Artistic Style 使用教程（中文版）
Artistic Style 使用教程（中文版）
本文目录
- 1. 命令格式
- 2. 简单使用
- 3. 文件重定向
- 4. 递归处理目录
- 5. 批量处理多个文件
- 6. Option选项文件
- 7. 禁用格式化
- 8. 基本的大（花）括号样式
- 9. 括号样式选项
- 10. Tab选项
- 11. 括号修改选项
- 12. 缩进选项
- 13. 填充选项
- 14. Formatting选项
- 15. Objective‑C Options
- 16. 其他选项
- 17. 只在命令行使用的选项
- 18. 我的总结
官网英文文档：http://astyle.sourceforge.net/astyle.html
本文根据官网教程进行简单翻译和总结。
注：Artistic Style的安装请参考 Artistic Style的安装 Mac/Linux
1. 命令格式
astyle [OPTIONS] SourceFilePath1 SourceFilePath2 SourceFilePath3 [...]
1.1. 一些说明
-
Artistic Style将根据文件扩展名确定文件类型。 扩展名“.java”表示Java文件，而“.cs”表示C＃文件。 其他所有内容都是C类型文件（C，C ++，C ++ / CLI或Objective-C）。 如果您使用Java或C＃的非标准文件扩展名，请使用
--mode=选项。 -
格式化文件后，新缩进的文件将保留原始文件名。 创建原始文件的副本，并在原始文件名后附加.orig。（可以通过–suffix =选项将其设置为其他字符串，或者通过-n或–suffix=none选项将其完全取消）。因此，缩进SourceFile.cpp后，缩进的文件将被命名为SourceFile.cpp，而原始的预缩进文件将被重命名为SourceFile.cpp.orig。
-
Artistic Style已经国际化，可以处理任何语言的文件和目录。它也已被翻译成几种语言。使用的翻译取决于Windows的用户区域设置和其他系统的LANG环境变量。这些设置将自动完成翻译。如果没有可用的翻译，它将默认为英语。有一个“–ascii”选项可以使用英语而不是系统语言。
-
Artistic Style可以格式化嵌入式SQL语句。
-
UTF-16的Unicode文件（大端或者小端）可以被格式化。文件必须以字节顺序标记（BOM）开头才能被识别。编码为UTF‑32的文件将被拒绝。需要转换为转换为UTF-8。
-
关于Option，可以使用文件进行配置，使用选项–options = ####指定要使用的文件。
1.2. 选项使用简要说明
-
长选项
这些选项以“–”开头，并且必须一次写入一个。
例如：--style=allman --indent=spaces=4 -
短选项
这些选项以单个“-”开头，并且可以串联在一起。
示例：-bps4与-b -p -s4相同。）
2. 简单使用
astyle main.c
不带任何选项运行，将使用默认的大括号样式（四个空格为一个缩进，而其他格式没有改变）。 开括号没有改变，闭括号将从上一行断开。 有一些例外。
3. 文件重定向
使用符号 < 和 > 进行文件重定向，分别等同于使用选项--stdin=和--stdout=。
注意：重定向后，一次只能格式化一个文件。 无法识别通配符，没有控制台消息，也不会创建备份。
示例：
astyle --style=allman < OriginalSourceFile > BeautifiedSourceFile
OriginalSourceFile 为格式化的文件，BeautifiedSourceFile为格式化后的输出文件。
等同于：
astyle --style=allman --stdin=OriginalSourceFile --stdout=BeautifiedSourceFile
另外：
astyle --style=allman < OriginalSourceFile | less
可以将结果打印到终端，但源文件OriginalSourceFile的格式没有改变。
4. 递归处理目录
Artistic Style可以递归处理目录。 通配符（例如*.cpp或*.c）在内部进行处理。 如：
astyle --style=allman --recursive /home/project/*.cpp,*.h
如果使用shell，则应将通配符传递给Artistic Style，而不是先解决它们。因为shell文件会对*符号进行处理，所以需要转义。Makefile中便不用考虑这个。
对于Linux，在文件名包含通配符的路径周围使用双引号引起来。 对于Windows，在文件名包含空格的路径周围使用双引号引起来。
5. 批量处理多个文件
Linux/Mac下，递归格式化当前目录下的所有c文件和cpp文件的bash命令：
for f in $(find . -name '*.c' -or -name '*.cpp' -type f); do astyle $f; done
Makefile下可以这样使用（需要对$转义）：
for f in $(shell find . -name '*.c' -or -name '*.cpp' -type f); do astyle $$f; done
等同于递归处理命令：
astyle --recursive *.cpp,*.c
Windows下的批处理命令：
for /R %f in (*.cpp;*.c;*.h) do astyle --style=ansi "%f"
6. Option选项文件
可以选择使用默认选项文件与项目选项文件来补充或者替换命令行选项。选项文件需要使用计算机标准编码、UTF-8或UTF-16 unicode编码。
选项文件的书写格式：
- 选项可以用换行符，制表符，逗号或空格分开
- 选项文件中的长选项可以不带前面的
-- - 选项文件中以“＃”开头的行被视为行注释
- 运行时，可以使用
--verbose选项显示使用的选项文件及其位置。
选项的设置有三个来源：
-
command line options：命令行选项
通过命令行设置的选项，它具有最高的优先级，如果选项与默认选项文件和项目选项文件存在冲突，则使用命令行的选项设置。 -
project option file：项目选项文件
项目选项文件具有第二高优先级。按照以下顺序搜索到的第一个文件为使用的项目选项文件：--project=选项指示的文件- 名为
.astylerc或_astylerc的文件 - 由环境变量
ARTISTIC_STYLE_PROJECT_OPTIONS（如果存在）指示的文件 - 可以通过在命令行上指定
--project=none来禁用文件或环境变量。
项目选项文件应位于要格式化的项目的顶层目录中。每次执行仅使用一个文件，并且所有要格式化的文件都假定在同一项目中。Artistic Style将在目录路径中向后搜索以找到项目选项文件。从以下位置之一按以下顺序获得搜索的初始目录路径。
- 在命令行上输入的第一个SourceFilePath。
- “–stdin=“的值（如果用于重定向）
- 当前目录（如果使用“ <”进行重定向）。如果要格式化的文件不在当前目录中，请改用“ --stdin=”选项。
-
default option file：默认选项文件
默认选项文件的优先级最低，可用于所有项目，按照以下顺序搜索到的第一个文件为默认选项文件：--options=命令行选项指示的文件。- 环境变量
ARTISTIC_STYLE_OPTIONS指示的文件（如果存在） - 环境变量
HOME所指示目录下的.astylerc文件（如Linux下：$HOME/.astylerc） - 由环境变量
APPDATA所指示目录下的astylerc文件（如Windows下：%APPDATA%\astyler） - 可以通过在命令行上指定
--options=none来禁用文件或环境变量。
选项文件书写示例：
# 这是行注释
--style=allman #这是行尾注释
# 长选项可以没有前面的‘--’
indent-switches # 不能在命令行选项中这样使用
# 短选项必须有前面的‘-’
-t -p
# 短选项可以链接在一起
-M60Ucv
7. 禁用格式化
可以通过在源代码中插入注释标签来禁用格式和缩进。
7.1. 禁用块
- 可以使用“ off”和“ on”标签禁用代码块。标签作为注释包含在源文件中。
- 注释可以是C注释（/*…*/）或C ++行注释（//）。
- 标签必须包含在单行注释中。如果注释超过一行，则缩进标记将被忽略。
- 标签可以包含其他信息。
用法：
- 起始标签为
*INDENT-OFF*，结束标签为*INDENT-ON*。 - 它们可以在程序中的任何位置使用，标签之间的部分不会被格式化。
示例：
// *INDENT-OFF*
#define FOO_DECLARE_int32_(name) \
FOO_API_ extern ::Int32 FOO_FLAG(name)
// *INDENT-ON*
7.2. 禁用线
Artistic Style不能总是确定具有多个含义的符号的使用。例如，星号（*）可以是乘法，指针或指针取消引用。“＆”和“ &&”符号是类似的问题。
行尾注释标签*NOPAD*将禁用pad-oper, align-pointer, 和 align-reference 选项。但其他格式可以应用于该行。标记仅适用于一行。
示例：
// 以下内容可防止操作员填充更改：
size_t foo =（unsigned int）-1; // * NOPAD *
8. 基本的大（花）括号样式
有三种基本的大括号样式：
- Attached——括号连接到上一个块的最后一行的末尾(Java)。
- Broken——大括号从上一个块中折断(Allman)。
- Linux——除了
function、class、namespace的大括号采用Broken外，其他地方的采用Attached(K&R, Linux)。
其他花括号样式是这些的变体。有些会在类，名称空间或其他花括号的位置上使用变体（Stroustrup，Google，One True Brace，Lisp）。有的将缩进花括号（Whitesmith，VTK，Banner和GNU）。其他的将使花括号以及其中的语句放到同一行（Horstmann和Pico）。
9. 括号样式选项
括号样式选项定义要使用的括号样式。
- 所有选项默认为每个缩进4个空格，以空格缩进
- 所有样式不缩进
namespaces - 所有选项都将折断一行的大括号，并且将折断一行的语句
注：一些样式会有多种选项，使用其中一种即可。
9.1. 默认样式
如果不需要大括号样式，将使用默认的大括号样式。开括号没有改变，闭括号将从上一行断开。有一些例外。
9.2. Allman
使用Broken的基本样式
选项格式：
--style=allman
--style=bsd
--style=break
-A1
样式示例：
int Foo(bool isBar)
{
if (isBar)
{
bar();
return 1;
}
else
return 0;
}
9.3. Java
使用Bttached基本样式。
选项格式：
--style=java
--style=attach
-A2
样式示例：
int Foo(bool isBar) {
if (isBar) {
bar();
return 1;
} else
return 0;
}
9.4. Kernighan & Ritchie style
使用Linux基本样式。
- namespaces, classes 和 function definitions的地方采用
Broken - 其他地方采用
Attached，如数组、结构体、枚举等等。
在选项中直接使用k&r可能会出问题，事可以使用双引号包围。
选项格式：
‑‑style="k&r"
--style=kr
--style=k/r
-A3
样式示例：
int Foo(bool isBar)
{
if (isBar) {
bar();
return 1;
} else
return 0;
}
9.5. Stroustrup
使用带有选项‑‑break‑closing‑headers的Linux样式。有以下特征：
- 函数定义处，花括号
Broken - 其他所有地方的花括号
Attached
该选项通常与attach‑closing‑while、tab缩进和一个缩进为5个空格等选项一起使用。
选项格式：
--style=stroustrup
-A4
样式示例：
int Foo(bool isBar)
{
if (isBar) {
bar();
return 1;
}
else
return 0;
}
9.6. Whitesmith
使用Broken，但花括号缩进
为了防止花括号中的语句“悬挂缩进”，进行了以下处理：
- switch块中的case、default语句和花括号一起缩进。
- clase中的权限说明语句（public, private, protected）和花括号一起缩进。
选项格式：
--style=whitesmith
-A5
样式示例：
int Foo(bool isBar)
{
if (isBar)
{
bar();
return 1;
}
else
return 0;
}
int main()
{
int a = 1;
switch (a)
{
case 1:
a++;
break;
default:
break;
}
return a;
}
9.7. VTK (Visualization Toolkit)
使用Broken、且花括号缩进，但classes, arrays, structs, enums, and function definitions等地方例外。防止“悬挂缩进”，switch块中的case、default语句和花括号一起缩进。
选项格式：
--style=vtk
-A15
样式示例：
int Foo(bool isBar)
{
if (isBar)
{
bar();
return 1;
}
else
return 0;
}
int main()
{
int arrays[] = {1,2};
int a = 1;
switch (a)
{
case 1:
a++;
break;
default:
break;
}
return a;
}
9.8. Ratliff
Attached、括号缩进。对Switch blocks和class blocks进行防“悬挂缩进”处理。
选项格式：
--style=ratliff
--style=banner
-A6
样式示例：
int Foo(bool isBar) {
if (isBar) {
bar();
return 1;
}
else
return 0;
}
9.9. GNU
Broken，函数内的块会有额外的缩进，即整个块均会进行缩进，包括语句，该样式通常设置缩进为2个空格。
选项格式：
--style=gnu
-A7
样式示例：
int Foo(bool isBar)
{
if (isBar)
{
bar();
return 1;
}
else
return 0;
}
9.10. Linux
Linux基础样式
- namespace, class, and function definitions的地方
Broken - 其他地方均
Attached - 最小条件缩进是一半缩进
该样式在大缩进的情况下效果最好，通常设置缩进为8个空格。
也称为Kernel Normal Form (KNF)，通常使用在Linux BSD 内核。
选项格式：
--style=linux
--style=knf
-A8
样式示例：
int Foo(bool isBar)
{
if (isFoo) {
bar();
return 1;
} else
return 0;
}
9.11. Horstmann
broken、run-in statements(即块中第一条语句与开始花括号同行)，该样式通常设置缩进为3个空格。
选项格式：
--style=horstmann
--style=run-in
-A9
样式示例：
int Foo(bool isBar)
{ if (isBar)
{ bar();
return 1;
}
else
return 0;
}
9.12. One True Brace Style
Linux
- 会将括号添加到只有一条语句的块上
- namespaces, classes, and function definition的地方
Broken - 其他地方
Attached
选项‑‑add‑one‑line‑braces可以和该样式一起使用
选项格式：
--style=1tbs
--style=otbs
-A10
样式示例：
int Foo(bool isBar)
{
if (isFoo) {
bar();
return 1;
} else {
return 0;
}
}
其中，语句return 0;加上了花括号。
9.13. Google
Attached
- 缩进class中的权限声明关键字
这不是独立的一个样式，是Java样式的变体，改样式通常设置缩进为2个空格。
格式选项：
--style=google
-A14
样式示例：
int Foo(bool isBar) {
if (isBar) {
bar();
return 1;
} else
return 0;
}
9.14. Mozilla
Linux
- classes, structs, enums, and function definitions的地方
Broken - 其他地方
Attached
通常，设置缩进为2空格，使用选项--break-return-type
选项格式：
--style=mozilla
-A16
样式示例：
int Foo(bool isBar)
{
if (isBar) {
bar();
return 1;
} else
return 0;
}
9.15. Pico
Broken，语句与最近的花括号同行。
- 开始括号与第一个语句同行
- 结束括号与最后一个语句同行
通常，设置缩进为2空格
选项格式：
--style=pico
-A11
样式示例：
int Foo(bool isBar)
{ if (isBar)
{ bar();
return 1; }
else
return 0; }
9.16. Lisp
Attached
- 结束括号与最后一条语句同行
改样式不支持one-line braces，如果使用了--add-one-line-braces选项，将以多行的形式添加括号。
选项格式：
--style=lisp
--style=python
-A12
样式示例：
int Foo(bool isBar) {
if (isBar) {
bar()
return 1; }
else
return 0; }
10. Tab选项
注：下列代码示例中，用.代替空格，>代替tab
-
默认缩进
4个空格（等同于：-s4--indent=spaces=4） -
–indent=spaces / --indent=spaces=# / -s#
缩进使用#个空格，例如：-s3 --indent=spaces=3，#需要介于2到20之间。没有指明#则默认4个空格为一个缩进。// with indent=spaces=3 void Foo() { ...if (isBar1 .........&& isBar2) // indent of this line can be changed with min-conditional-indent ......bar(); } -
–indent=tab / --indent=tab=# / -t / -t#
使用tab作为缩进，使用空格来处理连续行的对齐。将tab视为#个空格，如：-t6和--indent=tab=6，#需要介于2到20之间。没有指明#则默认4个空格。with indent=tab: void Foo() { > if (isBar1 > ........&& isBar2) // indent of this line can be changed with min-conditional-indent > > bar(); } with style=linux, indent=tab=8: void Foo() { > if (isBar1 > ....&& isBar2) // indent of this line can NOT be changed with style=linux > > bar(); } -
–indent=force-tab / --indent=force-tab=# / -T / -T#
如果可以缩进均使用tab，如果连续行中的空格数量不足一个tab，则使用空格代替。将tab视为#个空格，如：-T6和--indent=force-tab=6，#需要介于2到20之间。没有指明#则默认4个空格。// with indent=force-tab: void Foo() { > if (isBar1 > > > && isBar2) // indent of this line can be changed with min-conditional-indent > > bar(); } -
–indent=force-tab-x / --indent=force-tab-x=# / -xT / -xT#
- 该选项允许将制表符长度设置为与缩进长度不同的长度，这可能导致缩进同时包含制表符和空格。如果可能，将使用制表符缩进。如果不能使用制表符缩进，则将使用空格。
- 将tab视为#个空格，如：
-xT6和--indent=force-tab-x=6，#需要介于2到20之间。没有指明#则默认8个空格。 - 注意，该选项只是改变tab的长度，如果要同时改变缩进的长度，需要使用选项
--indent=force-tab
// with indent=force-tab-x (default tab length of 8 and default indent length of 4): void Foo() { ....if (isBar1 > ....&& isBar2) // indent of this line can be changed with min-conditional-indent > bar(); }
11. 括号修改选项
-
–attach-namespaces / -xn
将花括号附加到名称空间语句。不管使用哪种花括号样式都可以完成此操作，将大括号附加到CORBA IDL模块语句中。// 大括号始终附加到名称空间语句中 namespace FooName { ... } -
–attach-classes / -xc
将大括号附加到类声明中。不管使用哪种花括号样式都可以完成此操作。// 大括号始终附加在类声明中 class FooClass { ... }; -
–attach-inlines / -xl
将括号附加到类和结构内联函数定义。此选项对除Horstmann和Pico以外的所有样式均具有优先权。它仅对C++文件有效。// 所有花括号都附加到类和结构内联方法定义： class FooClass { void Foo() { ... } }; -
–attach-extern-c / -xk
将大括号附加到extern "C"语句上，管使用哪种花括号样式都可以完成此操作。此选项仅对C++文件有效。extern "C"语句不受花括号样式的影响，所以此选项是更改它们的唯一方法。#ifdef __cplusplus extern "C" { #endif // 此类的由花括号样式处理，不受此选项影响 extern "C" EXPORT void STDCALL Foo() {} -
–attach-closing-while / -xV
将do-while语句的结束while附加到结束括号。它的等级高于brace style和the break closing braces option。do { bar(); ++x; } while x == 1; becomes: do { bar(); ++x; } while x == 1;
12. 缩进选项
-
–indent-classes / -C
缩进“类”和“结构”块，以便缩进整个块。仅当在结构的某个位置声明了访问修饰符“ public：”，“ protected：”或“ private：”时，才会缩进struct块。此选项仅对C++文件有效。class Foo { public: Foo(); virtual ~Foo(); }; becomes: class Foo { public: Foo(); virtual ~Foo(); }; -
–indent-modifiers / -xG
缩进“类”和“结构”访问修饰符，“public：”，“protected：”和“private：”，缩进一半，该类的其余部分不缩进。此选项仅对C++文件有效。如果与indent‑classes一起使用，此选项将被忽略。class Foo { public: Foo(); virtual ~Foo(); }; becomes: class Foo { public: Foo(); virtual ~Foo(); }; -
–indent-switches / -S
缩进’switch’块，以使’case X：'语句在switch块中缩进。整个case块都会缩进。switch (foo) { case 1: a += 1; break; case 2: { a += 2; break; } } becomes: switch (foo) { case 1: a += 1; break; case 2: { a += 2; break; } } -
–indent-cases / -K
缩进从’case X:‘开始的’case X:’ 块，未被括号括在块中的Case语句不缩进。switch (foo) { case 1: a += 1; break; case 2: { a += 2; break; } } becomes: switch (foo) { case 1: a += 1; break; case 2: { a += 2; break; } } -
–indent-namespaces / -N
向名称空间块添加额外的缩进。此选项对Java文件无效。它还将缩进CORBA IDL模块语句。namespace foospace { class Foo { public: Foo(); virtual ~Foo(); }; } becomes: namespace foospace { class Foo { public: Foo(); virtual ~Foo(); }; } -
–indent-after-parens / -xU
在包含开行括号’（‘或赋值’='的行之后缩进（而不是对齐）续行。这包括函数定义和声明以及return语句。可以使用--indent-continuation选项修改缩进。void Foo(bool bar1, bool bar2) { isLongFunction(bar1, bar2); isLongVariable = foo1 || foo2; } becomes: void Foo(bool bar1, bool bar2) { isLongFunction(bar1, bar2); isLongVariable = foo1 || foo2; } -
–indent-continuation=# / -xt#
设置以开始括号’（‘或赋值’='行之后续行的缩进，包括函数定义和声明。#表示缩进的次数，取值范围是0到4，默认是1。isLongVariable = foo1 || foo2; isLongFunction( bar1, bar2); becomes: // with indent-continuation=3 isLongVariable = foo1 || foo2; isLongFunction( bar1, bar2); -
–indent-labels / -L
给Label添加额外的缩进，以便它们比当前缩进少1个缩进。而不是靠在最左边（默认）。void Foo() { while (isFoo) { if (isFoo) goto error; ... error: ... } } becomes: // with indented 'error:' void Foo() { while (isFoo) { if (isFoo) goto error; ... error: ... } } -
–indent-preproc-block / -xW
缩进在零级别括号和名称空间中的预编译块。缩进有限制。方法，类，数组等中的块不会缩进。包含花括号或多行define语句的块不会缩进。没有此选项，预编译块将不缩进。#ifdef _WIN32 #include <windows.h> #ifndef NO_EXPORT #define EXPORT #endif #endif becomes: #ifdef _WIN32 #include <windows.h> #ifndef NO_EXPORT #define EXPORT #endif #endif -
–indent-preproc-define / -w
缩进以反斜杠结尾的多行预处理器定义，应该与--convert-tabs一起使用以获得正确的结果。没有此选项，预处理器定义语句将保持不变。#define Is_Bar(arg,a,b) \ (Is_Foo((arg), (a)) \ || Is_Foo((arg), (b))) becomes: #define Is_Bar(arg,a,b) \ (Is_Foo((arg), (a)) \ || Is_Foo((arg), (b))) -
–indent-preproc-cond / -xw
将预编译条件语句缩进到与源代码相同的级别。isFoo = true; #ifdef UNICODE text = wideBuff; #else text = buff; #endif becomes: isFoo = true; #ifdef UNICODE text = wideBuff; #else text = buff; #endif -
–indent-col1-comments / -Y
缩进从第一列开始的注释行。默认情况下，不缩进。该选项可以让注释和代码有相同的缩进。void Foo()\n" { // comment if (isFoo) bar(); } becomes: void Foo()\n" { // comment if (isFoo) bar(); } -
–min-conditional-indent=# / -m#
设置当头部由多行构成时添加的最小缩进量，该缩进有助于轻松地将头部与随后的命令语句分开。＃的值表示缩进的数量，并且是最小值。缩进可能更大，以与上一行的数据对齐。取值可以为：
- 0-无最小缩进。这些行将与上一行的括号对齐。
- 1-缩进至少一个额外缩进。
- 2-缩进至少两个额外缩进。
- 3-缩进至少一半的额外缩进，这个适用于大缩进的情况，比如8。
默认为2。
// default setting makes this non-braced code clear if (a < b || c > d) foo++; // but creates an exaggerated indent in this braced code if (a < b || c > d) { foo++; } becomes (when setting --min-conditional-indent=0): // setting makes this non-braced code less clear if (a < b || c > d) foo++; // but makes this braced code clearer if (a < b || c > d) { foo++; } -
–max-continuation-indent=# / -M#
设置最多＃个空格来缩进连续行，＃表示的列数，取值范围是40到120。如果未设置任何值，则将使用默认值40。此选项将防止连续线向右延伸太远。设置较大的值将使代码可以进一步向右扩展。fooArray[] = { red, green, blue }; fooFunction(barArg1, barArg2, barArg3); becomes (with larger value): fooArray[] = { red, green, blue }; fooFunction(barArg1, barArg2, barArg3);
13. 填充选项
-
–break-blocks / -f
在块周围填充空白行（例如“ if”，“ for”，“ while” …）。isFoo = true; if (isFoo) { bar(); } else { anotherBar(); } isBar = false; becomes: isFoo = true; if (isFoo) { bar(); } else { anotherBar(); } isBar = false; -
–break-blocks=all / -F
在标题块周围填充空白行（例如“ if”，“ for”，“ while” …）。将关闭的标题块（例如，“ else”，“ catch”）视为独立块。isFoo = true; if (isFoo) { bar(); } else { anotherBar(); } isBar = false; becomes: isFoo = true; if (isFoo) { bar(); } else { anotherBar(); } isBar = false; -
–pad-oper / -p
在运算符周围插入空格，包括逗号，如有可能，任何行尾注释都将保留在原始列中。请注意，没有选项可以去除空格。一旦填充，它们保持填充。if (foo==2) a=bar((b-c)*a,d--); becomes: if (foo == 2) a = bar((b - c) * a, d--); -
–pad-comma / -xg
在逗号后插入空格，如果使用了选项--pad-oper，则此选项就不必要用了。 -
–pad-paren / -P
在内部和外部的括号周围插入空格。如有可能，任何行尾注释都将保留在原始列中。if (isFoo((a+2), b)) bar(a, b); becomes: if ( isFoo ( ( a+2 ), b ) ) bar ( a, b ); -
–pad-paren-out / -d
仅在括号的外侧周围插入空格。空的括号不会被填充。如有可能，任何行尾注释都将保留在原始列中。可以与下面的unpad-paren一起使用，以删除不需要的空格。if (isFoo((a+2), b)) bar(a, b); becomes: if (isFoo ( (a+2), b) ) bar (a, b); -
–pad-first-paren-out / -xd
仅在第一个括号的外侧填充空格，空的括号不会被填充。如有可能，任何行尾注释都将保留在原始列中。可以与下面的unpad-paren一起使用，以删除不需要的空间。如果与pad-paren或pad-paren-out一起使用，此选项将被忽略。如果与pad-paren-in一起使用，结果将是pad-paren。if (isFoo((a+2), b)) bar(a, b); becomes: if (isFoo ((a+2), b)) bar (a, b); -
–pad-paren-in / -D
仅在括号的内侧填充空格，如有可能，任何行尾注释都将保留在原始列中。可以与下面的unpad-paren一起使用，以删除不需要的空间。if (isFoo((a+2), b)) bar(a, b); becomes: if ( isFoo( ( a+2 ), b ) ) bar( a, b ); -
–pad-header / -H
在标头（例如’if’，‘for’，‘while’…）和后面的括号之间插入空格。如有可能，任何行尾注释都将保留在原始列中。可以与unpad-paren一起使用以删除不需要的空间。if(isFoo((a+2), b)) bar(a, b); becomes: if (isFoo((a+2), b)) bar(a, b); -
–unpad-paren / -U
除去内部和外部的括号周围的多余空间。如有可能，任何行尾注释都将保留在原始列中。该选项可以与paren填充选项，pad-paren-out，pad-paren-in和pad-header一起使用。仅删除其他选项未请求的填充。例如，如果源在内部和外部都填充了parens，而您只想在内部。您需要使用unpad-paren删除外部填充，并使用pad-paren-in保留内部填充。仅使用pad-paren-in不会删除外部填充。
if ( isFoo( ( a+2 ), b ) ) bar ( a, b ); becomes (with no padding option requested): if(isFoo((a+2), b)) bar(a, b); -
–delete-empty-lines / -xe
删除函数或方法中的空行。函数或方法之外的空行不会删除。如果与break-blocks或break-blocks=all一起使用，它将删除除break-blocks选项添加的行以外的所有空行。
void Foo() { foo1 = 1; foo2 = 2; } becomes: void Foo() { foo1 = 1; foo2 = 2; } -
–fill-empty-lines / -E
用上一行（开始）的空白填充空白行。 -
–align-pointer=type / -k1
–align-pointer=middle / -k2
–align-pointer=name / -k3
将指针或引用运算符（*，＆或^）附加到变量类型（左）或变量名称（右），或将其放置在类型和名称之间（中间）。如果可能，将保留类型和名称之间的间距。此选项适用于C / C ++，C ++ / CLI和C＃文件。要单独设置引用的格式，请使用以下align-reference选项。char* foo1; char & foo2; string ^s1; becomes (with align-pointer=type): char* foo1; char& foo2; string^ s1;char* foo1; char & foo2; string ^s1; becomes (with align-pointer=middle): char * foo1; char & foo2; string ^ s1;char* foo1; char & foo2; string ^s1; becomes (with align-pointer=name): char *foo1; char &foo2; string ^s1; -
–align-reference=none / -W0
–align-reference=type / -W1
–align-reference=middle / -W2
–align-reference=name / -W3此选项将对齐引用符&，指针不会被该选项更改。如果指针和引用要对齐，请使用前面的align-pointer选项。选项align-reference = none不会更改参考对齐方式。其他选项与对齐指针相同。此选项适用于C / C ++，C ++ / CLI和C＃文件。
char &foo1; becomes (with align-reference=type): char& foo1;char& foo2; becomes (with align-reference=middle): char & foo2;char& foo3; becomes (with align-reference=name): char &foo3;
14. Formatting选项
-
–break-closing-braces / -y
使得头部与最近的右花括号断开。
与–style = java，–style = kr，–style = stroustrup，–style = linux或–style = 1tbs一起使用时，该选项仍然生效。void Foo(bool isFoo) { if (isFoo) { bar(); } else { anotherBar(); } } becomes (a broken 'else'): void Foo(bool isFoo) { if (isFoo) { bar(); } else { anotherBar(); } } -
–break-elseifs / -e
将“else if”标题组合分成单独的行。如果使用keep-one-line语句，此选项无效，“else if”语句将保持原样。if (isFoo) { bar(); } else if (isFoo1()) { bar1(); } else if (isFoo2()) { bar2; } becomes: if (isFoo) { bar(); } else if (isFoo1()) { bar1(); } else if (isFoo2()) { bar2(); } -
–break-one-line-headers / -xb
从同一行中的语句中断开一行标题（例如，“ if”，“ while”，“ else”，…）
如果设置了选项keep-one-line-statements和keep-one-line-blocks，则该选项失效。void Foo(bool isFoo) { if (isFoo1) bar1(); if (isFoo2) { bar2(); } } becomes: void Foo(bool isFoo) { if (isFoo1) bar1(); if (isFoo2) { bar2(); } } -
–add-braces / -j
在不带括号的一行条件语句中添加花括号（例如“ if”，“ for”，“ while” …）。该语句必须在一行上。括号将根据要求的括号样式添加。如果不要求样式，则将附加括号。如果选项keep-one-line-statements、keep-one-line-blocks设置，则此选项无效。
if (isFoo) isFoo = false; becomes: if (isFoo) { isFoo = false; } -
–add-one-line-braces / -J
在无括号的条件语句（例如“ if”，“ for”，“ while” …）中添加一行括号。该语句必须在一行上。该选项暗含–keep-one-line-blocks并且不会破坏一个行块。
类似–add-braces，但在同一行添加花括号。if (isFoo) isFoo = false; becomes: if (isFoo) { isFoo = false; } -
–remove-braces / -xj
if (isFoo) { isFoo = false; } becomes: if (isFoo) isFoo = false; -
–break-return-type / -xB
–break-return-type-decl / -xD
从函数名称中中断返回类型。这两个选项分别用于函数定义（-xB）和函数声明或签名（-xD）。如果与–attach-return-type一起使用，结果仍是破坏返回类型。此选项对Objective-C功能无效。void Foo(bool isFoo); becomes: void Foo(bool isFoo); -
–attach-return-type / -xf
–attach-return-type-decl / -xh
将返回类型附加到函数名称。这两个选项分别用于函数定义（-xf）和函数声明或签名（-xh）。它们旨在撤消–break-return-type选项。如果与–break-return-type一起使用，结果将是破坏返回类型。此选项对Objective-C功能无效。void Foo(bool isFoo); becomes: void Foo(bool isFoo); -
–keep-one-line-blocks / -O
不折断本事一行的块代码if (isFoo) { isFoo = false; cout << isFoo << endl; } remains unchanged. -
–keep-one-line-statements / -o
不折断本就是一行的代码if (isFoo) { isFoo = false; cout << isFoo << endl; } remains unchanged. -
–convert-tabs / -c
将制表符转换为空格，插入的空格数将保持制表符的间距。引号中的制表符不会被替换 -
–close-templates / -xy
封闭模板定义的结束尖括号之间的空格。C ++ 11标准现在允许关闭结束尖括号。进行更改之前，请确保您的编译器支持此功能。Stack< int, List< int > > stack1; becomes: Stack< int, List< int >> stack1; -
–remove-comment-prefix / -xp
在以一行开头的多行注释中删除前面的“ *”。尾随的“ *”（如果存在）也会被删除。少于一个缩进的文本缩进为一个缩进。大于一个缩进的文本不会更改。以一行开头但没有前面的“ *”的多行注释将缩进一个缩进以保持一致性。这可以稍微修改注释掉的代码块的缩进。多余的空格会从结束注释“*/”的左边删除。/* * comment line 1 * comment line 2 */ becomes: /* comment line 1 comment line 2 */ -
–max-code-length=# / -xC#
–break-after-logical / -xL- 对于选项
max-code-length，如果代码一行超过＃个字符，将折断一行。有效值为50到200。将在逻辑条件（||，&&& …），逗号，括号，分号或空格处折断。 - 某些代码不会被破坏，例如注释，引号和数组。如果和选项keep‑one‑line‑blocks或者add-one-line-braces一起使用，这些代码不会被破坏。如果和选项keep‑one‑line‑statements一起使用，如果行超过最大长度，则该语句将在分号后折断。如果最大代码长度内没有可用的断点，则该行将在最大代码长度之后的第一个可用断点处断开。
- 默认情况下，逻辑条件将放在新行的第一位。选项break‑after‑logical将使逻辑条件置于一行的最后。没有最大代码长度，此选项无效。
if (thisVariable1 == thatVariable1 || thisVariable2 == thatVariable2 || thisVariable3 == thatVariable3) bar(); becomes: if (thisVariable1 == thatVariable1 || thisVariable2 == thatVariable2 || thisVariable3 == thatVariable3) bar(); becomes (with break‑after‑logical): if (thisVariable1 == thatVariable1 || thisVariable2 == thatVariable2 || thisVariable3 == thatVariable3) bar(); - 对于选项
-
–mode=c
–mode=cs
–mode=java- 将处理的文件类型指定为C type, C#, or Java，C type的文件包括C, C++, C++/CLI, and Objective-C.
- 该选项常用于从文件的扩展名判断不出文件类型的情况。当然，有正确扩展名的文件，也会被强制按照该选项指定的类型文件来处理。
15. Objective‑C Options
略
请参考http://astyle.sourceforge.net/astyle.html#_Objective_C_Options
16. 其他选项
下列的选项不是格式方面的选项，但可以用在选项文件中。
-
–suffix=####
在原始(历史)文件名后附加后缀####而不是’.orig’（例如–suffix = .bak。如果这是文件扩展名，则必须包括点’.’。否则，将后缀添加到当前文件扩展名。 -
–suffix=none / -n
不要保留原始文件的备份。格式化后将清除原始文件。 -
–recursive / -r / -R
对于命令行中的每个目录，请递归处理所有子目录。使用递归选项时，文件名语句应包含通配符。Linux用户应将文件路径和名称放在双引号中，以使Shell不会解析通配符（例如“$HOME/src/ *.cpp”）。如果路径或名称包含空格，则Windows用户应将文件路径和名称放在双引号中。 -
–dry-run
在不更改文件的情况下执行试运行。该报告将照常输出。 -
–exclude=####
指定要从处理中排除的文件或子目录####。-
排除项从文件路径的末尾开始匹配。“模板”的排除选项将排除所有名为“模板”的目录。“ cpp / templates”的排除选项将排除所有“ cpp / templates”目录。您可以在目录树中向后进行操作，以仅排除所需的目录。
-
特定文件可以用相同的方式排除。“ default.cpp”的排除选项将排除所有名为“ default.cpp”的文件。“ python / default.cpp”的排除选项将排除“ python”子目录中包含的所有名为“ default.cpp”的文件。您可以在目录树中向后进行操作，以仅排除所需的文件。
-
-
–ignore-exclude-errors / -i
如果“ exclude = ###”选项中存在错误，则允许继续处理。
使用此选项，可以在单个选项文件中输入多个项目的排除项。此选项可以与排除项放在同一选项文件中。此选项之前，可以显示不匹配的排除项。但之后的便不再显示。 -
–ignore-exclude-errors-x / -xi
如果“ exclude = ###”选项中存在错误，则允许继续处理。
使用此选项，可以在单个选项文件中输入多个项目的排除项。此选项可以与排除项放在同一选项文件中。It will NOT display the unmatched excludes. The preceding option will display the unmatched excludes.这个英文感觉好像跟前一个选项的功能一样啊，需要测试一下。 -
–errors-to-stdout / -X
将错误打印到标准输出而不是标准错误。
对于没有单独输出标准错误的系统/shell（例如Windows95），此选项应该很有帮助。 -
–preserve-date / -Z
保留原始文件的修改日期和时间。修改的时间将更改几微秒，以强制更改的文件进行编译。如果使用重定向来重命名输入文件，则此选项无效。 -
–verbose / -v
详细显示模式。显示可选信息，例如发行号，日期，选项文件位置和统计数据。 -
–formatted / -Q
格式化文件的显示模式。仅显示已格式化的文件。不要显示未更改的文件。 -
–quiet / -q
安静的显示模式。禁止显示除错误消息以外的所有输出。 -
–lineend=windows / -z1
–lineend=linux / -z2
–lineend=macold / -z3
强制使用指定的线端样式。有效选项是Windows（CRLF），Linux（LF）和Macold（CR）。MacOld样式是Mac OS 9及更早版本的格式。MacOS和OS X使用Linux风格。如果未使用这些选项之一，则将从输入文件中自动确定行尾。当重定向在Windows上使用，则输出总是有Windows行结束。此选项将被忽略。
17. 只在命令行使用的选项
这些选项仅适用于命令行。它们在选项文件中不可用。
-
–options=####
–options=none
指定要读取和使用的选项文件####。它必须包含文件路径和文件名。这将允许从astylerc或.astylerc更改文件名。如果存在默认选项文件，则“none”选项将禁用默认选项文件。仅使用命令行参数。
-
–project
–project=####
–project=none指定要使用的项目选项文件。选项文件的默认名称应为.astylerc或_astylerc，并且应位于要格式化的项目的顶层目录中。
指定要使用的项目选项文件####。它只能包含不带目录路径的文件名。这将允许将项目文件名从.astylerc或_astylerc更改。它应该在要格式化的项目的顶层目录中。
如果存在，则“none”选项将禁用项目选项文件。在这种情况下，将不使用项目选项文件。
-
–ascii / -I
显示的输出将仅为ASCII字符。文本将以英文显示，数字将不格式化。该短选项必须是单独的，不能与其他选项串联。 -
–version / -V
打印版本号并退出。该短选项必须是单独的，不能与其他选项串联。 -
–help / -h / -?
打印帮助消息并退出。该短选项必须是单独的，不能与其他选项串联。 -
–html / -!
在默认浏览器中打开HTML帮助文件“ astyle.html”，然后退出。短选项必须是单独的，不能与其他选项串联。
必须将文档安装在标准安装路径中（对于Linux，则为/usr/share/doc/astyle/html；对于Windows，则为％PROGRAMFILES％\AStyle\doc）。如果安装到其他路径，请使用html = ###。 -
–html=####
在默认浏览器中使用文件路径####打开HTML帮助文件，然后退出。可以指定“ astyle.help”以外的HTML文件。该路径可以包括目录路径和文件名，或者仅包括文件名（例如html = install.html）。如果仅使用文件名，则假定该文件名位于标准安装路径中（对于Linux，为/ usr / share / doc / astyle / html；对于Windows，为％PROGRAMFILES％\ AStyle \ doc）。在这两种情况下，文件名都必须包含html扩展名。包含空格的文件路径必须用引号引起来。在Linux上，使用安装包“ xdg-utils”中的脚本“ xdg-open”打开HTML文件。默认情况下，应在大多数发行版中安装此程序。
该选项可以打开任何HTML文件。您可能需要的文件是astyle.html（默认值），install.html和index.html。
-
–stdin=####
使用文件路径####作为单个文件格式的输入打开文件。这是重定向的替代。请勿将其与“ <”重定向一起使用。 -
–stdout=####
使用文件路径####作为单个文件格式的输出打开文件。这是重定向的替代。不要将此与“>”重定向一起使用。
18. 我的总结
本满怀希望学习这个工具，结果发现功能基本在围绕着代码的缩进方面，用处有很大的局限性。我心目中的代码格式化工具，应该和go语言的fmt工具差不多，不仅能处理缩进问题，还能将用户的注释、结构体赋值语句等等地方进行对齐，最好还能对代码不合理的地方提供建议。没想到这么古老的c/c++语言居然找不到一个强大的代码格式化工具，不知道clang-format工具怎样。
18.1. 我的选项配置文件
最后附上我配置的选项文件，该配置的特点是，减少代码行数，偏向java、go语言风格。
--style=java
# 没有历史文件
-n
# 打印详细处理信息
-v
# 递归处理目录
--recursive
# 将错误打印到标准输出而不是标准错误。
--errors-to-stdout
# 括号附加到类和结构内联函数定义
--attach-inlines
# 花括号附加到extern "C"语句上
--attach-extern-c
# 将`do-while`语句的结束`while`附加到结束括号
--attach-closing-while
# 缩进'switch'块，以使'case X：'语句在switch块中缩进。整个case块都会缩进。
--indent-switches
# 向名称空间块添加额外的缩进
--indent-namespaces
# 缩进续行
--indent-after-parens
# 缩进以反斜杠结尾的多行预处理器定义
--indent-preproc-define
# 缩进注释，使得与代码对齐
--indent-col1-comments
--min-conditional-indent=2
# 运算符周围填充空格
--pad-oper
# 在标头（例如'if'，'for'，'while'...）和后面的括号之间插入空格
--pad-header
--unpad-paren
# 用上一行（开始）的空白填充空白行。
--fill-empty-lines
# 将指针或引用运算符（*，＆或^）放置到靠近变量名的一侧
--align-pointer=name
# 断开头部和语句在同一行的情况，如 if(1) a++; 断开
--break-one-line-headers
# 给只有一行语句的块添加花括号
--add-braces
# 一行代码的最大长度
--max-code-length=160
# 将tab转化为空格
--convert-tabs