使用 Clang Tools —— ClangFormat

ClangFormat

1. 独立的工具
2. Vim 集成
3. Emacs 集成
4. BBEdit 集成
5. CLion 集成
6. Visual Studio 集成
7. 用于补丁重新格式化的脚本(Script for patch reformatting)

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

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 thisfilename to look for a style config file (with-style=file) and to determine the language.-cursor=<uint>            - The position of the cursor when invokingclang-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 afallback in case clang-format is invoked with-style=file, but can not find the .clang-formatfile 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 specifyingseveral -offset and -length pairs.When only a single -offset is specified without-length, clang-format will format up to the endof the file.Can only be used with one input file.-lines=<string>           - <start line>:<end line> - format a range oflines (both 1-based).Multiple ranges can be formatted by specifyingseveral -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 specifyingseveral -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 parentdirectories of the source file (or currentdirectory for stdin).Use -style="{key: value, ...}" to set specificparameters, e.g.:-style="{BasedOnStyle: llvm, IndentWidth: 8}"-verbose                  - If set, shows the list of processed filesGeneric 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 = 1pyf ~/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（脚本也将格式化这些行）。