Provided by: astyle_2.03-1_amd64 
NAME
astyle - indentation and reformatting filters for C, C++, C#, Java
SYNOPSIS
astyle [options] < Original > Beautified
astyle [options] [File1] [File2] [...]
DESCRIPTION
Artistic Style (or astyle) is a source code indenter, formatter, and beautifier for the C, C++, C# and
Java programming languages.
When indenting source code, we as programmers have a tendency to use both spaces and tab characters to
create the wanted indentation. Moreover, some editors by default insert spaces instead of tabs when
pressing the tab key, and other editors (Emacs for example) have the ability to "pretty up" lines by
automatically setting up the white space before the code on the line, possibly inserting spaces in a code
that up to now used only tabs for indentation.
Since the NUMBER of space characters showed on screen for each tab character in the source code changes
between editors (until the user sets up the number to his liking...), one of the standard problems facing
programmers when moving from one source code editor to another is that code containing both spaces and
tabs that was up to now perfectly indented, suddently becomes a mess to look at when changing to another
editor. Even if you as a programmer take care to ONLY use spaces or tabs, looking at other peoples source
code can still be problematic.
To address this problem astyle was created - a series of filters, written in C++, that automatically
reindent and reformat C/C++/C#/Java source files. These can be used from a command line, or it can be
incorporated as classes in another C++ program.
USAGE
When indenting a specific file, the newly indented file RETAINS the original filename. While a copy of
the original file is created, with a suffix of ".orig" added to the original filename.
By default, astyle is set up to indent C/C++ files, with 4 spaces per indent, a maximal indentation of
40 spaces inside continuous statements, and NO formatting.
A default options file may be used to set your favorite source style. But, the command line options have
precedence. The default options file can be $HOME/.astylerc, or be specified in the
ARTISTIC_STYLE_OPTIONS environment variable or the --options command line option.
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 start with two dashes (`--') and must be
written one at a time; short options start with a single dash ('-') may be concatenated together (thus,
-bps4 is the same as -b -p -s4).
A summary of the options supported by astyle is included below.
Bracket Style Options:
Bracket Style options define the bracket style to use. This option always overrides any individual option
settings. You will always get the requested style regardless of other defined options.
All other options are available to customize the bracket style. By default, none of the styles indent
namespaces. All options default to 4 spaces per indent, indented with spaces.
default bracket style
If no bracket style option is set, the opening brackets will not be changed and closing brackets
will be broken from the preceding line.
--style=allman, --style=ansi, --style=bsd, --style=break, -A1
Allman style formatting/indenting uses broken brackets.
--style=java, --style=attach, -A2
Java style formatting/indenting uses attached brackets.
--style=kr, --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.
--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.
This style frequently is used with an indent of 5 spaces.
--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).
--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).
--style=gnu, -A7
GNU style formatting/indenting uses broken brackets and indented blocks. This style frequently is
used with an indent of 2 spaces. Extra indentation is added to blocks within a function. The
opening bracket for namespaces, classes, and functions is not indented.
--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. Minimum
conditional indent is one-half indent. If you want a different minimum conditional indent use the
K&R style instead. This style works best with a large indent. It frequently is used with an indent
of 8 spaces.
Also known as Kernel Normal Form (KNF) style, this is the style used in the Linux kernel.
--style=horstmann, -A9
Horstmann style formatting/indenting uses run-in brackets, brackets are broken and allow run-in
statements. Switches are indented to allow a run-in to the opening switch block. This style
frequently is used with an indent of 3 spaces.
--style=1tbs, --style=otbs, -A10
"One True Brace Style" formatting/indenting uses linux brackets and adds brackets to unbracketed
one line conditional statements. The option --add-one-line-brackets can also be used with this
style.
--style=pico, -A11
Pico style formatting/indenting uses run-in brackets, opening brackets are broken and allow run-in
statements. The closing bracket 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. This style does not support multiple-line brackets. If add-brackets
is used they will be added as one-line brackets. This style frequently is used with an indent of
2 spaces.
--style=1isp, --style=python, -A12
Lisp style formatting/indenting uses attached brackets, opening brackets are attached at the end
of the statement. The closing bracket 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 brackets. If --add-one-line-brackets is used they will be added as multiple-line
brackets.
Tab Options:
default indent
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, -s#
Indent using # spaces per indent (e.g. -s6 / --indent=spaces=6). # must be between 2 and 20. Not
specifying # will result in a default of 4 spaces per indent.
--indent=tab, --indent=tab=#, -t, -t#
Indent using tabs for indentation, and spaces for continuation line alignment. This ensures that
the code is displayed correctly regardless of the viewer’s tab size. Treat each tab as # spaces
(e.g. -t6 / --indent=tab=6). # must be between 2 and 20. If no # is set, treats tabs as 4 spaces.
--indent=force-tab, --indent=force-tab=#, -T, -T#
Indent using all tab characters, if possible. If a continuation line is not an even number of
tabs, spaces will be added at the end. 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 2 and 20. If no # is set, treats tabs as 4
spaces.
--indent=force-tab-x, --indent=force-tab-x=#, -xT, -xT#
This force-tab option allows the tab length to be set to a length that is different than the
indent length. This may cause the indentation to be a mix of both tabs and spaces. Tabs will be
used to indent, if possible. If a tab indent cannot be used, spaces will be used instead.
This option sets the tab length. Treat each tab as # spaces (e.g. -xT6 / --indent=force-tab-x=6).
# must be between 2 and 20. If no # is set, treats tabs as 8 spaces. To change the indent length
--indent=force-tab must also be used.
Indentation Options:
--indent-classes, -C
Indent 'class' and 'struct' blocks so that the blocks 'public:', ´protected:' and 'private:' are
indented. The struct blocks are indented only if an access modifier is declared somewhere in the
struct. The entire block is indented. This option is effective for C++ files only.
--indent-switches, -S
Indent 'switch' blocks so that the 'case X:' statements are indented in the switch block. The
entire case block is indented.
--indent-cases, -K
Indent 'case X:' blocks from the 'case X:' headers. Case statements not enclosed in blocks are NOT
indented.
--indent-namespaces, -N
Add extra indentation to namespace blocks. This option has no effect on Java files.
--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).
--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 cannot perform miracles in
obfuscated preprocessor definitions. Without this option the preprocessor statements remain
unchanged.
--indent-col1-comments, -Y
Indent C++ comments beginning in column one. By default C++ comments beginning in column one are
not indented. This option will allow the comments to be indented with the code.
--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.
--max-instatement-indent=#, -M#
Set the maximum of # spaces to indent a continuation line. The # indicates a number of columns
and must not be greater than 120. If no # is set, the default value of 40 will be used. A maximum
of less than two indent lengths will be ignored. This option will prevent continuation lines from
extending too far to the right. Setting a larger value will allow the code to be extended further
to the right.
Padding Options:
--break-blocks, -f
Pad empty lines around header blocks (e.g. 'if', 'for', 'while'...).
--break-blocks=all, -F
Pad empty lines around header blocks (e.g. 'if', 'for', 'while'...). Treat closing header blocks
(e.g. 'else', 'catch') as stand-alone blocks.
--pad-oper, -p
Insert space padding around operators. 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.
--pad-paren, -P
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.
--pad-paren-out, -d
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.
--pad-first-paren-out, -xd
Insert space padding around the first parenthesis in a series 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 used with --pad-paren or --pad-paren-out, this option will be
ignored. If used with --pad-paren-in, the result will be the same as pad-paren.
--pad-paren-in, -D
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.
--pad-header, -H
Insert space padding after paren headers only (e.g. 'if', 'for', 'while'...). Any end of line
comments will remain in the original column, if possible. This can be used with --unpad-paren to
remove unwanted spaces.
--unpad-paren, -U
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.
--delete-empty-lines, -xe
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.
--fill-empty-lines, -E
Fill empty lines with the white space of their previous lines.
--align-pointer=type, -k1
--align-pointer=middle, -k2
--align-pointer=name, -k3
Attach a pointer or reference operator (*, &, or ^) to either the variable type (left) or variable
name (right), or place it between the type and name (middle). The spacing between the type and
name will be preserved, if possible. This option is for C/C++, C++/CLI, and C# files. To format
references separately use the following --align-reference option.
--align-reference=none, -W0
--align-reference=type, -W1
--align-reference=middle, -W2
--align-reference=name, -W3
This option will align references separate from pointers. Pointers are not changed by this option.
If pointers and references are to be aligned the same, use the previous --align-pointer option.
The option --align-reference=none will not change the reference alignment. The other options are
the same as for --align-pointer. This option is for C/C++, C++/CLI, and C# files.
Formatting Options:
--break-closing-brackets, -y
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, horstmann brackets, indented blocks, and
indented brackets.
--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.
--add-brackets, -j
Add brackets to unbracketed one line conditional statements (e.g. 'if', 'for', 'while'...). The
statement must be on a single line. The brackets will be added according to the currently
requested predefined style or bracket type. If no style or bracket type is requested the brackets
will be attached. If --add-one-line-brackets is also used the result will be one line brackets.
--add-one-line-brackets, -J
Add one line brackets to unbracketed one line conditional statements (e.g. 'if', 'for',
'while'...). The statement must be on a single line. The option implies --keep-one-line-blocks
and will not break the one line blocks.
--keep-one-line-blocks, -O
Don't break one-line blocks.
--keep-one-line-statements, -o
Don't break complex statements and multiple statements residing on a single line.
--convert-tabs, -c
Convert tabs to 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.
--close-templates, -xy
Closes whitespace in the angle brackets of template definitions. Closing the ending angle
brackets is now allowed by the C++11 standard. Be sure your compiler supports this before making
the changes.
--max-code-length=#, -xC#
--break-after-logical, -xL
The option --max\[u2011]code\[u2011]length will break a line if the code exceeds # characters. The
valid values are 50 thru 200. Lines without logical conditionals will break on a logical
conditional (||, &&, ...), comma, paren, semicolon, or space.
Some code will not be broken, such as comments, quotes, and arrays. If used with
keep‑one‑line‑blocks or add-one-line-brackets the blocks will NOT be broken. If used 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.
By default logical conditionals will be placed first on the new line. The option
break‑after‑logical will cause the logical conditionals to be placed last on the previous line.
This option has no effect without max‑code‑length.
--mode=c
--mode=cs
--mode=java
Indent a C/C++, C#, or 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 C++ classes,
templates, 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.
--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. The filepath and name should
be placed in double quotes so the shell will not resolve the wildcards (e.g. "$HOME/src/*.cpp").
--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").
--ignore-exclude-errors, -i
Allow processing to continue if there are errors in the --exclude=### options. This option lets
the excludes for several projects be entered in a single option file. This option may be placed in
the same option file as the excludes. It will display the unmatched excludes. The following option
will not display the unmatched excludes.
--ignore-exclude-errors-x, -xi
Allow processing to continue if there are errors in the --exclude=### options. This option lets
the excludes for several projects be entered in a single option file. This option may be placed in
the same option file as the excludes. It will NOT display the unmatched excludes. The preceding
option will display the unmatched excludes.
--errors-to-stdout, -X
Print errors and help information to standard-output rather than to standard-error.
--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 to rename the
input file. Please note that the date is not actually preserved: 10 seconds are added to the
original date (this behaviour is reported as Debian bug #686317).
--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.
--lineend=windows, -z1
--lineend=linux, -z2
--lineend=macold, -z3
Force use of the specified line end style. Valid options are windows (CRLF), linux (LF), and
macold (CR). MacOld style is the format for OS 9 and earlier. Mac OS X uses the Linux style. If
one of these options is not used the line ends will be determined automatically from the input
file.
Command Line Only:
These options are available for the command-line only. They are NOT available in an options file.
--options=####
Specify an options file #### to read and use. It must contain a file path for the file. This will
allow the file name to be changed from astylerc or .astylerc.
--options=none
Disable the default options file. Only the command-line parameters will be used.
--ascii, -I
The displayed output will be ascii characters only. The text will be displayed in English and
numbers will not be formatted. The short option must be by itself, it cannot be concatenated with
other options.
--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.
FILES
Artistic Style looks for a default options file in the following order:
1. The contents of the file indicated by the --options= command line option; 2. The contents of the
ARTISTIC_STYLE_OPTIONS environment variable if it exists.
3. The file called .astylerc in the directory pointed to by the HOME environment variable (i.e.
$HOME/.astylerc).
4. 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. This option file lookup can be disabled by specifying --options=none on the command line.
Long options within the default option file may be written without the preliminary '--', but short
options require the preceding '-'. Lines within the options file that begin with '#' are considered line-
comments.
VERSION
2.03
SEE ALSO
indent(1)
http://astyle.sourceforge.net/
http://www.sourceforge.net/projects/astyle/
http://packages.debian.org/astyle
AUTHOR
Tal Davidson <davidsont@bigfoot.com>
This man-page was written by Jan Schaumann <jschauma@netmeister.org> as part of "The Missing Man Pages
Project". Please see http://www.netmeister.org/misc/m2p2/index.html for details.
Minor modifications by Luca Filipozzi <lfilipoz@debian.org>. Updated on August 2009 by Margarita
Manterola <marga@debian.org>. Updated from 2010 to 2013 by Matteo Cypriani <mcy@lm7.fr>.
astyle February 21, 2011 ASTYLE(1)