clang-format-vsix: add command to format document

[amaiorano]

Summary

Bound to Ctrl+R, Ctrl+D by default. Also added section on how to debug the extension to the Readme.

[amaiorano]

My first patch accidentally included the changes from https://reviews.llvm.org/D27440

[hans]

tools/clang-format-vs/ClangFormat/ClangFormat.vsct

76

I think File would be better than Document when referring to source code.

But it seems a little annoying to need two menu alternatives. Could we make the regular "Clang Format" option just format the whole file if there is currently no selection, or would that be confusing?

[amaiorano]

tools/clang-format-vs/ClangFormat/ClangFormat.vsct

76

The reason I chose "Document" is that it mimics the existing functionality in Visual Studio:

As you can see, "Ctrl+K, Ctrl+F" is bound to format selection by default; which I assumed is the reason "Ctrl+R, Ctrl+F" was used for Clang Format (Selection). So along the same lines, I bound "Ctrl + R, Ctrl + D" to Clang Format Document.

I don't really have a problem with having multiple menu options, although we could have both of them underneath a "Clang Format" top menu, with "Format Selection" and "Format Document" as sub menu items.

As for annoyance in menus, I think most developers would reach for keyboard shortcuts in this case anyway. Furthermore, the next feature I want to add, building on top of this one, is allowing the user to enable "Format on Save", which would make this even easier to use.

[hans]

tools/clang-format-vs/ClangFormat/ClangFormat.vsct

76

I see, I didn't realize they call it documents. And if they also have separate commands for formating selection and formating the whole file, maybe that makes sense for us too.

Right, I also imagine folks would use this from the keyboard, but there too it's annoying to have two shortcuts for the same thing. But again, if that's how it's generally done in VS...

I'd like to hear from Manuel on this patch too, though.

[klimek]

tools/clang-format-vs/ClangFormat/ClangFormat.vsct

76

Clang-format currently formats the current line / statement if there is no selection, and that's how most people I know use it.
Formatting the whole file by default is not what clang-format is optimized for, and highly disruptive (eclipse does that, and it's annoying).
I'm more wondering why we need a setting for this at all - isn't ctrl-a,ctrl-k,ctrl-f equivalent to formatting the whole file?

[amaiorano]

(NOTE, I forgot to click Submit on the reply to @klimek yesterday)

tools/clang-format-vs/ClangFormat/ClangFormat.vsct

76

@klimek My own experience, which also seems to match those of others online, is that clang-format is a fantastic tool for making sure your code-base follows a strict formatting standard. What many people do is install Git pre-stage hooks, for instance, to run clang-format across entire source files, to ensure they're formatted properly. So even if it's not optimized for that, it works very well :)

Using clang-format to format only the current line doesn't guarantee that everything will be formatted accordingly. My own experience is that it sometimes formats the line differently than if you format the entire document. Or perhaps you end up writing a few lines of code, and formatting current line doesn't pick up all the lines you've modified. As for ctrl-a,ctrl-r-ctrl-f, the problem with it is that you lose your cursor position, as ctrl-a will place it at the end of the file.

You also mention that formatting the entire file is "highly disruptive" like in eclipse. I'm not sure how eclipse handles that, but so far VS seems to do a pretty good job. It manages to maintain breakpoint positions quite well, it manages to keep the cursor in the same place, and it manages to keep the relative location of the code where the cursor is at visible on screen. I suspect part of the reason it works well in VS is because Microsoft made sure it worked for their own format document feature (ctrl-k,ctrl-d).

As I mentioned earlier, this is a stepping stone towards adding a feature to "format on save", for which I'd like to offer the ability to choose "current line/selection" and "document". Here's an example of an extension that offers this feature, but for VS's built-in formatting.

[klimek]

LG. I also think it makes the code nicer by breaking out the right functions. Thanks!

tools/clang-format-vs/ClangFormat/ClangFormat.vsct

76

Note: with "highly disruptive" I meant only if the default behavior without any selection is to format the whole file, as that basically kills the workflow; that was what Hans suggested.

I'm not opposed to having an extra key binding if enough folks want it and there is enough benefit - the argument to not move your cursor is a good point.

[amaiorano]

tools/clang-format-vs/ClangFormat/ClangFormat.vsct

76

Thanks! Now I just need to get my svn submit working. Chris Latner created my account, etc. but when I tried to submit another accepted change, it didn't work. Anyway, will figure it out. Thanks again :)

tools/clang-format-vs/.gitignore

 # Visual Studio files
 .vs/
+*.user
 /packages/
 /ClangFormat/obj/
 /ClangFormat/bin/
 
 # Generated and copied files
 /ClangFormat/Key.snk
 /ClangFormat/license.txt
 /ClangFormat/clang-format.exe
 /ClangFormat/source.extension.vsixmanifest

tools/clang-format-vs/ClangFormat/ClangFormat.vsct

<Buttons>
       <!--To define a menu group you have to specify its ID, the parent menu and its display priority. 
           The command is visible and enabled by default. If you need to change the visibility, status, etc, you can use
           the CommandFlag node.
           You can add more than one CommandFlag node e.g.:
               <CommandFlag>DefaultInvisible</CommandFlag>
               <CommandFlag>DynamicVisibility</CommandFlag>
           If you do not want an image next to your command, remove the Icon node /> -->
 
-      <Button guid="guidClangFormatCmdSet" id="cmdidClangFormat" priority="0x0100" type="Button">
+      <Button guid="guidClangFormatCmdSet" id="cmdidClangFormatSelection" priority="0x0100" type="Button">
         <Parent guid="guidClangFormatCmdSet" id="MyMenuGroup" />
         <Icon guid="guidImages" id="bmpPic1" />
         <Strings>
-          <ButtonText>ClangFormat</ButtonText>
+          <ButtonText>Clang Format Selection</ButtonText>
         </Strings>
       </Button>
 
-
+      <Button guid="guidClangFormatCmdSet" id="cmdidClangFormatDocument" priority="0x0101" type="Button">
+        <Parent guid="guidClangFormatCmdSet" id="MyMenuGroup" />
+        <Icon guid="guidImages" id="bmpPic2" />
+        <Strings>
+          <ButtonText>Clang Format Document</ButtonText>
+        </Strings>
+      </Button>
 
     </Buttons>
    
     <!--The bitmaps section is used to define the bitmaps that are used for the commands.-->
     <Bitmaps>
       <!--  The bitmap id is defined in a way that is a little bit different from the others: 
             the declaration starts with a guid for the bitmap strip, then there is the resource id of the 
             bitmap strip containing the bitmaps and then there are the numeric ids of the elements used 
             inside a button definition. An important aspect of this declaration is that the element id 
             must be the actual index (1-based) of the bitmap inside the bitmap strip. -->
       <Bitmap guid="guidImages" href="Resources\Images_32bit.bmp" usedList="bmpPic1, bmpPic2, bmpPicSearch, bmpPicX, bmpPicArrows"/>
       
     </Bitmaps>
  
   </Commands>
 
 
   <KeyBindings>
-    <KeyBinding guid="guidClangFormatCmdSet" id="cmdidClangFormat" editor="guidTextEditor" key1="R" mod1="Control" key2="F" mod2="Control"/>
+    <KeyBinding guid="guidClangFormatCmdSet" id="cmdidClangFormatSelection" editor="guidTextEditor" key1="R" mod1="Control" key2="F" mod2="Control"/>
+    <KeyBinding guid="guidClangFormatCmdSet" id="cmdidClangFormatDocument" editor="guidTextEditor" key1="R" mod1="Control" key2="D" mod2="Control"/>
   </KeyBindings>
 
 
 
   <Symbols>
     <!-- This is the package guid. -->
     <GuidSymbol name="guidClangFormatPkg" value="{c5286038-25d3-4f65-83a8-51fa2df4a146}" />
     
     <!-- This is the guid used to group the menu commands together -->
     <GuidSymbol name="guidClangFormatCmdSet" value="{e39cbab1-0f96-4022-a2bc-da5a9db7eb78}">
 
       <IDSymbol name="MyMenuGroup" value="0x1020" />
-      <IDSymbol name="cmdidClangFormat" value="0x0100" />
+      <IDSymbol name="cmdidClangFormatSelection" value="0x0100" />
+      <IDSymbol name="cmdidClangFormatDocument" value="0x0101" />
     </GuidSymbol>
 
     <GuidSymbol name="guidTextEditor" value="{8B382828-6202-11d1-8870-0000F87579D2}" />
 
 
     <GuidSymbol name="guidImages" value="{6d53937b-9ae1-42e1-8849-d876dcdbad7b}" >
       <IDSymbol name="bmpPic1" value="1" />
       <IDSymbol name="bmpPic2" value="2" />
       <IDSymbol name="bmpPicSearch" value="3" />
       <IDSymbol name="bmpPicX" value="4" />
       <IDSymbol name="bmpPicArrows" value="5" />
     </GuidSymbol>
   </Symbols>
 
 </CommandTable>

tools/clang-format-vs/ClangFormat/ClangFormatPackage.cs

public sealed class ClangFormatPackage : Package
         #region Package Members
         protected override void Initialize()
         {
             base.Initialize();
 
             var commandService = GetService(typeof(IMenuCommandService)) as OleMenuCommandService;
             if (commandService != null)
             {
-                var menuCommandID = new CommandID(GuidList.guidClangFormatCmdSet, (int)PkgCmdIDList.cmdidClangFormat);
+                {
+                    var menuCommandID = new CommandID(GuidList.guidClangFormatCmdSet, (int)PkgCmdIDList.cmdidClangFormatSelection);
+                    var menuItem = new MenuCommand(MenuItemCallback, menuCommandID);
+                    commandService.AddCommand(menuItem);
+                }
+
+                {
+                    var menuCommandID = new CommandID(GuidList.guidClangFormatCmdSet, (int)PkgCmdIDList.cmdidClangFormatDocument);
                     var menuItem = new MenuCommand(MenuItemCallback, menuCommandID);
                     commandService.AddCommand(menuItem);
                 }
             }
+        }
         #endregion
 
         private void MenuItemCallback(object sender, EventArgs args)
         {
+            var mc = sender as System.ComponentModel.Design.MenuCommand;
+            if (mc == null)
+                return;
+
+            switch (mc.CommandID.ID)
+            {
+                case (int)PkgCmdIDList.cmdidClangFormatSelection:
+                    FormatSelection();
+                    break;
+
+                case (int)PkgCmdIDList.cmdidClangFormatDocument:
+                    FormatDocument();
+                    break;
+            }
+        }
+
+        /// <summary>
+        /// Runs clang-format on the current selection
+        /// </summary>
+        private void FormatSelection()
+        {
             IWpfTextView view = GetCurrentView();
             if (view == null)
                 // We're not in a text view.
                 return;
             string text = view.TextBuffer.CurrentSnapshot.GetText();
             int start = view.Selection.Start.Position.GetContainingLine().Start.Position;
             int end = view.Selection.End.Position.GetContainingLine().End.Position;
             int length = end - start;
+            
             // clang-format doesn't support formatting a range that starts at the end
             // of the file.
             if (start >= text.Length && text.Length > 0)
                 start = text.Length - 1;
             string path = GetDocumentParent(view);
             string filePath = GetDocumentPath(view);
-            try
-            {
-                var root = XElement.Parse(RunClangFormat(text, start, length, path, filePath));
-                var edit = view.TextBuffer.CreateEdit();
-                foreach (XElement replacement in root.Descendants("replacement"))
-                {
-                    var span = new Span(
-                        int.Parse(replacement.Attribute("offset").Value),
-                        int.Parse(replacement.Attribute("length").Value));
-                    edit.Replace(span, replacement.Value);
-                }
-                edit.Apply();
+
+            RunClangFormatAndApplyReplacements(text, start, length, path, filePath, view);
+        }
+
+        /// <summary>
+        /// Runs clang-format on the current document
+        /// </summary>
+        private void FormatDocument()
+            IWpfTextView view = GetCurrentView();
+            if (view == null)
+                // We're not in a text view.
+                return;
+
+            string filePath = GetDocumentPath(view);
+            var path = Path.GetDirectoryName(filePath);
+            string text = view.TextBuffer.CurrentSnapshot.GetText();
+
+            RunClangFormatAndApplyReplacements(text, 0, text.Length, path, filePath, view);
+
+        private void RunClangFormatAndApplyReplacements(string text, int offset, int length, string path, string filePath, IWpfTextView view)
+        {
+            try
+            {
+                string replacements = RunClangFormat(text, offset, length, path, filePath);
+                ApplyClangFormatReplacements(replacements, view);
             }
             catch (Exception e)
             {
                 var uiShell = (IVsUIShell)GetService(typeof(SVsUIShell));
                 var id = Guid.Empty;
                 int result;
                 uiShell.ShowMessageBox(
                         0, ref id,
public sealed class ClangFormatPackage : Package
                 // FIXME: If clang-format writes enough to the standard error stream to block,
                 // we will never reach this point; instead, read the standard error asynchronously.
                 throw new Exception(process.StandardError.ReadToEnd());
             }
             return output;
         }
 
         /// <summary>
+        /// Applies the clang-format replacements (xml) to the current view
+        /// </summary>
+        private void ApplyClangFormatReplacements(string replacements, IWpfTextView view)
+        {
+            // clang-format returns no replacements if input text is empty
+            if (replacements.Length == 0)
+                return;
+
+            var root = XElement.Parse(replacements);
+            var edit = view.TextBuffer.CreateEdit();
+            foreach (XElement replacement in root.Descendants("replacement"))
+            {
+                var span = new Span(
+                    int.Parse(replacement.Attribute("offset").Value),
+                    int.Parse(replacement.Attribute("length").Value));
+                edit.Replace(span, replacement.Value);
+            }
+            edit.Apply();
+        }
+
+        /// <summary>
         /// Returns the currently active view if it is a IWpfTextView.
         /// </summary>
         private IWpfTextView GetCurrentView()
         {
             // The SVsTextManager is a service through which we can get the active view.
             var textManager = (IVsTextManager)Package.GetGlobalService(typeof(SVsTextManager));
             IVsTextView textView;
             textManager.GetActiveView(1, null, out textView);

tools/clang-format-vs/ClangFormat/PkgCmdID.cs

 namespace LLVM.ClangFormat
 {
     static class PkgCmdIDList
     {
-        public const uint cmdidClangFormat = 0x100;
+        public const uint cmdidClangFormatSelection = 0x100;
+        public const uint cmdidClangFormatDocument = 0x101;
     };
 }
 No newline at end of file

tools/clang-format-vs/README.txt

 Once LLVM.sln is generated, build the clang_format_vsix target, which will build
 ClangFormat.sln, the C# extension application.
 
 The CMake build will copy clang-format.exe and LICENSE.TXT into the ClangFormat/
 directory so they can be bundled with the plug-in, as well as creating
 ClangFormat/source.extension.vsixmanifest. Once the plug-in has been built with
 CMake once, it can be built manually from the ClangFormat.sln solution in Visual
 Studio.
+
+===========
+ Debugging
+===========
+
+Once you've built the clang_format_vsix project from LLVM.sln at least once,
+open ClangFormat.sln in Visual Studio, then:
+
+- Make sure the "Debug" target is selected
+- Open the ClangFormat project properties
+- Select the Debug tab
+- Set "Start external program:" to where your devenv.exe is installed. Typically
+  it's "C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\devenv.exe"
+- Set "Command line arguments" to: /rootsuffix Exp
+- You can now set breakpoints if you like
+- Press F5 to build and run with debugger
+
+If all goes well, a new instance of Visual Studio will be launched in a special
+mode where it uses the experimental hive instead of the normal configuration hive.
+By default, when you build a VSIX project in Visual Studio, it auto-registers the
+extension in the experimental hive, allowing you to test it. In the new Visual Studio
+instance, open or create a C++ solution, and you should now see the Clang Format
+entries in the Tool menu. You can test it out, and any breakpoints you set will be
+hit where you can debug as usual.