转 Astyle:代码格式化工具简明指南

来源:互联网 发布:国方商标查询软件 编辑:程序博客网 时间:2024/05/16 08:59

astyle是一个我自己常用的开放源码工具。它可以方便的将程序代码格式化成自己想要的样式而不必人工修改。本来嘛,作为高等生物应该优先去做一些智慧的事情,而不是把时间消耗在机器可以完美完成的事情上。

想要立刻开始?请先去主页http://sourceforge.net/projects/astyle下载最新版本。可以选择二进制版本,也可以下载源码自行编译。总之得到可执行文件后请将astyle放在Path(C:/Program Files/Microsoft Visual Studio 8/Common7/IDE)中,这样会方便很多。

astyle是一个命令行工具,命令语法很简单:
          astyle [options] < original > Beautified
          astyle [options] Foo.cpp Bar.cpp  [...]

例如:

          astyle --style=ansi foo.cpp

上面的命令将美化foo.cpp文件,更改其风格为ANSI,并将原始文件备份到foo.cpp.orgin。所以,你可以安全的使用该软件而不必担心会将代码改得无法回头。

具体的来说,astyle包含了以下几种预定义风格,只需在参数中简单指定即可使用:

  --style=ansi:ANSI 风格格式和缩进

namespace foospace
{
 int Foo()
 {
  if (isBar)
  {
   bar();
   return 1;
  }
  else
   return 0;
 }
}


  --style=kr :Kernighan&Ritchie 风格格式和缩进

namespace foospace {
 int Foo() {
  if (isBar) {
   bar();
   return 1;
  } else
   return 0;
 }
}


  --style=linux :Linux 风格格式和缩进

namespace foospace
{
 int Foo()
 {
  if (isBar) {
   bar();
   return 1;
  } else
   return 0;
 }
}


  --style=gnu :GNU 风格格式和缩进

namespace foospace
{
 int Foo()
 {
  if (isBar)
  {
   bar();
   return 1;
  }
  else
   return 0;
 }
}


  --style=java :Java 风格格式和缩进

class foospace {
 int Foo() {
  if (isBar) {
   bar();
   return 1;
  } else
   return 0;
 }
}

 

从这里开始介绍astyle的高级应用!这里要介绍的是两种应用情形,一是在Visual Studio中整合,二是批量处理。

先看如何在Visual Studio中整合。看图说话!

第一步:点击“工具”菜单

第一步:点击“工具”菜单

第二步:点击“外部工具”

第二步:点击“外部工具”

第三步:配置并保存

在对话框中点击“添加”,如图填入各项。其中参数填写 --style=ansi $(ItemFileName)$(ItemExt)

可以勾选“使用输出窗口”,这样将不会显示黑色的命令窗口。相关信息都会显示在Visual Studio中。

经过上面设置之后,只需点击该菜单项就可以将当前文档格式化成ansi风格。如果你想要其它风格,可以自行设置参数。

值得注意的是在低版本的Visual Studio中,默认设置运行外部程序不会保存当前文档。这样的话如果在未保存的情况下运行该命令,未保存部分将会丢失。这个可以通过设置一个选项来解决。Visual Studio 6.0中:Options -> Editor -> Save Options -> Save before running tools 将该项勾选即可。我已经验证,在Visual Studio 2005中不用担心这类问题,可以放心使用。但是作为一个好习惯,我仍然建议你随时保存你的工作,尤其是做这种大幅度改动之前,甚至应该对源代码进行Check in操作。不知道Check in是什么?没关系,过几天我还会写一篇关于代码控制的文章,应该可以解决你的疑惑。

1.常用功能
(1) 单个文件--缺省美化
astyle --style=ansi Form1.cs
处理前的代码:
    private void Form1_Load(object sender, EventArgs e)
    {
        int s;
        for (int i=0;i<10;i++){
            for (int j=0;j<10; j++){
                s = s+j+i;}
        }
    }
处理后:
    private void Form1_Load(object sender, EventArgs e)
    {
        int s;
        for (int i=0;i<10;i++)
        {
            for (int j=0;j<10; j++)
            {
                s = s+j+i;
            }
        }
    }

(2) 单个文件--更改缩进2个空格
astyle --style=ansi --indent=spaces=2 Form1.cs
缺省缩进一个TAB,也可以显式说明使用Tab,如下:
astyle --style=ansi --indent=tab Form1.cs

(3) 处理多个文件--有限个
astyle --style=ansi Form1.cs Form2.cs

(4) 批量处理多个文件--无限个
for /R ./ %f in (*.cs) do astyle --style=ansi "%f"
说明:/R表明遍历一个目录树,后面紧跟的路径是根,缺省为当前目录。
本例中,根为./表示当前目录,命令等价于:
for /R %f in (*.cs) do astyle --style=ansi "%f"
作用是从(目录树根)当前目录开始,查找所有java文件,包含子目录中的文件;然后交给astyle处理。
当然,目录树根也可以使用绝对路径,下面的命令查找C盘所有的java文件并处理。
for /R c:/ %f in (*.cs) do astyle --style=ansi "%f"

2. 其他比较有用的开关:
(1) -f
在两行不相关的代码之间插入空行,如import和public class之间、public class和成员之间等;
(2) -p
在操作符两边插入空格,如=、+、-等。
如:int a=10*60;
处理后变成int a = 10 * 60;
(3) -P
在括号两边插入空格。另,-d只在括号外面插入空格,-D只在里面插入。
如:MessageBox.Show ("aaa");
处理后变成MessageBox.Show ( "aaa" );
(4) -U
移除括号两边不必要的空格。
如:MessageBox.Show ( "aaa" );
处理后变成MessageBox.Show ("aaa");
(5) -V
将Tab替换为空格。 

下面再介绍第二项独门绝技:批量格式化!

有时候你会有很多文件需要格式化成统一风格,难道一个个点击菜单?不!那样太累了。

在Windows中,我们可以用命令行来解决问题。这里用到一个超级命令 for

我来写个范例,大家就知道该怎么处理了。

      for /R %f in (*.cpp;*.c;*.h) do astyle --style=ansi "%f"

该命令在当前目录中寻找文件名匹配模式 *.cpp;*.c;*.h 的所有文件(不同模式可用英文逗号隔开),并且对每个文件%f执行操作:

       astyle --style=ansi "%f"

好了,本教程可以结束了。希望对你有所帮助。

 

下面是标准的程序文档,如果你想了解更多用法,可以一读;如果你只是像我一样日常使用该工具,就可以不看了。

Artistic Style 1.15.3   (http://www.bigfoot.com/~davidsont/astyle)
                       (created by Tal Davidson,
davidsont@bigfoot.com)

Modified edition by Qiongzhu Wan, 2004.09

Usage  :  astyle [options] < original > Beautified
          astyle [options] Foo.cpp Bar.cpp  [...]

When indenting a specific file, the resulting indented file RETAINS the
original file-name. The original pre-indented file is renamed, with a
suffix of ".orig" added to the original filename.

By default, astyle is set up to indent C/C++/C# files, with 4 spaces per
indent, a maximal indentation of 40 spaces inside continuous statements,
and NO formatting.

Option's Format:
----------------
    Long options (starting with '--') must be written one at a time.
    Short options (starting with '-') may be appended together.
    Thus, -bps4 is the same as -b -p -s4.

Predefined Styling options:
--------------------
    --style=ansi
    ANSI style formatting/indenting.

    --style=kr
    Kernighan&Ritchie style formatting/indenting.

    --style=gnu
    GNU style formatting/indenting.

    --style=java
    Java mode, with standard java style formatting/indenting.

    --style=linux
    Linux mode (i.e. 8 spaces per indent, break definition-block
    brackets but attach command-block brackets.

Indentation options:
--------------------
    -c   or   --mode=c
    Indent a C, C++ or C# source file (default)

    -j   or   --mode=java
    Indent a Java(TM) source file

    -s   or   -s#   or   --indent=spaces=#
    Indent using # spaces per indent. Not specifying #
    will result in a default of 4 spacec per indent.

    -t   or   -t#   or   --indent=tab=#
    Indent using tab characters, assuming that each
    tab is # spaces long. Not specifying # will result
    in a default assumption of 4 spaces per tab.

    -T#   or   --force-indent=tab=#    Indent using tab characters, assuming tha
t each
    tab is # spaces long. Force tabs to be used in areas
    Astyle would prefer to use spaces.

    -C   or   --indent-classes
    Indent 'class' blocks, so that the inner 'public:',
    'protected:' and 'private: headers are indented in
    relation to the class block.

    -S   or   --indent-switches
    Indent 'switch' blocks, so that the inner 'case XXX:'
    headers are indented in relation to the switch block.

    -K   or   --indent-cases
    Indent 'case XXX:' lines, so that they are flush with
    their bodies..

    -N   or   --indent-namespaces
    Indent the contents of namespace blocks.

    -B   or   --indent-brackets
    Add extra indentation to '{' and '}' block brackets.

    -G   or   --indent-blocks
    Add extra indentation entire blocks (including brackets).

    -L   or   --indent-labels
    Indent labels so that they appear one indent less than
    the current indentation level, rather than being
    flushed completely to the left (which is the default).

    -m#  or  --min-conditional-indent=#
    Indent a minimal # spaces in a continuous conditional
    belonging to a conditional header.

    -M#  or  --max-instatement-indent=#
    Indent a maximal # spaces in a continuous statement,
    relatively to the previous line.

    -E  or  --fill-empty-lines
    Fill empty lines with the white space of their
    previous lines.

    --indent-preprocessor
    Indent multi-line #define statements

Formatting options:
-------------------
    -b  or  --brackets=break
    Break brackets from pre-block code (i.e. ANSI C/C++ style).

    -a  or  --brackets=attach
    Attach brackets to pre-block code (i.e. Java/K&R style).

    -l  or  --brackets=linux
    Break definition-block brackets and attach command-block
    brackets.

    --brackets=break-closing-headers
    Break brackets before closing headers (e.g. 'else', 'catch', ..).
    Should be appended to --brackets=attach or --brackets=linux.

    -o   or  --one-line=keep-statements
    Don't break lines containing multiple statements into
    multiple single-statement lines.

    -O   or  --one-line=keep-blocks
    Don't break blocks residing completely on one line

    -p   or  --pad=oper
    Insert space paddings around operators only.

    --pad=paren
    Insert space paddings around parenthesies only.

    -P   or  --pad=all
    Insert space paddings around operators AND parenthesies.

    --convert-tabs
    Convert tabs to spaces.

    --break-blocks
    Insert empty lines around unrelated blocks, labels, classes, ...

    --break-blocks=all
    Like --break-blocks, except also insert empty lines
    around closing headers (e.g. 'else', 'catch', ...).

    --break-elseifs
    Break 'else if()' statements into two different lines.

Other options:
-------------
    --suffix=####
    Append the suffix #### instead of '.orig' to original filename.

    -X   or  --errors-to-standard-output
    Print errors and help information to standard-output rather than
    to standard-error.

    -v   or   --version
    Print version number

    -h   or   -?   or   --help
    Print this help message

Default options file:
---------------------
    Artistic Style looks for a default options file in the
    following order:
    1. The contents of the ARTISTIC_STYLE_OPTIONS environment
       variable if it exists.
    2. The file called .astylerc in the directory pointed to by the
       HOME environment variable ( i.e. $HOME/.astylerc ).
    3. The file called .astylerc in the directory pointed to by the
       HOMEPATH environment variable ( i.e. %HOMEPATH%/.astylerc ).
    If a default options file is found, the options in this file
    will be parsed BEFORE the command-line options.
    Options within the default option file may be written without
    the preliminary '-' or '--'.

 

 

 

Artistic Style 1.23A Free, Fast and Small Automatic Formatter
for C, C++, C#, and Java Source CodeContents

General Information

Usage

Options

Options File

Predefined Style Options

style=allman    style=java    style=k&r    style=stroustrup    style=whitesmith    style=banner    style=gnu    style=linux   

Tab and Bracket Options

default indent    indent=spaces    indent=tab    indent=force?tab    default brackets    brackets=break    brackets=attach    brackets=linux    brackets=stroustrup   

Indentation Options

indent?classes    indent?switches    indent?cases    indent?brackets    indent?blocks    indent?namespaces    indent?labels    indent?preprocessor    max?instatement?indent    min?conditional?indent   

Formatting Options

break?blocks    break?blocks=all    break?closing?brackets    break?elseifs    delete?empty?lines    pad?oper    pad?paren    pad?paren?out    pad?paren?in    unpad?paren    keep?one?line?statements    keep?one?line?blocks    convert?tabs    fill?empty?lines    mode=c    mode=java    mode=cs   

Other Options

suffix    suffix=none    options    options=none    recursive    exclude    errors?to?stdout    preserve?date    verbose    formatted    quiet    version    help   

 

<!-- * * * * * * * * * * * * General InformationGeneral InformationLine Endings

Line endings in the formatted file will be the same as the input file. If there are mixed line endings the most frequent occurrence will be used.

File Type

Artistic Style will determine the file type from the file extension. The extension ".java" indicates a Java file, and ".cs" indicates a C# file. Everything else is a C or C++ file. If you are using a non-standard file extension for Java or C#, use one of the --mode= options.

Wildcards and Recursion

Artistic Style can process directories recursively. Wildcards (such as "*.cpp" or "*.c??") are processed internally. If a shell is used it should pass the wildcards to Artistic Style instead of resolving them first. For Linux use double quotes around paths whose filename contains wildcards. For Windows use double quotes around paths whose filename contains spaces. The "Other Options" section contains information on recursive processing.

File Names

When a file is formatted, the newly indented file retains the original file name. A copy of the original file is created with a .orig appended to the original file name. (This can be set to a different string by the option --suffix=, or suppressed altogether by the options -n or --suffix=none). Thus, after indenting SourceFile.cpp the indented file will be named SourceFile.cpp, while the original pre-indented file will be renamed to SourceFile.cpp.orig.

Considerations

Artistic Style can format standard class library statements such as wxWidgets, QT, Open GL, and MFC. It can usually format embedded assembler language. There are occasional problems with assembler since it can vary in syntax depending on the platform.

Embedded statements that are multiple-line and are NOT in a C type format, such as SQL or Python, are usually mal-formatted. (a C type format has blocks enclosed by brackets and statements terminated by a semi-colon). If you have source code with these types of statements, exclude them with the --exclude= statement described in the "Other Options" section.

Quick Start

If you have never used Artistic Style there are a couple of ways to start. One is to run it with no options at all. This will format the file with 4 spaces per indent and will leave the brackets unchanged. Another is to use one of the predefined styles described in the "Predefined Style Options" section. Select one with a bracket formatting style you like. Once you are familiar with the options you can customize the format to your personal preference.

 

Usage

Artistic style is a console program that receives information from the command line. The format of the command line is:

astyle [options] SourceFile1 SourceFile2 SourceFile3 [ . . . ]

The block parens [ ] indicate that more than one option or more than one filename can be entered. They are NOT actually included in the command. For the options format see the following Options section.

 Example to format a single file:

astyle --style=allman /home/user/project/foo.cpp

 Example to format all .cpp and .h files recursively:

astyle --style=allman --recursive /home/user/project/*.cpp /home/user/project/*.h

Or to save the file with a different name:

astyle [options] < OriginalSourceFile > BeautifiedSourceFile

The < and > characters are used to redirect the files into standard input and out of standard output - don't forget them! With this option a copy is not created.

 

Options

Not specifying any option will result in 4 spaces per indent, no change in bracket placement, and no formatting changes.

Options may be written in two different ways.

Long options

These options start with '--', and must be written one at a time.
(Example: '--brackets=attach --indent=spaces=4')

Short Options

These options start with a single '-', and may be concatenated together.
(Example: '-bps4' is the same as writing '-b -p -s4'.)

 

Options File

A default options file may be used to set your favorite source style options.

  • The command line options have precedence. If there is a conflict between a command line option and an option in the default options file, the command line option will be used.
  • Artistic Style looks for this file in the following locations (in order):
    1. the file indicated by the --options= command line option;
    2. the file and directory indicated by the environment variable ARTISTIC_STYLE_OPTIONS (if it exists);
    3. the file named .astylerc in the directory pointed to by the >HOME environment variable (e.g. "$HOME/.astylerc" on Linux);
    4. the file named astylerc in the directory pointed to by the USERPROFILE environment variable (e.g. "%USERPROFILE%/astylerc" on Windows).
  • This option file lookup can be disabled by specifying --options=none on the command line.
  • Options may be set apart by new-lines, tabs, commas, or spaces.
  • Long options in the options file may be written without the preceding '--'.
  • Lines within the options file that begin with '#' are considered line-comments.

Example of a default options file:

# this line is a comment--brackets=attach # this is a line-end comment# long options can be written without the preceding '--'indent-switches # cannot do this on the command line# short options must have the preceding '-'-t -p# short options can be concatenated together-M65Ucv

 

Predefined Style Options

Predefined Style options define the style by setting other options. The style options always override any individual option settings. You will always get the requested style regardless of other defined options.

The style options always set the options brackets=###, indent?blocks, and indent?brackets. These options can NOT be changed with the individual option settings.

Some styles also set the number of spaces per indent. With these styles you may use the indent options indent=spaces, indent=tab, and indent=force?tab. You may also use the indent options that set the spaces per indent (indent=spaces=#, indent=tab=#, or indent=force?tab=#), but the spaces per indent will be ignored and the style setting used instead. If a style does not set the spaces per indent, any of the indent options may be used. For the options that set the spaces per indent see the following style descriptions.

All other options are available to customize the style. By default, none of the styles indent namespaces. This can be changed with the indent?namespaces option.

 

--style=allman / --style=ansi / --style=bsd / -A1
Allman style formatting/indenting uses broken brackets.

int Foo(bool isBar){ if (isBar) { bar(); return 1; } else return 0;}

 

--style=java / -A2  / --style=kr (depreciated)
Java style formatting/indenting uses attached brackets.

int Foo(bool isBar) { if (isBar) { bar(); return 1; } else return 0;}

 

--style=k&r / --style=k/r / -A3
Kernighan & Ritchie style formatting/indenting uses linux brackets. Brackets are broken from namespaces, classes, and function definitions. Brackets are attached to statements within a function.

Using k&r may cause problems because of the &. This can be resolved by enclosing the k&r in quotes (e.g. ??style="k&r") or by using the alternate ??style=k/r.

int Foo(bool isBar) { if (isBar) { bar(); return 1; } else return 0;}

 

--style=stroustrup / -A4
Stroustrup style formatting/indenting uses stroustrup brackets. Brackets are broken from function definitions only. Brackets are attached to namespaces, classes, and statements within a function.

int Foo(bool isBar) { if (isBar) { bar(); return 1; } else return 0;}

 

--style=whitesmith / -A5
Whitesmith style formatting/indenting uses broken, indented brackets. Class blocks and switch blocks are indented to prevent a 'hanging indent' with switch statements and C++ class modifiers (public, private, protected). 

int Foo(bool isBar) { if (isBar) { bar(); return 1; } else return 0; }

 

--style=banner / -A6
Banner style formatting/indenting uses attached, indented brackets. Class blocks and switch blocks are indented to prevent a 'hanging indent' with switch statements and C++ class modifiers (public, private, protected). 

int Foo(bool isBar) { if (isBar) { bar(); return 1; } else return 0; }

 

--style=gnu / -A7
GNU style formatting/indenting uses broken brackets and indented blocks. Indentation is 2 spaces.

Extra indentation is added to blocks within a function. The opening bracket for namespaces, classes, and functions is not indented.

int Foo(bool isBar){ if (isBar) { bar(); return 1; } else return 0;}

 

--style=linux / -A8
Linux style formatting/indenting uses linux style brackets. Brackets are broken from namespace, class, and function definitions. Brackets are attached to statements within a function. Indentation is 8 spaces.

Also known as Kernel Normal Form (KNF) style, this is the style used in the Linux kernel.

int Foo(bool isBar){ if (isBar) { bar(); return 1; } else return 0;}

 

Tab and Bracket Options

default indent option
If no indentation option is set, the default option of 4 spaces will be used (e.g. -s4 --indent=spaces=4).

--indent=spaces / --indent=spaces=# / -s#
Indent using # spaces per indent (e.g. -s6 --indent=spaces=6). # must be between 1 and 20. Not specifying # will result in a default of 4 spaces per indent.

--indent=tab / --indent=tab=# / -t#
Indent using tab characters. Treat each tab as # spaces (e.g. -t6 / --indent=tab=6). # must be between 1 and 20. If no # is set, treats tabs as 4 spaces.

--indent=force-tab / --indent=force-tab=# / -T# / --force-indent=tab=# (depreciated)
Indent using tab characters. Treat each tab as # spaces (e.g. -T6 / --indent=force-tab=6). Uses tabs as indents where ??indent=tab prefers to use spaces, such as inside multi-line statements. # must be between 1 and 20. If no # is set, treats tabs as 4 spaces.

default brackets option
If no brackets option is set, the brackets will not be changed.

--brackets=break / -b
Break brackets from their pre-block statements ( e.g. ANSI C / C++ style ).

void Foo(bool isFoo){ if (isFoo) { bar(); } else { anotherBar(); }}

 

--brackets=attach / -a
Attach brackets to their pre-block statements ( e.g. Java / K&R style ).

void Foo(bool isFoo) { if (isFoo) { bar(); } else { anotherBar(); }}

 

--brackets=linux / -l
Break brackets from namespace, class, and function definitions, but attach brackets to statements within a function.

With C++ files brackets are attached for function definitions within a class (inline class functions). The brackets are also attached for arrays, structs, enums, and other top level objects that are not classes or functions. This does not apply to Java and C#.

void Foo(bool isFoo){ if (isFoo) { bar(); } else { anotherBar; }}

 

--brackets=stroustrup / -u
Break brackets from function definitions only. Attach brackets to namespaces, classes, and statements within a function.

With C++ files brackets are attached for function definitions within a class (inline class functions). The brackets are also attached for arrays, structs, enums, and other top level objects that are not classes or functions. This does not apply to Java and C#.

void Foo(bool isFoo){ if (isFoo) { bar(); } else { anotherBar; }}

 

Indentation Options

--indent-classes / -C
Indent 'class' and 'struct' blocks so that the blocks 'public:', 'protected:' and 'private:' are indented. The entire block is indented. This option has no effect on Java and C# files.

class Foo{public: Foo(); virtual ~Foo();};

becomes:

class Foo{ public: Foo(); virtual ~Foo();};

 

--indent-switches / -S
Indent 'switch' blocks so that the 'case X:' statements are indented in the switch block. The entire case block is indented.

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
Indent 'case X:' blocks from the 'case X:' headers. Case statements not enclosed in blocks are NOT indented.

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-brackets / -B
Add extra indentation to brackets. This is the option used for Whitesmith and Banner style formatting/indenting. If both ??indent?brackets and ??indent?blocks are used the result will be ??indent?blocks.

if (isFoo){ bar();}else anotherBar();

becomes:

if (isFoo) { bar(); }else anotherBar();

 

--indent-blocks / -G
Add extra indentation to blocks within a function. The opening bracket for namespaces, classes, and functions is not indented. This is the option used for GNU style formatting/indenting.

if (isFoo){ bar();}else anotherBar();

becomes:

if (isFoo) { bar(); }else anotherBar();

 

--indent-namespaces / -N
Add extra indentation to namespace blocks. This option has no effect on Java files.

namespace foospace{class Foo{ public: Foo(); virtual ~Foo();};}

becomes:

namespace foospace{ class Foo { public: Foo(); virtual ~Foo(); };}

 

--indent-labels / -L
Add extra indentation to labels so they appear 1 indent less than the current indentation, rather than being flushed to the left (the default).

void Foo() { while (isFoo) { ... if (isFoo) goto error; }error: ...}

becomes (with indented 'error'):

void Foo() { while (isFoo) { ... if (isFoo) goto error; } error: ...}

 

--indent-preprocessor / -w
Indent multi-line preprocessor definitions ending with a backslash. Should be used with --convert-tabs for proper results. Does a pretty good job, but can not perform miracles in obfuscated preprocessor definitions.

#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)))

 

--max-instatement-indent=# / -M#
Indent a maximum of # spaces in a continuous statement, relative to the previous line (e.g. ??max?instatement?indent=40). # must be less than 80. If no # is set, the default value of 40 will be used.

fooArray[] = { red, green, blue };fooFunction(barArg1, barArg2, barArg3);

becomes (with larger value):

fooArray[] = { red, green, blue };fooFunction(barArg1, barArg2, barArg3);

 

--min-conditional-indent=# / -m#
Set the minimal indent that is added when a header is built of multiple-lines. This indent makes helps to easily separate the header from the command statements that follow. The value for # must be less than 40. The default setting for this option is twice the current indent (e.g. --min-conditional-indent=8).

// default setting makes this non-bracketed code clearif (a < b || c > d) foo++;// but creates an exaggerated indent in this bracketed codeif (a < b || c > d){ foo++;}

becomes (when setting --min-conditional-indent=0):

// setting makes this non-bracketed code less clearif (a < b || c > d) foo++;// but makes this bracketed code clearerif (a < b || c > d){ foo++;}

 

Formatting Options

--break-blocks / -f
Pad empty lines around header blocks (e.g. 'if', 'while'...).

isFoo = true;if (isFoo) { bar();} else { anotherBar();}isBar = false;

becomes:

isFoo = true;if (isFoo) { bar();} else { anotherBar();}isBar = false;

 

--break-blocks=all / -F
Pad empty lines around header blocks (e.g. 'if', 'while'...). Treat closing header blocks (e.g. 'else', 'catch') as stand-alone blocks.

isFoo = true;if (isFoo) { bar();} else { anotherBar();}isBar = false;

becomes:

isFoo = true;if (isFoo) { bar(); } else { anotherBar();}isBar = false;

 

--break-closing-brackets / -y / --brackets=break-closing (depreciated)
When used with --brackets=attach, --brackets=linux, or --brackets=stroustrup, this breaks closing headers (e.g. 'else', 'catch', ...) from their immediately preceding closing brackets. Closing header brackets are always broken with broken brackets, indented blocks, and indented brackets.

void Foo(bool isFoo) { if (isFoo) { bar(); } else { anotherBar(); }}

becomes (with a broken 'else'):

void Foo(bool isFoo) { if (isFoo) { bar(); } else { anotherBar(); }}

 

--break-elseifs / -e
Break "else if" header combinations into separate lines. This option has no effect if keep-one-line-statements is used, the "else if" statements will remain as they are.

If this option is NOT used, "else if" header combinations will be placed on a single line.

if (isFoo) { bar();}else if (isFoo1()) { bar1();}else if (isFoo2()) } bar2;}

becomes:

if (isFoo) { bar();}else if (isFoo1()) { bar1(); } else if (isFoo2()) { bar2(); }

 

--delete-empty-lines / -x
Delete empty lines within a function or method. Empty lines outside of functions or methods are NOT deleted. If used with break-blocks or break-blocks=all it will delete all lines EXCEPT the lines added by the break-blocks options.

void Foo(){ foo1 = 1; foo2 = 2;}

becomes:

void Foo(){ foo1 = 1; foo2 = 2;}

 

--pad-oper / -p / --pad=oper (depreciated)
Insert space padding around operators. Operators inside block parens [] are not padded. Any end of line comments will remain in the original column, if possible. Note that there is no option to unpad. Once padded, they stay padded.

if (foo==2) a=bar((b-c)*a,*d--);

becomes:

if (foo == 2) a = bar((b - c) * a, * d--);

 

--pad-paren / -P / --pad=paren (depreciated)
Insert space padding around parenthesis on both the outside and the inside. Any end of line comments will remain in the original column, if possible.

if (isFoo(a, b)) bar(a, b);

becomes:

if ( isFoo ( a, b ) ) bar ( a, b );

 

--pad-paren-out / -d / --pad=paren-out (depreciated)
Insert space padding around parenthesis on the outside only. Any end of line comments will remain in the original column, if possible. This can be used with unpad-paren below to remove unwanted spaces.

if (isFoo(a, b)) bar(a, b);

becomes:

if (isFoo (a, b) ) bar (a, b);

 

--pad-paren-in / -D / --pad=paren-in (depreciated)
Insert space padding around parenthesis on the inside only. Any end of line comments will remain in the original column, if possible. This can be used with unpad-paren below to remove unwanted spaces.

if (isFoo(a, b)) bar(a, b);

becomes:

if ( isFoo( a, b ) ) bar( a, b );

 

--unpad-paren / -U / --unpad=paren (depreciated)
Remove extra space padding around parenthesis on the inside and outside.  Any end of line comments will remain in the original column, if possible. This option can be used in combination with the paren padding options pad?paren?out and pad?paren?in above. Only padding that has not been requested by other options will be removed.

For example, if a source has parens padded on both the inside and outside, and you want inside only. You need to use unpad-paren to remove the outside padding, and pad?paren?in to retain the inside padding. Using only pad?paren?in would not remove the outside padding.

if ( isFoo( a, b ) ) bar ( a, b );

becomes (with no padding option requested):

if (isFoo(a, b)) bar(a, b);

 

--keep-one-line-statements / -o / --one-line=keep-statements (depreciated)

Don't break complex statements and multiple statements residing on a single line.

if (isFoo){ isFoo = false; cout << isFoo << endl;}

remains unchanged.

if (isFoo) DoBar();

remains unchanged.

 

--keep-one-line-blocks / -O / --one-line=keep-blocks (depreciated)

Don't break one-line blocks.

if (isFoo){ isFoo = false; cout << isFoo << endl; }

remains unchanged.

 

--convert-tabs / -c
Converts tabs into spaces in the non-indentation part of the line. The number of spaces inserted will maintain the spacing of the tab. The current setting for spaces per tab is used. It may not produce the expected results if convert-tabs is used when changing spaces per tab. Tabs are not replaced in quotes.

 

--fill-empty-lines / -E
Fill empty lines with the white space of the previous line.

 

--mode=c
Indent a C or C++ file. The option is usually set from the file extension for each file. You can override the setting with this entry. It will be used for all files regardless of the file extension. It allows the formatter to identify language specific syntax such as C++ classes, templates, and keywords.

--mode=java
Indent a Java file. The option is usually set from the file extension for each file. You can override the setting with this entry. It will be used for all files regardless of the file extension. It allows the formatter to identify language specific syntax such as Java class's keywords.

--mode=cs
Indent a C sharp file. The option is usually set from the file extension for each file. You can override the setting with this entry. It will be used for all files regardless of the file extension. It allows the formatter to identify language specific syntax such as C sharp classes and keywords.

 

Other Options

--suffix=####
Append the suffix #### instead of '.orig' to original filename (e.g. --suffix=.bak). If this is to be a file extension, the dot '.' must be included. Otherwise the suffix will be appended to the current file extension.

--suffix=none / -n
Do not retain a backup of the original file. The original file is purged after it is formatted.

--options=####
Specify an options file #### to read and use.

--options=none
Disable the default options file. Only the command-line parameters will be used.

--recursive / -r / -R
For each directory in the command line, process all subdirectories recursively. When using the recursive option the file name statement should contain a wildcard. Linux users should place the filepath and name in double quotes so the shell will not resolve the wildcards (e.g. "$HOME/src/*.cpp"). Windows users should place the filepath and name in double quotes if the path or name contains spaces.

--exclude=####
Specify a file or sub directory #### to be excluded from processing. 

Excludes are matched from the end of the filepath. An exclude option of "templates" will exclude ALL directories named "templates". An exclude option of "cpp/templates" will exclude ALL "cpp/templates" directories. You may proceed backwards in the directory tree to exclude only the required directories.

Specific files may be excluded in the same manner. An exclude option of "default.cpp" will exclude ALL files named "default.cpp". An exclude option of "python/default.cpp" will exclude ALL files named "default.cpp" contained in a "python" subdirectory.  You may proceed backwards in the directory tree to exclude only the required files.

Wildcards are NOT allowed.  There may be more than one exclude statement. The filepath and name may be placed in double quotes (e.g. ??exclude="foo bar.cpp").

--errors-to-stdout / -X
Print errors to standard-output rather than to standard-error.
This option should be helpful for systems/shells that do not have this option, such as in Windows95.

--preserve-date / -Z
Preserve the original file's date and time modified. The date and time modified will not be changed in the formatted file. This option is not effective if redirection is used.

--verbose / -v
Verbose display mode. Display optional information, such as release number and statistical data.

--formatted / -Q
Formatted files display  mode. Display only the files that have been formatted. Do not display files that are unchanged.

--quiet / -q
Quiet display mode. Suppress all output except error messages.

--version / -V
Print version number and quit. The short option must be by itself, it cannot be concatenated with other options.

--help / -h / -?
Print a help message and quit. The short option must be by itself, it cannot be concatenated with other options.