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 reindenter and reformatter 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
This program follows the usual GNU command line syntax, with long
options starting with two dashes (‘--’). Long options must be written
one at a time. Short options (starting with ’-’) may be appended
together.
Thus, -bps4 is the same as -b -p -s4.
A summary of the options supported by astyle is included below.
Predefined Styling options:
Predefined Style options define the style by setting several other
options. If other options are also used, the placement of the
predefined style option in the command line is important. If the
predefined style option is placed first, the other options may override
the predefined style. If placed last, the predefined style will
override the other options.
--style=ansi, --style=allman, --style=bsd, -A1
ANSI style formatting/indenting. Uses broken brackets.
--style=java, -A2
Java style formatting/indenting. Uses attached brackets.
--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.
--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 brocken 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.
--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.
--style=horstmann, -A9
Horstmann style formatting/indenting uses horstmann style
brackets. Brackets are broken with run-in statements. Switches
are indented. Indentation is 3 spaces.
--style=1tbs, --style=otbs, -A10
"One True Brace Style" formatting/indenting uses linux style
brackets and adds brackets to unbracketed one line conditional
statements. The option --add-one-line-brackets can also be used
with this style.
Tab and Bracket Options:
If no indentation option is set, the default option of 4 spaces will be
used. Equivalent to -s4 --indent=spaces=4. If no brackets option is
set, the brackets will not be changed.
--indent=spaces, --indent=spaces=#, -s, -s#
Indent using # spaces per indent. Between 1 to 20. Not
specifying # will result in a default of 4 spaces per indent.
--indent=tab, --indent=tab=#, -t, -t#
Indent using tab characters, assuming that each tab is # spaces
long. Between 1 and 20. Not specifying # will result in a
default assumption of 4 spaces per tab.
--indent=force-tab, --indent=force-tab=#, -T, -T#
Indent using tab characters, assuming that each tab is # spaces
long. Between 1 and 20. Force tabs to be used in areas astyle
would usually prefer to use spaces (as in multi-line
statements). Not specifying # will result in a default
assumption of 4 spaces per tab.
--brackets=break, -b
Break brackets from pre-block statements (i.e. ANSI C/C++
style).
--brackets=attach, -a
Attach brackets to pre-block statements (i.e. Java/K&R style).
--brackets=linux, -l
Break brackets from class and function declarations, but attach
brackets to pre-block command statements.
--brackets=horstmann, -g
Break brackets from their pre-block statements but allow run-in
statements on the same line as an opening bracket (e.g.
Horstmann style).
--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#.
Indentation Options:
--indent-classes, -C
Indent ’class’ blocks, so that the inner ’public:’, ’protected:’
and ’private:’ headers are indented in relation to the class
block. This option has no effect on Java and C# files.
--indent-switches, -S
Indent ’switch’ blocks, so that the inner ’case X:’ headers are
indented in relation to the switch block. The entire case block
is indented.
--indent-cases, -K
Indent ’case X:’ lines, so that they are flush with their
bodies. Case statements not enclosed in blocks are NOT indented.
--indent-brackets, -B
Add extra indentation to ’{’ and ’}’ block 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.
--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.
--indent-namespaces, -N
Add extra indentation to namespace blocks. This option has no
effect on Java files.
--indent-labels, -L
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).
--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.
--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.
--max-instatement-indent=#, -M#
Indent a maximum of # spaces in a continuous statement, relative
to the previous line. Must be less than 80. The default value
is 40.
--min-conditional-indent=#, -m#
Indent a minimal # spaces in a continuous conditional belonging
to a conditional header. Must be less than 40. The default
value is twice the current indent.
Formatting options:
--break-blocks, -f
Insert empty lines around header blocks (e.g. ’if’, ’while’...).
--break-blocks=all, -F
Like --break-blocks, except also insert empty lines around
closing headers (e.g. ’else’, ’catch’, ...).
--break-closing-brackets, -y, --brackets=break-closing (deprecated)
Break brackets before closing headers (e.g. ’else’, ’catch’,
..). Should be appended to --brackets=attach, --brackets=linux
or --brackets=stroustrup. Closing header brackets are always
broken with broken 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.
--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.
--pad-paren, -p, --pad=paren (deprecated)
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, --pad=paren-out (deprecated)
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-paren-in, -D, --pad=paren-in (deprecated)
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, --unpad=paren (deprecated)
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.
--keep-one-line-statements, -o, --one-line=keep-statements (deprecated)
Don’t break complex statements and multiple statements residing
on a single line.
--keep-one-line-blocks, -O, --one-line=keep-blocks (deprecated)
Don’t break blocks residing completely on one 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.
--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. The spacing between the type and name
will be preserved, if possible. This option is effective for
C/C++ files only.
--fill-empty-lines, -E
Fill empty lines with the white space of their previous lines.
Indentation modes:
The modes used for indentation are set by each file’s extension, but it
can be overriden with the following options:
--mode=c
Indent a C or C++ source file (default).
--mode=java
Indent a Java(TM) source file.
--mode=cs
Indent a C sharp source file.
Other options:
--suffix=####
Append the suffix #### instead of ’.orig’ to original filename.
--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. 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").
--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.
--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.
-V, --version
Print version number
-h, -?, --help
Show summary of 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
1.23
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>