更新日志:
2017/07/12 10:17 更新至
一种获取可用的
.clang-format
文件并囊括预定义风格的全部配置选项的简单方法:
2017/07/13 0:34 更新至
AlignConsecutiveDeclarations (
bool
)
2017/07/15 0:34 更新至
BinPackParameters(
bool
)
原文地址:http://clang.llvm.org/docs/ClangFormatStyleOptions.html
Clang-Format Style Options
Clang-Format Style Options 描述了可配置的格式样式选项,由LibFormat 和 ClangFormat提供支持.
当在命令行下使用clang-format工具或代码中的clang::format::reformat(...)
函数,可以使用已定义好的代码样式(LLVM, Google, Chromium, Mozilla, WebKit)或者通过配置特定的样式选项创建自定义样式.
#### clang-format的配置样式
clang-format支持两种自定义样式选项:通过-style=
命令行直接指定样式配置,或者使用-style=file
并将样式配置放在项目目录下的.clang-format
或_clang-format
文件中.
当使用-style=file
时,clang-format会为每个输入文件尝试在就近的上级目录查找.clang-format
文件.当使用标准输入时,查找从当前目录开始.
.clang-format
使用YAML样式:
key1: value1
key2: value2
# A comment.
...
该配置文件由多个部分组成,每部分都有不同的Language:
参数说明该部分针对的编程语言.参阅下面的语言选项描述,以获得支持的语言列表.第一部分可能没有语言集,将对所有语言使用默认格式选项.对特定语言的配置将覆盖默认的配置选项.
当clang-format
格式化一个文件,它会通过文件名自动检测语言.当使用标准输入或一个没有相应其语言的扩展的文件,-assume-filename=
选项可以用于覆盖文件名使clang-format
自动获取语言.
一个针对多语言的配置文件样例
---
# We'll use defaults from the LLVM style, but with 4 columns indentation.
BasedOnStyle: LLVM
IndentWidth: 4
---
Language: Cpp
# Force pointers to the type for C++.
DerivePointerAlignment: false
PointerAlignment: Left
---
Language: JavaScript
# Use 100 columns for JS.
ColumnLimit: 100
---
Language: Proto
# Don't format .proto files.
DisableFormat: true
...
一种获取可用的.clang-format
文件并囊括预定义风格的全部配置选项的简单方法:
clang-format -style=llvm -dump-config > .clang-format
当使用-style=
选项自定义配置时,将对所有输入文件以同样的样式生效. 自定义配置的格式如下:
-style='{key1: value1, key2: value2, ...}'
对一段代码禁用格式化
Clang-format同样支持用特殊的注释对一段限定范围的代码切换样式.在注释//clang-format off
(或/* clang-format off */
)和//clang-format on
(或/* clang-format on */
)之间的代码将不会被格式化.注释本身依旧会被格式化(对齐).
int formatted_code;
// clang-format off
void unformatted_code ;
// clang-format on
void formatted_code_again;
在代码中配置样式
当使用clang::format::reformat(...)
等函数时,格式样式将通过使用clang::format::FormatStyle
来指定
可配置的格式样式选项
该部分将列出支持的样式选项.每个选项可被指定值类型.对于枚举类型,值可能被指定为c++枚举成员(带前缀,比如LS_Auto),以及在配置中可用的值(不带前缀的Auto).
BasedOnStyle(string
)
该样式用于除被专门设定的之外的选项样式.
该选项只在clang-format配置中支持(-style={}
和.clang-format
文件均可).
可取的值:
- LLVM 将使用LLVM代码标准的样式
- Google 将使用Google C++代码指南的样式
- Chromium 将使用Chromium代码指南的样式
- Mozilla 将使用Mozilla代码指南的样式
- WebKit 将使用WebKit代码指南的样式
AccessModifierOffset(int
)
访问修饰符的缩进或凸出,如public
AlignAfterOpenBracket (BracketAlignmentStyle
)
若真,在开括号后保持水平对齐.
这适用于圆括号(括号),尖括号和方括号.
可取的值:
BAS_Align
(在配置中为Align
)参数根据开括号对齐,如下
someLongFunction(argument1,
argument2);
BAS_DontAlign
(在配置中为DontAlign
)不对齐,使用ContinuationIndentWidth
,如下
someLongFunction(argument1,
argument2);
BAS_AlwaysBreak
(在配置中为AlwaysBreak
) 若参数不适合一行,将在开括号换行,如下
someLongFunction(
argument1, argument2);
AlignConsecutiveAssignments (bool
)
若true
,则对齐连续赋值运算符.
这将对齐连续多行的赋值运算符.效果如下:
int aaaa = 12;
int b = 23;
int ccc = 23;
AlignConsecutiveDeclarations (bool
)
若true
,则对齐连续声明.
这将对齐连续多行的声明变量名.效果如下:
int aaaa = 12;
float b = 23;
std::string ccc = 23;
AlignEscapedNewlines (EscapedNewlineAlignmentStyle
)
换行符()的选项
可取的值:
ENAS_DontAlign
(在配置中为DontAlign
) 换行符()不对齐
#define A \
int aaaa; \
int b; \
int dddddddddd;
ENAS_Left
(在配置中为Left
) 换行符()尽量左对齐
true:
#define A \
int aaaa; \
int b; \
int dddddddddd;
false:
ENAS_Right
(在配置中为Right
) 换行符()尽量右对齐
#define A \
int aaaa; \
int b; \
int dddddddddd;
AlignOperands (bool
)
若true
,则水平对齐二目运算符和三目运算符的操作数
具体地说,这将单行表达式拆分成多行对齐,如下:
int aaa = bbbbbbbbbbbbbbb +
ccccccccccccccc;
AlignTrailingComments (bool
)
若true
,则对齐注释
true: false:
int a; // My comment a vs. int a; // My comment a
int b = 2; // comment b int b = 2; // comment about b
AllowAllParametersOfDeclarationOnNextLine (bool)
在函数声明中允许将所有参数放下一行,除非为false
.
true: false:
myFunction(foo, vs. myFunction(foo, bar, plop);
bar,
plop);
AllowShortBlocksOnASingleLine (bool
)
允许将简单语句放置在一行中
样例: if (a) { return; }
将在一行
AllowShortCaseLabelsOnASingleLine (bool
)
若true
,则会将简单的case代码压缩在一行
true: false:
switch (a) { vs. switch (a) {
case 1: x = 1; break; case 1:
case 2: return; x = 1;
} break;
case 2:
return;
}
AllowShortFunctionsOnASingleLine (ShortFunctionStyle
)
根据取值, int f() { return 0; }
可能在单独一行.
可取的值:
SFS_None
(在配置中为None
) 不将函数合并在一行SFS_InlineOnly
(在配置中为InlineOnly
) 只合并在类内定义的函数和inline
函数,不合并空函数: 举例,顶级空函数也不会被合并
class Foo {
void f() { foo(); }
};
void f() {
foo();
}
void f() {
}
SFS_Empty
(在配置中为Empty
) 只合并空函数
void f() {}
void f2() {
bar2();
}
SFS_Inline
(在配置中为Inline
) 只合并类内函数及空函数
class Foo {
void f() { foo(); }
};
void f() {
foo();
}
void f() {}
SFS_All
(在配置中为All
) 将所有函数都合并在一行
class Foo {
void f() { foo(); }
};
void f() { bar(); }
AllowShortIfStatementsOnASingleLine (bool
)
若true
, if (a) return;
将在一行
AllowShortLoopsOnASingleLine (bool
)
若true
, while (true) continue;
将在一行
AlwaysBreakAfterDefinitionReturnType (DefinitionReturnTypeBreakingStyle
)
函数声明中返回类型单独一行.该选项是弃用的,并保留作为向后兼容.
可取的值:
DRTBS_None
(在配置中为None
) 返回类型后自动换行,但会受PenaltyReturnTypeOnItsOwnLine
选项的影响.DRTBS_All
(在配置中为All
) 返回类型后总是换行DRTBS_TopLevel
(在配置中为TopLevel
)顶层函数的返回类型后总是换行
AlwaysBreakAfterReturnType (ReturnTypeBreakingStyle
)
函数定义中返回类型的样式风格
可取的值:
RTBS_None
(在配置中为None
) 返回类型后自动换行,但会受PenaltyReturnTypeOnItsOwnLine
选项的影响
class A {
int f() { return 0; };
};
int f();
int f() { return 1; }
RTBS_All
(在配置中为All
) 返回类型后总是换行
class A {
int
f() {
return 0;
};
};
int
f();
int
f() {
return 1;
}
RTBS_TopLevel
(在配置中为TopLevel
) 顶层函数的返回类型后总是换行
class A {
int f() { return 0; };
};
int
f();
int
f() {
return 1;
}
RTBS_AllDefinitions
(在配置中为AllDefinitions
) 函数定义中的返回类型后总是换行
class A {
int
f() {
return 0;
};
};
int f();
int
f() {
return 1;
}
RTBS_TopLevelDefinitions
(在配置中为TopLevelDefinitions
) 顶层函数定义中的返回类型后总是换行
class A {
int f() { return 0; };
};
int f();
int
f() {
return 1;
}
AlwaysBreakBeforeMultilineStrings (bool
)
若true
,在多行字符串前总是换行
这个选项意味着在代码中有多个多行字符串的情况下视觉更一致.因此,它只在包装字符串时生效,并使其从行首缩进ContinuationIndentWidth
个空格.
true: false:
aaaa = vs. aaaa = "bbbb"
"bbbb" "cccc";
"cccc";
AlwaysBreakTemplateDeclarations (bool
)
若true
,总会在定义模板中的template<...>
后换行
true: false:
template <typename T> vs. template <typename T> class C {};
class C {};
BinPackArguments (bool
)
若false
,调用函数的实参不会在同一行或各自一行.
true:
void f() {
f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa,
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
}
false:
void f() {
f(aaaaaaaaaaaaaaaaaaaa,
aaaaaaaaaaaaaaaaaaaa,
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
}
BinPackParameters (bool
)
若false
,函数定义的形参将不会同一行或各自一行
true:
void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa,
int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
false:
void f(int aaaaaaaaaaaaaaaaaaaa,
int aaaaaaaaaaaaaaaaaaaa,
int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
未完待续,并争取在2017/7/17前完成