clangformat.vroom

The built-in clang-format formatter knows how to format code for C/C++ and many
C-like languages.
If you aren't familiar with basic codefmt usage yet, see main.vroom first.

We'll set up codefmt and configure the vroom environment, then jump into some
examples. If you haven't seen the setup code below yet, read through main.vroom
briefly.

  :source $VROOMDIR/setupvroom.vim

  :let g:repeat_calls = []
  :function FakeRepeat(...)<CR>
  |  call add(g:repeat_calls, a:000)<CR>
  :endfunction
  :call maktaba#test#Override('repeat#set', 'FakeRepeat')

  :call codefmt#SetWhetherToPerformIsAvailableChecksForTesting(0)


The clang-format formatter expects the clang-format executable to be installed
on your system.

  % f();
  :FormatCode clang-format
  ! clang-format --version .*
  $ clang-format version 3.7.0 (tags/testing)
  ! clang-format .*
  $ { "Cursor": 0 }
  $ f();

Notice the "clang-format --version" syscall. The clang-format formatter checks
the version of the clang-format executable to detect what features it supports.
It caches the result, so it only does this once per vim session.  We'll take a
closer look at that below.

Any time this flag is changed, the cached version is invalidated and checked
fresh on the next format invocation.  The name or path of the clang-format
executable can be configured via the clang_format_executable flag if the
default of "clang-format" doesn't work.

  :Glaive codefmt clang_format_executable='clang-format-3.9'
  :FormatCode clang-format
  ! clang-format-3.9 --version .*
  $ clang-format version 3.9.0 (tags/testing)
  ! clang-format-3.9 .*
  $ { "Cursor": 0 }
  $ f();
  :Glaive codefmt clang_format_executable='clang-format'
  :FormatCode clang-format
  ! clang-format --version .*
  $ clang-format version 3.9.0 (tags/testing)
  ! clang-format .*
  $ { "Cursor": 0 }
  $ f();


You can format any buffer with clang-format specifying the formatter explicitly.

  @clear
  % void f() {int i; SomeFunction(parameter,// comment<CR>
  |i);}

  :FormatCode clang-format
  ! clang-format -style file .*2>.*
  $ { "Cursor": 0 }
  $ void f() {
  $   int i;
  $   SomeFunction(parameter,  // comment
  $                i);
  $ }
  void f() {
    int i;
    SomeFunction(parameter,  // comment
                 i);
  }
  @end

Several filetypes will use the clang-format formatter by default: c, cpp, and
proto.

  @clear
  % f();

  :set filetype=cpp
  :FormatCode
  ! clang-format .*
  $ { "Cursor": 0 }
  $ f();

  :set filetype=proto
  :FormatCode
  ! clang-format .*
  $ { "Cursor": 0 }
  $ f();

It will also format javascript and java, but is not necessarily the default if
other formatters are available.
Note: Formatting java requires clang-format >= 3.6.

  :set filetype=javascript
  :FormatCode clang-format
  ! clang-format .*
  $ { "Cursor": 0 }
  $ f();

  :set filetype=java
  :FormatCode clang-format
  ! clang-format .*
  $ { "Cursor": 0 }
  $ f();

  :set filetype=

It can format specific line ranges of code using :FormatLines.

  @clear
  % void f() {<CR>
  |  int i = 2+2;<CR>
  |  int i = 3+3;<CR>
  |  int i = 4+4;<CR>
  |}

  :3,4FormatLines clang-format
  ! clang-format -style file -lines 3:4 .*2>.*
  $ { "Cursor": 0 }
  $ void f() {
  $   int i = 2+2;
  $   int i = 3 + 3;
  $   int i = 4 + 4;
  $ }
  void f() {
    int i = 2+2;
    int i = 3 + 3;
    int i = 4 + 4;
  }
  @end

Note this will usually maintain cursor position correctly even when the code
under the cursor moves. See clangformat-cursor.vroom for examples.

You might have wondered where the "-style file" above comes from. The
clang-format tool accepts a "style" option to control the formatting style. By
default, "file" is used to indicate that clang-format should respect
configuration in a .clang-format file in the project directory. You can control
how style is selected via the clang_format_style flag. This flag accepts either
a string value to use everywhere...

  :Glaive codefmt clang_format_style='WebKit'

  @clear
  % f();
  :FormatCode clang-format
  ! clang-format -style WebKit .*2>.*
  $ { "Cursor": 0 }
  $ f();

...or a callable that takes no arguments and returns a string style name for the
current buffer.

  :function MaybeWebkitStyle()<CR>
  |  if stridx(expand('%:p'), '/WebKit/') != -1<CR>
  |    return 'WebKit'<CR>
  |  endif<CR>
  |  return 'file'<CR>
  |endfunction
  :Glaive codefmt clang_format_style=`function('MaybeWebkitStyle')`

  :silent file /foo/WebKit/foo.cc
  :FormatCode clang-format
  ! clang-format -style WebKit -assume-filename .*foo.cc .*2>.*
  $ { "Cursor": 0 }
  $ f();

  :silent file /foo/foo.cc
  :FormatCode clang-format
  ! clang-format -style file -assume-filename .*foo.cc .*2>.*
  $ { "Cursor": 0 }
  $ f();

  :Glaive codefmt clang_format_style='file'

The -assume-filename arg passed above is also related, used by the clang-format
tool to detect any custom style rules particular to the current file.


Bug #102. When the buffer is empty, clang-format does _not_ return a cursor
position

  @clear
  :FormatCode clang-format