CLang-Format格式化工具

一、简述

Clang-Format是基于 clang 的一个命令行工具,这个工具能够自动化格式C/C++/Obj-C代码,支持多种代码风格(Google, Chromium, LLVM, Mozilla, WebKit),同时也支持自定义风格(通过编写.clang-format文件);

二、安装方式

# mac
brew install clang-format

三、参数解析

官方文档的参数解析为:http://clang.llvm.org/docs/ClangFormatStyleOptions.html

3.1 参数解析

BasedOnStyle样式信息:

3.2 详细参数信息

---
# 语言
Language: Cpp
# BasedOnStyle: LLVM
#类的访问修饰关键字(private,public,protected···)缩进
# private:
# int a;
# 1表示不缩进
# 大于1的值表示访问修饰关键字的左侧从int a的左侧列开始往右侧移动的距离
AccessModifierOffset: -2
# 在未封闭(括号的开始和结束不在同一行)的括号中的代码是否对齐
# if(a &;&;
#b)
#
AlignAfterOpenBracket: Align
# 多行赋值语句按 = 号对齐
AlignConsecutiveAssignments: false
# 多行声明语句按 = 号对齐
AlignConsecutiveDeclarations: false
# (EscapedNewlineAlignmentStyle)用于在转义换行符中对齐反斜杠的选项,可能的值如下所示:
AlignEscapedNewlines: Right
+ ENAS_DontAlign:在配置DontAlign中不要对齐转义的换行符;
+ ENAS_Left:在配置Left中尽可能向左对齐转义的换行符;
+ ENAS_Right:在配置Right中对齐最右列中的转义换行符
# (bool)是否水平对齐二进制和三元表达式的操作数
AlignOperands: true
# 是否把注释右对齐,下面为右对齐的效果
#void someFunction() {
#doWork(); // Does something
#doMoreWork(); // Does something else
#}
AlignTrailingComments: true
# (bool)是否允许将函数声明的所有参数放到下一行(BinPackParameters为false不影响该参数)
AllowAllParametersOfDeclarationOnNextLine: true
# 是否允许短代码块在一行写完
# 如 if (a) { return; }
AllowShortBlocksOnASingleLine: false
# 是否允许短switch的case 语句在一行写完
AllowShortCaseLabelsOnASingleLine: false
# 是否允许短的函数在一行写完
AllowShortFunctionsOnASingleLine: All
# 是否允许短的语句在一行写完
AllowShortIfStatementsOnASingleLine: false
# 是否允许短的循环在一行写完,如果为真(true), 语句“while (true) continue;” 能被放到单行
AllowShortLoopsOnASingleLine: false
# 用于函数定义返回类型换行样式,这个选项是过时的并且被保留向后兼容(可选值如下所示)
AlwaysBreakAfterDefinitionReturnType: None
+ DRTBS_None (在配置中: None) 再返回类型后自动换行,PenaltyReturnTypeOnItsOwnLine 会被考虑到;
+ DRTBS_All (在配置中: All) 总是在返回类型后换行;
+ DRTBS_TopLevel (在配置中: TopLevel) 总是在返回类型的顶级函数后换行;
# 用于函数声明返回类型换行样式(可选值如下所示)
AlwaysBreakAfterReturnType: None
+ RTBS_None (在配置中: None) 在返回类型后自动换行。“PenaltyReturnTypeOnItsOwnLine”会被考虑.
+ RTBS_All (在配置中: All) 再返回类型后总是换行;
+ RTBS_TopLevel (在配置中: TopLevel) 在方法的顶层的返回类型后总是换行;
+ RTBS_AllDefinitions (在配置中: AllDefinitions) 在方法定义中的返回类型后总是换行;
+ RTBS_TopLevelDefinitions (在配置中: TopLevelDefinitions) 在顶层定义的返回类型后总是换行
# 使在文件中有多行字符串的情况看起来更一致。因此,如果字符串被“ContinuationIndentWidth”空格导致换行,它将会在行首生效。如果为真(true), 在多行字面量字符串前总是换行
AlwaysBreakBeforeMultilineStrings: false
AlwaysBreakTemplateDeclarations: MultiLine
# 如果为假(false), 函数调用的参数要么是在同一行上,要么将在同一行上有一行
BinPackArguments: true
# 如果为假(false), 函数声明或函数定义的参数将都在同一行上,或各有一行
BinPackParameters: true
# 控制单独的大括号换行事件,如果“BreakBeforeBraces”设置为“BS_Custom”, 使用这个指定如何处理每个单独的括号的情况。否则,这是被忽略的嵌套结构的标志
BraceWrapping:
# 使类定义换行
AfterClass: false
# 使控制语句(if/for/while/switch/..)换行
AfterControlStatement: false
# 使枚举定义换行
AfterEnum: false
# 使方法定义换行
AfterFunction: false
# 使命名空间定义换行
AfterNamespace: false
# 使OC定义(@autoreleasepool, interfaces, ..)换行
AfterObjCDeclaration: false
# 使结构体定义换行
AfterStruct: false
# 使共同体定义换行
AfterUnion: false
AfterExternBlock: false
# 在catch之前换行
BeforeCatch: false
# 在else之前换行
BeforeElse: false
# 缩进换行的大括号
IndentBraces: false
SplitEmptyFunction: true
SplitEmptyRecord: true
SplitEmptyNamespace: true
# 在二元运算符前断行
BreakBeforeBinaryOperators: None
# 括号的断行模式
BreakBeforeBraces: Attach
BreakBeforeInheritanceComma: false
BreakInheritanceList: BeforeColon
# 在三元运算符前断行
BreakBeforeTernaryOperators: true
# 在构造函数初始化时按逗号断行,并以冒号对齐
BreakConstructorInitializersBeforeComma: false
BreakConstructorInitializers: BeforeColon
BreakAfterJavaFieldAnnotations: false
# 当格式化时,总是对字面量字符串换行
BreakStringLiterals: true
# 最大宽度,如果代码超过这个宽度会按语义折行
ColumnLimit: 80
# 一个固定的表达式,它描述了具有特殊意义的注释,不应该被分裂成行或以其他方式改变
CommentPragmas: '^ IWYU pragma:'
CompactNamespaces: false
# 如果构造函数初始化器不适合在一行,把每个初始化放到单独的行
ConstructorInitializerAllOnOneLineOrOnePerLine: false
# 使用构造函数初始化列表缩进的字符数
ConstructorInitializerIndentWidth: 4
# 在续行(/下一行)时的缩进长度
ContinuationIndentWidth: 4
Cpp11BracedListStyle: true
DerivePointerAlignment: false
# 禁用当前format文件
DisableFormat: false
# 如果为真(true), clang-format检测函数调用和定义格式化为每行一个参数。每个调用都可以被包装,每行一个或不确定的。如果是不确定的,例如完全在一行,但需要做出一个决定,clang-format分析文件中是否有其他被包装的事例和相应的行动。
# 注意:这是一个实验标志,可能会消失或被重命名。不要在配置文件中使用。你自己要为你的使用负责
ExperimentalAutoDetectBinPacking: false
FixNamespaceComments: true
# 一个宏,应解释为foreach循环而不是作为函数调用矢量
ForEachMacros:
- foreach
- Q_FOREACH
- BOOST_FOREACH
IncludeBlocks: Preserve
# 正则表达式表示不同的#include类别被用于#includes命令,这些正则表达式与一个包含(包括< >或“)的文件的文件名相匹配。属于第一匹配正则表达式的值被分配,并且#include首先根据增加类别数然后在每个类别按字母的顺序排序。如果正则表达式都不匹配,int_max分配类别。源文件的主要头引用自动获取类别0。因此,它通常是保持在#include开头(http://llvm.org/docs/CodingStandards.html#include-style)。然而,如果你有总是需要排在首位的头引用,你也可以分配负面的优先事项。为了在.clang-format文件中配置这个, 请使用
IncludeCategories:
- Regex: '^"(llvm|llvm-c|clang|clang-c)/'
Priority: 2
- Regex: '^(<|"(gtest|gmock|isl|json)/)'
Priority: 3
- Regex: '.*'
Priority: 1
# 指定一个常用的可以在文件主要包括映射的正则表达式的表达式,在猜测是否#include是“main”include(指定类别0,见上文),使用这个正则表达式允许后缀的头引用源。部分匹配完成,所以说:-“”意思是任意后缀,-“$”的意思是没有后缀,例如,如果配置”(_test)?$”,然后.h将被视为包括在a.cc和a_test.ccde中的“main”。
IncludeIsMainRegex: '(Test)?$'
# case语句的位置总是在switch语句后缩进一级
IndentCaseLabels: false
IndentPPDirectives: None
# 用于缩进的列数
IndentWidth: 2
# 缩进如果函数定义或声明后包的类型
IndentWrappedFunctionNames: false
# JavaScriptQuotes中可能的值如下所示
JavaScriptQuotes: Leave
+ JSQS_Leave (在配置中: Leave) 留下字符串原本的括号;
+ JSQS_Single (在配置中: Single) 总是使用单括号;
+ JSQS_Double (在配置中: Double) 总是使用双括号
JavaScriptWrapImports: true
# 在block从空行开始
KeepEmptyLinesAtTheStartOfBlocks: true
# block开始的正则
MacroBlockBegin: ''
# block开始的正则
MacroBlockEnd: ''
# 允许最大连续空行数
MaxEmptyLinesToKeep: 1
# 命名空间缩进
NamespaceIndentation: None
ObjCBinPackProtocolList: Auto
# block内的缩进
ObjCBlockIndentWidth: 2
# 是否需要在"@property"后加上空格
ObjCSpaceAfterProperty: false
# 是否需要在协议名后加上空格
ObjCSpaceBeforeProtocolList: true
PenaltyBreakAssignment: 2
# 在调用小括号“(”后给一个方法调用换行的处罚
PenaltyBreakBeforeFirstCallParameter: 19
# 包含在一个注释中的每一个换行的处罚
PenaltyBreakComment: 300
# 在第一个“<<”前的换行的处罚
PenaltyBreakFirstLessLess: 120
# 包含一个字面量的字符串中的每一个换行的处罚
PenaltyBreakString: 1000
PenaltyBreakTemplateDeclaration: 10
# 最多能超出ColumnLimit多少个字符
PenaltyExcessCharacter: 1000000
# 把一个方法返回类型放到函数的同一行
PenaltyReturnTypeOnItsOwnLine: 60
# 指针在类型那边还是在变量名那边还是在中间
PointerAlignment: Right
# 如果为真(true), clang-format 将会尝试将注释重新流布局
ReflowComments: true
# 如果为真(true), clang-format 将会分类#includes
SortIncludes: true
SortUsingDeclarations: true
# 如果为真(true), 可能在一个C样式描述后插入一个空格
SpaceAfterCStyleCast: false
# 如果为真(true), 在“template”关键字后插入一个空格
SpaceAfterTemplateKeyword: true
# 如果为假(false),移除分配操作符(=)前空格
SpaceBeforeAssignmentOperators: true
SpaceBeforeCpp11BracedList: false
SpaceBeforeCtorInitializerColon: true
SpaceBeforeInheritanceColon: true
# 是否在括号前加上空格
SpaceBeforeParens: ControlStatements
SpaceBeforeRangeBasedForLoopColon: true
# 是否在空括号中加空格
SpaceInEmptyParentheses: false
# 单行注释前的空格数
SpacesBeforeTrailingComments: 1
# 是否在<>中间插入空格
SpacesInAngles: false
# 是否在容器字面量(@[@"1",@"2"])中插入空格
SpacesInContainerLiterals: true
# 如果为真(true), 将会在C样式描述中插入空格
SpacesInCStyleCastParentheses: false
# 是否在非空的括号中插入空格
SpacesInParentheses: false
# 如果为真(true),将会在“[”之后和“]”之前插入空格
SpacesInSquareBrackets: false
# 用这个标准格式化:例如:在LS_Cpp03中使用 A<A<int> > 而不是 A<A<int>>(可能的值如下所示)
+ LS_Cpp03 (在配置中: Cpp03) 使用Use C++03统一语法;
+ LS_Cpp11 (在配置中: Cpp11) 使用C++11的特征(例如 A<A<int>>而不是A<A<int> >);
+ LS_Auto (在配置中: Auto) 基于输入自动检查;
Standard: Cpp11
# tab的缩进空格数
TabWidth: 8
# 在结果文件中使用制表符字符的方式可能的值如下所示)
UseTab: Never
+ UT_Never (在配置中: Never) 从不使用制表符;
+ UT_ForIndentation (在配置中: ForIndentation) 仅缩排时使用制表符;
+ UT_Always (在配置中: Always) 使用标签时,我们需要填补的空白,至少从一个制表位到下一个;
...

四、编辑器集成

编辑器在vscode上面的集成信息

Author: bugwz
Link: https://bugwz.com/2019/01/08/clang-format/
Copyright Notice: All articles in this blog are licensed under CC BY-NC-SA 4.0 unless stating additionally.