使用 Clang Tools —— ClangFormat

本文为译文，点击 此处查看原文。

ClangFormat描述了一组构建在 LibFormat 之上的工具。它可以以多种方式支持您的工作流，包括一个独立的工具和编辑器集成。

1. 独立的工具

clang-format位于clang/tools/clang-format中，可用于格式化C/C++/Java/JavaScript/Objective-C/Protobuf/C#代码。

$ clang-format -help
OVERVIEW: A tool to format C/C++/Java/JavaScript/Objective-C/Protobuf/C# code.

If no arguments are specified, it formats the code from standard input
and writes the result to the standard output.
If <file>s are given, it reformats the files. If -i is specified
together with <file>s, the files are edited in-place. Otherwise, the
result is written to the standard output.

USAGE: clang-format [options] [<file> ...]

OPTIONS:

Clang-format options:

  -assume-filename=<string> - When reading from stdin, clang-format assumes this
                              filename to look for a style config file (with
                              -style=file) and to determine the language.
  -cursor=<uint>            - The position of the cursor when invoking
                              clang-format from an editor integration
  -dump-config              - Dump configuration options to stdout and exit.
                              Can be used with -style option.
  -fallback-style=<string>  - The name of the predefined style used as a
                              fallback in case clang-format is invoked with
                              -style=file, but can not find the .clang-format
                              file to use.
                              Use -fallback-style=none to skip formatting.
  -i                        - Inplace edit <file>s, if specified.
  -length=<uint>            - Format a range of this length (in bytes).
                              Multiple ranges can be formatted by specifying
                              several -offset and -length pairs.
                              When only a single -offset is specified without
                              -length, clang-format will format up to the end
                              of the file.
                              Can only be used with one input file.
  -lines=<string>           - <start line>:<end line> - format a range of
                              lines (both 1-based).
                              Multiple ranges can be formatted by specifying
                              several -lines arguments.
                              Can't be used with -offset and -length.
                              Can only be used with one input file.
  -offset=<uint>            - Format a range starting at this byte offset.
                              Multiple ranges can be formatted by specifying
                              several -offset and -length pairs.
                              Can only be used with one input file.
  -output-replacements-xml  - Output replacements as XML.
  -sort-includes            - Sort touched include lines
  -style=<string>           - Coding style, currently supports:
                                LLVM, Google, Chromium, Mozilla, WebKit.
                              Use -style=file to load style configuration from
                              .clang-format file located in one of the parent
                              directories of the source file (or current
                              directory for stdin).
                              Use -style="{key: value, ...}" to set specific
                              parameters, e.g.:
                                -style="{BasedOnStyle: llvm, IndentWidth: 8}"
  -verbose                  - If set, shows the list of processed files

Generic Options:

  -help                     - Display available options (-help-hidden for more)
  -help-list                - Display list of available options (-help-list-hidden for more)
  -version                  - Display the version of this program

当所需的代码格式化样式与可用选项不同时，可以使用 -style="{key: value, ...}" 选项；或者将样式配置放在您的项目目录中的.clang-format或_clang-format文件中，并使用clang-format -style=file，以自定义样式。

创建 .clang-format 文件的一个简单方法是：

clang-format -style=llvm -dump-config > .clang-format

在 Clang-Format 样式选项中描述了可用的样式选项。

2. Vim 集成

这里有为vim设计的一个集成，允许您在当前缓冲区上运行clang-format独立工具，可以选择要重新格式化的区域。该集成具有一个python文件的形式，可以在clang/tools/clang-format/clang-format.py中找到。
这可以通过在您的.vimrc中添加以下内容来集成：

map <C-K> :pyf <path-to-this-file>/clang-format.py<cr>
imap <C-K> <c-o>:pyf <path-to-this-file>/clang-format.py<cr>

第一行启用clang-format以支持NORMAL模式和VISUAL模式，第二行添加了对INSERT模式的支持。如果需要在一个不同的键上使用clang-format （C-K 代表 Ctrl+k），则将“C-K”更改为另一个绑定。
通过这种集成，您可以按下绑定键，clang-format将以NORMAL模式和INSERT模式格式化当前行，并以VISUAL模式格式化选择区域。行或区域被扩展到下一个更大的语法实体。
它对当前可能未保存的缓冲区进行操作，不创建或保存任何文件。要还原格式，只需撤消即可。

另一种选择是在保存一个文件时更改格式，从而在编码工作流中实现一个零工作量的集成。要做到这一点，请将以下内容添加到您的.vimr：

function! Formatonsave()
  let l:formatdiff = 1
  pyf ~/llvm/tools/clang/tools/clang-format/clang-format.py
endfunction
autocmd BufWritePre *.h,*.cc,*.cpp call Formatonsave()

3. Emacs 集成

与vim的集成类似，也有为emacs设计的一个集成。它可以在clang/tools/clang-format/clang-format.el中找到，并将以下内容添加到您的.emacs来使用这个集成：

(load "<path-to-clang>/tools/clang-format/clang-format.el")
(global-set-key [C-M-tab] 'clang-format-region)

这将函数clang-format-region绑定到C-M-tab，然后将格式化当前行或选中区域。

4. BBEdit 集成

clang-format不能与BBEdit一起用作一个文本过滤器，但是通过一个脚本可以很好地工作。实现此集成的AppleScript可以在clang/tools/clang-format/clang-format-bbedit.applescript中找到；在~/Library/Application Support/BBEdit/Scripts中放置一个副本，并编辑其中的path以指向您的clang-format的本地副本。
通过这种集成，您可以从Script菜单中选择脚本，并且clang-format将对选择进行格式化。注意，您可以通过重命名脚本来重命名菜单项，并且可以在Menus & Shortcuts下的BBEdit首选项中为菜单项分配键盘快捷方式。

5. CLion 集成

clang-format作为一种可选的代码格式化程序集成到CLion中。它在默认情况下是禁用的，可以在Settings/Preferences | Editor | Code Style中打开。
如果启用了clang-format支持，CLion会在打开一个项目时检测配置文件，并建议覆盖当前 IDE 设置。然后将.clang-format文件中的代码样式规则自动应用于所有编辑器操作，包括自动完成(auto-completion)、代码生成(code generatio)和重构(refactorings)。

6. Visual Studio 集成

从 alpha构建站点下载最新的 Visual Studio 扩展。默认的绑定键是 Ctrl-R、Ctrl-F。

7. 用于补丁重新格式化的脚本(Script for patch reformatting)

这个python脚本lang/tools/clang-format/clang-format-diff.py解析一个统一的 diff 的输出，并用clang-format重新格式化所有包含的行。

usage: clang-format-diff.py [-h] [-i] [-p NUM] [-regex PATTERN] [-style STYLE]

Reformat changed lines in diff. Without -i option just output the diff that
would be introduced.

optional arguments:
  -h, --help      show this help message and exit
  -i              apply edits to files instead of displaying a diff
  -p NUM          strip the smallest prefix containing P slashes
  -regex PATTERN  custom pattern selecting file paths to reformat
  -style STYLE    formatting style to apply (LLVM, Google, Chromium, Mozilla,
                  WebKit)

因此，要重新格式化最新 git 提交中的所有行，只需：

git diff -U0 --no-color HEAD^ | clang-format-diff.py -i -p1

使用 Mercurial/hg：

hg diff -U0 --color=never | clang-format-diff.py -i -p1

在一个 SVN 客户端中，你可以这样做：

svn diff --diff-cmd=diff -x -U0 | clang-format-diff.py -i

选项-U0将创建一个没有上下文行的 diff（脚本也将格式化这些行）。