AStyle

A standards enforcer for computer coding

A Free, Fast, and Small Automatic Formatter
for C, C++, C++/CLI, Objective‑C, C#, and Java Source Code

Quick Start


Contents

Quick Start

Usage

Options

Option Files

Basic Brace Styles

Brace Style Options

default, allman, java, kr, stroustrup, whitesmith, vtk, ratliff, gnu, linux, horstmann, 1tbs, google, mozilla, pico, lisp

Brace attach

namespaces, classes, inlines, extern‑c, closing‑while

Indentation

classes, modifiers, switches, cases, namespaces, after‑parens, continuation, labels, preproc‑block, preproc‑define, preproc‑cond, col1‑comments, min‑conditional‑indent, max‑continuation‑indent

Padding Options

break‑blocks, break‑blocks=all
pad‑oper, pad‑comma, pad‑paren, pad‑paren‑out, pad‑first‑paren‑out, pad‑paren‑in, pad‑header, unpad‑paren
delete‑empty‑lines, fill‑empty‑lines
align‑pointer, align‑reference

Formatting

break‑closing‑braces, break‑elseifs, break‑one‑line‑headers, add‑braces, add‑one‑line‑braces, remove‑braces, break‑return‑type, attach‑return‑type
keep‑one‑line‑blocks, keep‑one‑line‑statements, close‑templates, remove‑comment‑prefix, max‑code‑length, break‑after‑logical, mode

Objective‑C

pad‑method‑prefix, unpad‑method‑prefix, pad‑return‑type, unpad‑return‑type, pad‑param‑type, unpad‑param‑type, align‑method‑colon, pad‑method‑colon

Indent with spaces | tabs

default, spaces, tab, force‑tab, force‑tab‑x convert‑tabs,

Other

suffix, suffix=none, recursive, dry-run, exclude, ignore‑exclude‑errors, ignore‑exclude‑errors‑x, errors‑to‑stdout, preserve‑date, verbose, formatted, quiet, lineend

Disable Formatting

Command Line Only

options, project, ascii, version, stdin, stdout -! (show this),

General Information

 


Usage

Command Line

astyle  [options]  'SourceFilePath1[*]'  SourceFilePath2  SourceFilePath3  []

Example to format a single file:

astyle  /home/project/foo.cpp 
Example to format C# files recursively:

astyle  --recursive  /home/project/*.cs 

Redirection

As in usual command line processing, '<' and '>' redirect standard input (stdin) and standard output (stdout).
There are no console messages, and a backup is not created.
stdin= and stdout= can be used instead of redirection.

Example of redirection to format a single file and specify the output:

astyle < OriginalSourceFile > EnforcedSourceFile 

Example of redirection usingstdin= and stdout=.

astyle --stdin=OriginalSourceFile --stdout=EnforcedSourceFile 

Options

Long options

Start with -- with arguments preceeded by =
Examples: --style=allman --indent-spaces=4

Short Options

Start with a single -' and usually may be combined.
Example: '-bps4' is the same as '-b -p -s4'. Long options are prefered.


Option Files

Use --options=path/to/file to use an options file.

The file contains options seperated by new-lines, tabs, commas, or spaces, long options may be written without the '--'.
Lines begining with '#' are comments.
Option files are displayed with --verbose .

  1. command line options have precedence over a project file and default.
  2. project option file has precedence over the default file and should be in the top directory of the project. One of the command line project options must be used to indicate a file is available . AStyle looks for the file in the current directory or one of its parent directories Only one file will be used per execution for all files which are defined to be in the same project.
    AStyle searchs up in the directory path to find the project option file. The initial directory path for the search is obtained from
    1. The first SourceFilePath on the command line.
    2. The value of --stdin.
    3. The current directory if < is used for rediredction.
      If the file to be formatted is not in the current directory, use the--stdin= option.
    A default option file can be used for all projects. --options must be used to indicate a file is available, or it may be referred to by the environment variable. AStyle looks via '

Example of a default or project option file:

--style=allman     
# long options can be written without the preceding '--'
indent-switches    

Indent a C, c++, C++/CLI Objective-C, C#, or Java file.

Defalut is set from the file extension for each file and allows identifcation of language specific syntax such as C++ classes, templates and keywords.

Overriding default applies to all files.

--mode=c
--mode=cs
--mode=java

Basic Brace Styles

Variations on the placement of class, namespace, or other braces. (Stroustrup, Google, One True Brace, Lisp).
Indent the braces (Whitesmith, VTK, Banner, and GNU).
Run-in braces where the following statement is on the same line as the brace (Horstmann and Pico).

Brace Style Options

By default, none of the styles indent namespaces.
Other indentations are in the individual style description.
All options seperate the braces for one line blocks and seperate one line statements.
To change this use keep-one-line-blocks and/or keep-one-line-statements.

default brace style
The opening braces are not changed and the closing braces will be seperated from the preceding line.
There are a few exceptions.


Allman uses broken braces.

--style=allman | bsd | break , -A1

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

Linux style uses opening braces broken from namespace, class, and function definitions.
Braces are attached to everything else, including arrays, structs, enums, and statements within a function.
The minimum conditional indent is one-half indent. For different minimum conditional indent, use K&R. Best with a large indent, frequently 8.
Also known as Kernel Normal Form (KNF) used in the BSD kernel.

--style=linux | knf , -A8
int Foo(bool isBar)
{
        if (isFoo) {
                bar();
                return 1;
        } else
                return 0;
}

Kernighan & Ritchie style uses linux braces. Opening braces are broken from namespaces, classes, and function definitions but attached to everything else, including arrays, structs, enums, and statements within a function.

--style=kr | ="k&r" | =k/r , -A3

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

Stroustrup style, based on linux braces, with closing headers seperated from closing braces (e.g. ‑‑break‑closing‑headers). Opening braces are broken from function definitions only. Frequently used with "attach‑closing‑while", tabbed indents and an indent of 5 spaces.

--style=stroustrup , -A4
int Foo(bool isBar)
{
    if (isBar) {
        bar();
        return 1;
    }
    else
        return 0;
}

Whitesmith style uses broken, indented braces. Switch blocks and class blocks are indented to prevent a 'hanging indent' with the following case statements and C++ class modifiers (public, private, protected). 

--style=whitesmith , -A5
int Foo(bool isBar)
    {
    if (isBar)
        {
        bar();
        return 1;
        }
    else
        return 0;
    }

VTK (Visualization Toolkit) style uses broken, indented braces, except for the opening brace of classes, arrays, structs, enums, and function definitions.Switch blocks are indented to prevent a 'hanging indent' with following case statements.

--style=vtk , -A15
int Foo(bool isBar)
{
    if (isBar)
        {
        bar();
        return 1;
        }
    else
        return 0;
}

ratliff
banner , -A6

attached, indented
Switch blocks and class blocks are indented to prevent a 'hanging indent' with following case statements and C++ class modifiers (public, private, protected). 

java
attach, -A2

attached
google , -A14
Java style with a non-brace variation.
int Foo(bool isBar) {
    if (isBar) {
        bar();
        return 1;
        }
    else
        return 0;
    } 
int Foo(bool isBar) {
    if (isBar) {
        bar();
        return 1;
    } else
        return 0;
}
int Foo(bool isBar) {
    if (isBar) {
        bar();
        return 1;
    } else
        return 0;
}

GNU style uses broken braces. Extra indentation is added to blocks within a function only. The entire block is indented, not just the brace. Frequently is used with an indent of 2 spaces.

--style=gnu , -A7
int Foo(bool isBar)
{
    if (isBar)
        {
            bar();
            return 1;
        }
    else
        return 0;
}

Horstmann uses broken braces and run-in statements. Switches are indented to allow a run-in to the opening switch block. frequently with an indent of 3.

--style=horstmann | run-in , -A9
int Foo(bool isBar)
{   if (isBar)
    {   bar();
        return 1;
    }
    else
        return 0;
}

One True Brace Style uses linux braces and adds braces to unbraced one line conditional statements. Opening braces are broken from namespaces, classes, and function definitions. The braces are attached to everything else, including arrays, structs, enums, and statements within a function.

In the following example, braces have been added to thereturn 0; statement. The option ‑‑add‑one‑line‑braces can also be used with this style.

--style=1tbs | otbs , -A10
int Foo(bool isBar)
{
    if (isFoo) {
        bar();
        return 1;
    } else {
        return 0;
    }
}

attached braces and indented class access modifiers. See the indent-modifiers option for an example of the indented modifiers format. This style frequently is used with an indent of 2 spaces.

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

--style=mozilla / -A16
Mozilla style uses linux braces. Opening braces are broken from classes, structs, enums, and function definitions. The braces are attached to everything else, including namespaces, arrays, and statements within a function. This style frequently is used with an indent of 2 spaces and --break-return-type.

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

--style=pico / -A11
Pico style uses broken braces and run-in statements with attached closing braces. The closing brace is attached to the last line in the block. Switches are indented to allow a run-in to the opening switch block. The style implies keep-one-line-blocks and keep-one-line-statements. If add-braces is used they will be added as one-line braces. This style frequently is used with an indent of 2 spaces.

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

Lisp style uses attached opening and closing braces. The closing brace is attached to the last line in the block. The style implies keep-one-line-statements, but NOT keep-one-line-blocks. This style does not support one-line braces. If add-one-line-braces is used they will be added as multiple-line braces.

--style=lisp / --style=python / -A12
1 int Foo(bool isBar) {
2    if (isBar) {
3         bar()
4        return 1; }
5    else
6        return 0; }

Brace Attachment

--attach-namespaces / -xn
Attach braces to a namespace statement regardless of the brace style.
It will attach braces to CORBA IDL module statements.

the brace is always attached to a namespace statement:

namespace FooName {}

--attach-classes / -xc
Attach braces to a class statement regardless of the brace style.

the brace is always attached to a class statement:

class FooClass {};

Attach braces to class and struct inline function definitions, has precedence for all styles except Horstmann and Pico (run-in styles), effective for C++ files only.

--attach-inlines , -xl
all braces are attached to class and struct inline method definitions:

class FooClass
{
    void Foo() {    }
};

Attach braces to a braced externC statement regardless of the brace style. effective for C++ files only.

An externC statement that is part of a function definition is formatted according to the requested brace style. Braced externC statements are unaffected by the brace style and this is the only way to change them.

--attach-extern-c , -xk

attaches braces to a braced externC statement:

#ifdef __cplusplus
externC {
#endif

but function definitions are formatted according to the requested brace style:

externC EXPORT void STDCALL Foo()
{}

Attach the while of a do-while to the closing brace. This has precedence over both the brace style and the break closing braces .

--attach-closing-while , -xV
do
{
    bar();
    ++xV;
}
while xV == 1;

becomes:

do
{
    bar();
    ++xV;
} while xV == 1;


Indentation Options

--indent-classes / -C
Indent class and struct blocks so that the entire block is indented.
The struct blocks are indented only if an access modifier public:, protected: or private: is declared in the struct.
For C++ files only.

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

becomes:

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

--indent-modifiers / -xG
Indent class and struct access modifiers, public:, protected: and private: ½ indent.
The rest of the class is not indented.
For C++ only. Ignored with indent‑classes

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

becomes:

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

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

switch (foo)
{
case 1:
    S += 4;
    break;

case 2:
{
    S += 4;
    break;
}
}

becomes:

switch (foo)
{
    case 1:
        S += 4;
        break;

    case 2:
    {
        S += 4;
        break;
    }
}

--indent-cases / -K
Indent 'case' {blocks} from the 'case :' headers.
Case statements not enclosed in blocks are NOT indented.

switch (foo)
{
    case 1:
        K += 0;
        break;

    case 2:
    {
        K += 4;
        break;
    }
}

becomes:

switch (foo)
{
    case 1:
        K += 0;
        break;

    case 2:
        {
           K += 4;
           break;
        }
}


--indent-namespaces / -N
Add extra indentation to namespace blocks. It will also indent CORBA IDL module statements.
No effect on Java files.

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

becomes:

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

--indent-after-parens / -xU
Indent, instead of align, continuation lines following lines that contain an opening paren '(' or an assignment '='. This includes function definitions and declarations and return statements. The indentation can be modified by using the following indent-continuation option. This option may be preferred for editors displaying proportional fonts.

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#
Set the continuation indent for a line that ends with an opening paren '(' or an assignment '='. This includes function definitions and declarations. It will also modify the previous indent-after-paren option. The value for # indicates a number of indents. The valid values are the integer values from 0 thru 4. If this option is not used, the default value of 1 is used.

isLongVariable =
    foo1 ||
    foo2;

isLongFunction(
    bar1,
    bar2);

becomes (with indent-continuation=3):

isLongVariable =
            foo1 ||
            foo2;

isLongFunction(
            bar1,
            bar2);

--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-preproc-block / -xW
Indent preprocessor blocks at brace level zero and immediately within a namespace. There are restrictions on what will be indented. Blocks within methods, classes, arrays, etc., will not be indented. Blocks containing braces or multi-line define statements will not be indented. Without this option the preprocessor block is not indented.

#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
Indent multi-line preprocessor definitions ending with a backslash. Should be used with --convert-tabs for proper results. Does a pretty good job, but cannot perform miracles in obfuscated preprocessor definitions. Without this option the preprocessor statements remain unchanged.

#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
Indent preprocessor conditional statements to the same level as the source code.

        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
Indent C++ comments beginning in column one. By default C++ comments beginning in column one are assumed to be commented‑out code and not indented. This option will allow the comments to be indented with the code.

void Foo()\n"
{
// comment
    if (isFoo)
        bar();
}

becomes:

void Foo()\n"
{
    // comment
    if (isFoo)
        bar();
}

--min-conditional-indent=# / -m#
Set the minimal indent that is added when a header is built of multiple lines. This indent helps to easily separate the header from the command statements that follow. The value for # indicates a number of indents and is a minimum value. The indent may be greater to align with the data on the previous line.
The valid values are:
0 - no minimal indent. The lines will be aligned with the paren on the preceding line.
1 - indent at least one additional indent.
2 - indent at least two additional indents.
3 - indent at least one-half an additional indent. This is intended for large indents (e.g. 8).
The default value is 2, two additional indents.

// 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=s / -Ms
Maximum spaces to indent a continuation line between 40 & 120. Default 40. (Seriously ?)
Prevents continuation lines from extending too far to the right.

MooArray[] = { red,  (Seriously ?)
         green,
         blue }

MooFunction(barArg1,  (Seriously ?)
         barArg2,
         barArg3);

becomes (with larger value):

MooArray[] = red,
             green,
             blue };

MooFunction(barArg1,
            barArg2,
            barArg3);


Padding Options

--break-blocks / -f
Blank lines before and after header {blocks} (i.e. if, for, while…).
Tends to clarify block boundries.

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

becomes:

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

--break-blocks=all / -F
Blank lines around header {blocks} (i.e. if, for, while…).
Treat closing header blocks (e.g. else, catch) as stand-alone blocks.
Stretchs down a lot.

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

becomes:

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

--pad-oper / -p
Insert space padding around operators and commas.
There is no option to unpad.
End of line comments are unchanged

if (poo==2)
    p=bar((b-c)*p,d--);

becomes:

if (poo == 2)
    p = bar((b - c) * p, d--);

--pad-comma / -xg
Insert space padding after commas. Not needed with pad-oper .
There is no option to unpad.
End of line comments are unchanged.

if (isxgoo(a,b))
    xg(a,b);

becomes:

if (isxgoo(a, b))
    xg(a, b);

--pad-paren / -P
Space padding around parens on both the outside and the inside.
Stretches line out a lot.
End of line comments are unchanged.

if (isPoo((a+2), b))
    bar(a, b);

becomes:

if ( isPoo ( ( a+2 ), b ) )
    bar ( a, b );

--pad-paren-out / -d
Space padding outside parens only. Stretches line out a some.
emptY Parens will not be padded. End of line comments are unchanged.
With unpad-paren removes unwanted ? spaces.

if (isdoo((a+2), b))
    bar(a, b);

becomes:

if (isdoo ( (a+2), b) )
    bar (a, b);

--pad-first-paren-out / -xd
Space padding outside the first paren in a series.
With unpad-paren removes unwanted spaces.
Superceeded by pad‑paren or pad‑paren‑out.
With pad‑paren‑in, the result will be the pad‑paren.
Empty parens will not be padded. End of line comments are unchanged.

if (isxdoo((a+2), b))
    bar(a, b);

becomes:

if (isxdoo ((a+2), b))
    bar (a, b);   

--pad-paren-in / -D
Space padding around paren on the inside only.
With unpad-paren removes unwanted ?spaces. End of line comments are unchanged.

if (isDoo((a+2), b))
    bar(a, b);

becomes:

if ( isDoo( ( a+2 ), b ) )
    bar( a, b );

--pad-header / -H
Space padding between a header (i.e. if, for, while…) and the following paren.
End of line comments are unchanged. With unpad-paren removes unwanted spaces.

if(isHoo((a+2), b))
    bar(a, b);

becomes:

if (isHoo((a+2), b))
    bar(a, b);

--unpad-paren / -U
Remove extra space padding around parens on the inside and outside.
End of line comments are unchanged.
With the paren padding options pad‑paren, pad‑paren‑out, pad‑paren‑in, and pad‑header .
Shrinks a bunch.
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. 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 ( isUoo( ( a+2 ), b ) )
     bar ( a, b );

becomes (with no padding option requested):

if(isUoo((a+2), b))
    bar(a, b);

--delete-empty-lines / -xe
Delete empty lines within a function or method. ( not nice IMEO )
With break-blocks or break-blocks=all all lines not added by break-blocks are deleted.
Reduces height of source at the expense of removing authors grouping.

void Foo()
{
                     
    xeoo1 = 1;
                     
    xefoo2 = 2;
                      
}

becomes:

void Foo()
{
    xefoo1 = 1;
    xefoo2 = 2;
}

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


--align-pointer=type   / -k1 gawk!
--align-pointer=middle / -k2
--align-pointer=name   / -k3 best

Attach pointer or reference operators (*, &, or ^) to either the variable type (left) , name (right), or between the type and name (middle).
The spacing between the type and name will be preserved.
To format references separately, use align-reference .
For C/C++, C++/CLI, and C# .

char* k1oo1;
char & k1o2;
string ^k1;

becomes (with align-pointer=type | k1):

char* k1oo1; gawk!
char& k1oo2;
string^ k1;

char* foo1;
char & foo2;
string ^s1;

becomes (with align-pointer=middle | k2):

char * foo1;
char & foo2;
string ^ s1;

char* foo1;
char & foo2;
string ^s1;

becomes (with align-pointer=name | k3):

char *foo1;
char &foo2;
string ^s1;

--align-reference=none   / -W0
--align-reference=type   / -W1
--align-reference=middle / -W2
--align-reference=name   / -W3

Aligns references (unless none is used) but not pointers .
To align pointers and references aligned the same, use align-pointer . For C/C++, C++/CLI, and C# .

char &fok1;

with --align-reference=type becomes:

char& fok1;

char& fok2;

with --align-reference=middle becomes:

char & fok2;

char& k3oo3;

with --align-reference=name becomes:

char &k3foo3;


Formatting Options

--break-closing-braces / -y
When used with --style=java, --style=kr, --style=stroustrup, --style=linux, or --style=1tbs, this breaks closing headers (e.g. 'else', 'catch', …) from their immediately preceding closing braces. Closing header braces are always broken with the other styles.

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
Breakelse if header combinations into separate lines. This option has no effect if keep-one-line-statements is used, theelse 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();
        }

--break-one-line-headers / -xb
Break one line headers (e.g. 'if', 'while', 'else', …) from a statement residing on the same line. If the statement is enclosed in braces, the braces will be formatted according to the requested brace style.

A multi-statement line will NOT be broken if keep-one-line-statements is requested. One line blocks will NOT be broken if keep-one-line-blocks is requested and the header is enclosed in the block.

void Foo(bool isFoo)
{
    if (isFoo1) bar1();

    if (isFoo2) { bar2(); }
}

becomes:

void Foo(bool isFoo)
{
    if (isFoo1)
        bar1();

    if (isFoo2) {
        bar2();
    }
}

--add-braces / -j
Add braces to unbraced one line conditional statements (e.g. 'if', 'for', 'while'…). on a single line.
Braces will be added according to the requested brace style. Default braces will be attached.

Braces will NOT be added to a multi-statement line if keep-one-line-statements is requested. Braces will NOT be added to a one line block if keep-one-line-blocks is requested. If used with --add-one-line-braces, the result will be one line braces.

if (isjoo)
    isjoo = false;

becomes:

if (isjoo) {
    isjoo = false;
}

--add-one-line-braces / -J
Braces around one line conditional statements (e.g. 'if', 'for', 'while'…) implies --keep-one-line-blocks will not break the one line blocks.
Adds some unnecessary noise and unaligns tested varilable.

if (isJoo)
    isJoo = false;

becomes:

if (isJoo)
    { isJoo = false; }

--remove-braces / -xj
No braces around single line conditional statements.
Overridden by --add-braces or --add-one-line-braces the result will be to add braces.
Braces will not be removed fromOne True Brace Style, --style=1tbs.
Compresses unnecessarily tall single line conditionals.

if (isFoo)
{
    isFoo = false;
}

becomes:

if (isFoo)
    isFoo = false;

--break-return-type      / -xB Gawk!
--break-return-type-decl / -xD Gawk!
Break the return type from the function name. For function definitions (-xB) and function declarations or signatures (-xD).
Overides --attach-return-type,.
No effect on Objective-C functions.

void Foo(bool isFoo);

becomes:

void
Foo(bool isFoo);

--attach-return-type      / -xf
--attach-return-type-decl / -xh
Attach the return type to the function name. For function definitions (-xf), and function declarations or signatures (-xh).
They are intended to undo --break-return-type . If used with --break-return-type, the result will be to break the return type. ?
No effect on Objective-C functions.

void
Foo(bool isFoo);

becomes:

void Foo(bool isFoo);

--keep-one-line-blocks / -O
Don't break one-line blocks.

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

remains unchanged.

--keep-one-line-statements / -o
Don't break complex statements and multiple statements residing on a single line.

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

remains unchanged.


--close-templates / -xy
Closes whitespace between the ending angle brackets of template definitions.

Stack< int, List< int > > stack1;

becomes:

Stack< int, List< int >> stack1;

--remove-comment-prefix / -xp
Remove the preceding and training * in a multi-line commen
Text that is less than one indent is indented to one indent.
Text greater than one indent is not changed.
Multi-line comments that begin a line, but without the preceding '*', are indented to one indent for consistency. This can slightly modify the indentation of "commented out" blocks of code.
Lines containing all '*' are unchanged.
Extra spacing is removed from the comment close '*/'.

/*
 *  comment with star prefix
 * comment line 2 a suffixed star *
 *        comment line 2 a suffixed star *
 */

becomes:

/*
    comment WITHOUT star prefix
    comment star suffix remover too
           comment 
*/

--max-code-length=c   / -xCc
--break-after-logical / -xL
( with --max-code-length)
Breaks a line if the code exceeds c characters (between 50 and 200).
Lines with logical conditionals will break before a logical conditional (||, &&, …) unless --break‑after‑logical is specified
Without loginal conditions lines are broken after comma, paren, semicolon, or space.
Comments, quotes, and arrays will not be broken.
With keep‑one‑line‑blocks or add-one-line-braces the blocks will NOT be broken.
With keep‑one‑line‑statements the statements will be broken at a semicolon if the line goes over the maximum length.
If there is no available break point within the max code length, the line will be broken at the first available break point after the max code length.

if (thisVariable1 == thatVariable1 || thisVariable2 == thatVariable2 || thisVariable3 == thatVariable3)
    bar();

becomes:

if (thisVariable1 == thatVariable1
        || thisVariable2 == thatVariable2
        || thisVariable3 == thatVariable3)
    bar();

with break‑after‑logical, becomes :

if (thisVariable1 == thatVariable1 ||
        thisVariable2 == thatVariable2 ||
        thisVariable3 == thatVariable3)
    bar();
Interestingly this document is formated with width of 148 columns


    

Objective‑C

Effective for Objective‑C files only. The standard paren padding options will still apply to the method prefix and return type unless overridden by these

Because of the longer indents sometimes needed for Objective‑C, max-continuation-indent may need to be increased if you are not getting the paren and square bracket alignmen. . see Indentation .

--pad-method-prefix / -xQ
Insert space padding after the - or + Objective‑C method prefix. This will add exactly one space. additional spaces will be deleted.

-(void)foo1;
-    (void)foo2;

becomes:

- (void)foo1;
- (void)foo2;

--unpad-method-prefix / -xR
Remove all space padding after the '-' or '+' Objective‑C method prefix.  This option will be ignored if used with pad‑method‑prefix. This option takes precedence over the pad paren outside option.

- (void) foo1;
-     (void) foo2;

becomes:

-(void) foo1;
-(void) foo2;

--pad-return-type / -xq
Insert space padding after the Objective‑C return type. This will add exactly one space. Any additional spaces will be deleted.

-(void)foo1;
-(void)   foo2;

becomes:

-(void) foo1;
-(void) foo2;

--unpad-return-type / -xr
Remove all space padding after the Objective‑C return type. This option will be ignored if used with pad‑return‑type. This option takes precedence over the pad paren outside option.

-(void) foo1;
-(void)    foo2;

becomes:

-(void)foo1;
-(void)foo2;

--pad-param-type / -xS
Insert space padding around an Objective‑C parameter type. This will add exactly one space. Any additional spaces will be deleted. This has precedence over the pad method colon option and will always cause space padding after a method colon.

-(void)foo1:(bool)barArg1;
-(void)foo2:    (bool)   barArg2;

becomes:

-(void)foo1: (bool) barArg1;
-(void)foo2: (bool) barArg2;

--unpad-param-type / -xs
Remove all space padding around an Objective‑C parameter type. This option takes precedence over the pad paren outside option. The pad method colon option has precedence over the opening paren. The closing paren will always be unpadded.

-(void)foo1: (bool)    barArg1;
-(void)foo2:     (bool)    barArg2;

becomes (with an unpadded method colon):

-(void)foo1:(bool)barArg1;
-(void)foo2:(bool)barArg2;

becomes (with a padded method colon after):

-(void)foo1: (bool)barArg1;
-(void)foo2: (bool)barArg2;

Align the colons in Objective‑C method declarations and method calls. If this option is not declared, method definitions will be indented uniformly, and method calls will align with the first keyword.

--align-method-colon / -xM
-(void)longKeyword: (ID)theArg1
         keyword: (int)theArg2
       error: (NSError*)theError
{
    [myObj longKeyword: arg1
     keyword: arg2
     error: arg3];
}

becomes (with no option declared):

-(void)longKeyword: (ID)theArg1
    keyword: (int)theArg2
    error: (NSError*)theError
{
    [myObj longKeyword: arg1
           keyword: arg2
           error: arg3];
}

becomes (with align-method-colon):

-(void)longKeyword: (ID)theArg1
           keyword: (int)theArg2
             error: (NSError*)theError
{
    [myObj longKeyword: arg1
               keyword: arg2
                 error: arg3];
}

Add or remove space padding before or after the colons in an Objective‑C method call. These options will pad exactly one space. Any additional spaces will be deleted. The space padding after the method colon can be overridden by pad-param-type.

--pad-method-colon=none   , -xP0
--pad-method-colon=all    , -xP1
--pad-method-colon=after  , -xP2
--pad-method-colon=before , -xP3

with pad-method-colon=none:

-(void)insertKey:(id)key;

with pad-method-colon=all:

-(void)insertKey : (id)key;

with pad-method-colon=after:

-(void)insertKey: (id)key;

with pad-method-colon=before:

-(void)insertKey :(id)key;


Indenting with Tab / Spaces

A space is indicated with . (dot), a tab is indicated by > (greater than).

If no indentation option is set, the default is 4 spaces .

void Foo() {
….if (isBar1
….........&& isBar2)    // indent of this line can be changed with min-conditional-indent
….....bar();
}

--indent=spaces[#] / -s[#]
Indent using # spaces per indent
# must be between 2 and 20. Default of 4 spaces per indent.

with indent=spaces=3

void soo() {
…if (isBar1
…......&& isBar2)    // indent of this continuation line can be changed with min-conditional-indent...bar();
}

--indent=tab[#] / -t[#]
Indent using tabs for indentation, and spaces for continuation line alignment.
Ensures that the code is displayed correctly  regardless of the viewer’s tab size.
Treat each indent as # spaces (e.g. -t6 / --indent=tab=6). # must be between 2 and 20. If no # is set, treats indents as 4 spaces.

with indent=tab:

void too() {
>   if (isBar1
>   ….....&& isBar2)  // indent of this continuation line can be changed with min-conditional-indent
>   >   bar();
}

with style=linux, indent=tab=8:

void too()
{
>       if (isBar1
>       ….&& isBar2)    // indent of this continuation line can NOT be changed with style=linux
>       >       bar();
}

--indent=force-tab[#] / -T[#]
Indent using all tab characters.
If a continuation line is not an even number of tabs, spaces will be added at the end.
Treat each tab as # spaces .
# must be between 2 and 20. Default treats tabs as 4 spaces.

with indent=force-tab:

void Too() {
>   if (isBar1
>   >   >   && isBar2)    // indent of this continuation line can be changed with min-conditional-indent
>   >   bar();
}

--indent=force-tab-x[#] / -xT[#]
Allows the tab length to be different than the indent. Tabs will be used to indent.
Causes the indentation to be tabs and spaces.

Sets the tab length. Treat each tab as # spaces
# must be between 2 and 20. Defaut tabs as 8 spaces.
To change the indent length from the default of 4 spaces indent=force-tab must also be used.

with indent=force-tab-x (default tab 8 and default indent 4):

void xToo() {
….if (isBar1
>       ….&& isBar2)    // indent of this continuation line can be changed with min-conditional-indent
>       bar();
}

--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 within quotes.


Disable Formatting

Disable Block

Formatting and indenting can be disabled with comment tags in the source with a C comment (/* … */) or a C++ line comment (//) which must be in a single line comment. Additional information can be included with the tag.

The beginning tag is *INDENT-OFF* and the ending tag is *INDENT-ON*. Parsing is partially disabled between the tags which may result in incorrect formatting after the ending tag.
If this happens, expand the tags to include additional code.

This example supresses the format of a preprocessor define:

// *INDENT-OFF*
#define FOO_DECLARE_int32_(name) \
        FOO_API_ extern ::Int32 FOO_FLAG(name)
// *INDENT-ON*
Otherwise the output would be:


                    

Disable Line

AStyle cannot always determine the usage of symbols with more than one meaning. For example an asterisk (*) can be multiplication, a pointer, or a pointer dereference. The "&" and "&&" symbols are a similar problem.

If a symbol is being padded incorrectly, pad it manually. If it is still being padded incorrectly, then disabling the formatting may be necessary.
To avoid having to use the disable bloc use single line disable.

NOPAD line ending comment

A line-end comment tag *NOPAD* will disable pad-oper, align-pointer and align-reference. All other formatting will be applied.

Example:

foo = (unsigned int) *arg;  // *NOPAD*

Other Options

Non-formatting options.

--suffix=[.]sss
Append .sss to original file name extension. Default .orig. (Example --suffix=.bak.
The suffix will be appended to the current extension unless a dot ( . ) is included.

--suffix=none , -n
Backup is not created.

--recursive , -r , -R
For each directory on the command line, process all subdirectories recursively, the file name statement should contain a wildcard. Place the file path and name in quotes to prevent the shell from not resolving the wildcards (Example $HOME/src/*.cpp).
or if the path or name contains spaces.

--dry-run
Perform a trial run with no changes. The report will be output as usual.

--exclude=file|dir
A file or subdirectory to be excluded from processing.

Excludes are matched from the end of the file path.
An exclude option of templates excludes ALL directories named templates
An exclude option of cpp/templates will exclude ALL cpp/templates directories. You may proceed backward in the directory tree to exclude only the required directories.

Specific files may be excluded in the same manner. An exclude option ofu default.cpp will exclude ALL files named default.cpp. An exclude option ofpython/default.cpp will exclude ALL files nameddefault.cpp contained in apython subdirectory. You may proceed backward in the directory tree to exclude only the required files.

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

--ignore-exclude-errors / -i
Allow processing to continue if there are errors in the exclude=### options.
Lets the excludes for several projects be entered in a single option file.
May be placed in the same option file as the excludes.
Displays the unmatched excludes.
The --ignore-exclude-errors-x will not display the unmatched excludes.

--ignore-exclude-errors-x / -xi
Allow processing to continue if there are errors in the exclude=### options.
Lets the excludes for several projects be entered in a single option file.
May be placed in the same option file as the excludes.
It will NOT display the unmatched excludes. The --ignore-exclude-errors / -i will display the unmatched excludes.

--errors-to-stdout / -X
Print errors to standard-output rather than to standard-error.
For systems/shells that do not have a separate output to standard-error.

--preserve-date / -Z
Preserve the original modifiecation time. By default the modification date will be changed a few microseconds to

Not effective if redirection is used to rename the input file.

--verbose / -v
Verbose, display release number, date, option file locations, and statistical data.

--formatted / -Q
Display only the files that have been changed.

--quiet / -q
Quiet, suppress output except error messages.

--lineend=windows / -z1
--lineend=linux   / -z2
--lineend=macold  / -z3

Use line end style. are windows (CRLF), linux (LF). MacOS uses the Linux style. Default will be determined from the input file.

When redirection is used on Windows the output will always have Windows line ends.


Command Line Only

--options=path
--options=none
Specify an options file path/name.
none disables the default options file . Only command-line parameters will be used.

--project
--project=fname
--project=none
Specify a project option file with the default name of .astylerc or _astylerc in the top directory of the project

Specify a project options file fname without a directory path. It should be in the top directory of the project.

none disables a project options file

see Also Option Files

--ascii , -I
The output will be ASCII characters only, text will be displayed in English and numbers will not be formatted. The -I must be by itself.

--html[=file.html]
Display this file. -!

--stdin=f
Use file path f as input for single file. Do not use with < redirection.

--stdout=f
Use f as output from single file . Do not use with > redirection.

--version , -V
Print version number and quit. The -V must be by itself.

General Information

Line Endings

Line endings (i.e. return & linefeed or just linefeed) will be the same the input file. If there are mixed line endings the most frequent occurrence will be used. Optionaly specify or change the line endings.

File Type

Default is a C unless the file extension is java or cs ( C# ). For non-standard file extension use --mode .

Wildcards and Recursion

To process directories recursively using wildcards ( for example: *.cpp or *.c??) pass wildcards to AStyle. For Linux use quotes around paths whose file name contains wildcards. For Windows use quotes around paths whose file name contains spaces. See recursive.

This is suppressed using -n or --suffix=none).

Other Considerations

The names of special characters used by AStyle:

braces or curly braces { } ‑ also called brackets, or curly brackets.
parens or round brackets ( ) ‑ also called parentheses, brackets, circle brackets, or soft brackets.
square brackets [ ] ‑ also called block parens, brackets, closed brackets, or hard brackets.
angle brackets < > ‑ also called brackets, pointy brackets, triangular brackets, diamond brackets, tuples, or chevrons.

Aligning assignment operators across multiple lines in preserved with Code alignment as well as code on other items.

AStyle can format standard class library statements such as Open GL, wxWidgets, Qt, and MFC.

Embedded assembler language, including extended assembly and Microsoft specific assembler lines and blocks is handled..

Embedded SQL statements will be maintained as long as the standard hanging indent format is used. If theexec sql statement is indented more than the following statements, the SQL will be aligned in a single column.

Accepts unicode files encoded as UTF‑16, either big and little endian which must begin with a byte order mark (BOM) .
` Files encoded as UTF‑32 will be rejected.

Embedded statements that are multiple-line and are NOT in a C-type format, such as Python, are usually mal-formatted (a C-type format has blocks enclosed by braces and statements terminated by a semi-colon).
Macros that define functions may cause the following code to be mal-formatted because the macro is missing the braces and semi-colons from the definition.
For source with these types of statements, exclude them with exclude=#### .


File Extensions

Any number of file extensions may be used separated by commas or semicolons. An space may follow if the entire file path is enclosed in quotes.

Example formating C++ files recursively using multiple file extensions:

astyle  --recursive  /home/project/*.cpp,*.h

Internationalization

AStyle process files in any language. The translation is determined by the User Locale for Windows and the $LANG for other systems. Default is English.
Use ascii to use English instead of the system language.

The source code for translations is at the end of ASLocalizer.cpp in the form of an English‑Translation pair.

To add a new language, add a new translation class to ASLocalizer.h. Add the English‑Translation pair to the constructor in ASLocalizer.cpp. Update the WinLangCode array and add the language code to the function setTranslationClass(). The ASLocalizer.cpp program contains comments that give web pages for obtaining the LCIDs and language codes. Send the source code as a bug report and it will be included in the next release.

Messages

RC
0 Unchanged infile : No changes were made and no backup was created.

0 Formatted infile :    changes were made and    backup was created.

This is a refactored version of the documentation available at the project repository: astyle.sourceForge.net

svn checkout "https://svn.code.sf.net/p/astyle/code/trunk/AStyleTest" "$HOME/astyletest"