.TH ASTYLE 1 "February 21, 2011" astyle "User's Manual"
.SH NAME
astyle \- indentation and reformatting filters for C, C++, C#, Java

.SH SYNOPSIS
.B astyle
[\fIOPTIONS\fR] < \fIOriginal\fR > \fIBeautified\fR

\fBastyle\fR [\fIOPTIONS\fR] [\fIFILE1\fR] [\fIFILE2\fR] [\fI...\fR]

.SH DESCRIPTION
\fBArtistic Style\fR (or \fBastyle\fR) 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 \fBastyle\fR 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.

.SH 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
\fB$HOME/.astylerc\fR, or be specified in the \fBARTISTIC_STYLE_OPTIONS\fR
environment variable or the \fB\-\-options\fR command line option.

.SH 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, \fB\-bps4\fR is the same as \fB\-b \-p \-s4\fR.

A summary of the options supported by \fBastyle\fR is included below.

.SS "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.

.TP
\fB\-\-style=\fR\fIansi\fR, \fB\-\-style=\fR\fIallman\fR, \fB\-\-style=\fR\fIbsd\fR, \fB\-A\fR\fI1 \fR
ANSI style formatting/indenting. Uses broken brackets.
.TP
\fB\-\-style=\fR\fIjava\fR, \fB\-A\fR\fI2\fR
Java style formatting/indenting. Uses attached brackets.
.TP
\fB\-\-style=\fR\fIk&r\fR, \fB\-\-style=\fR\fIk/r\fR, \fB\-A\fR\fI3\fR
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.
.TP
\fB\-\-style=\fR\fIstroustrup\fR, \fB\-A\fR\fI4\fR
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.
.TP
\fB\-\-style=\fR\fIwhitesmith\fR, \fB\-A\fR\fI5\fR
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). 
.TP
\fB\-\-style=\fR\fIbanner\fR, \fB\-A\fR\fI6\fR
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). 
.TP
\fB\-\-style=\fR\fIgnu\fR, \fB\-A\fR\fI7\fR
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.
.TP
\fB\-\-style=\fR\fIlinux\fR, \fB\-A\fR\fI8\fR
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. \fBIndentation\fR is 8 spaces.
\fBMinimum conditional indent\fR is 4 spaces, or one-half the spaces per indent
if a different setting is used. If you want to change the spaces per indent for
this style it will be easier to use the K&R style instead.

Also known as Kernel Normal Form (KNF) style, this is the style used in the
Linux kernel.
.TP
\fB\-\-style=\fR\fIhorstmann\fR, \fB\-A\fR\fI9\fR
Horstmann style formatting/indenting uses horstmann style brackets.
Brackets are broken with run-in statements. Switches are indented.
Indentation is 3 spaces. 
.TP
\fB\-\-style=\fR\fI1tbs\fR, \fB\-\-style=\fR\fIotbs\fR, \fB\-A\fR\fI10\fR
"One True Brace Style" formatting/indenting uses linux style brackets
and adds brackets to unbracketed one line conditional statements. The
option \fB\-\-add\-one\-line\-brackets\fR can also be used with this style.

.SS "Tab and Bracket Options:"

If no indentation option is set, the default option of 4 spaces will be
used. Equivalent to \fB\-s\fR4 \fB\-\-indent=\fR\fIspaces=4\fR.  If no brackets
option is set, the brackets will not be changed.

.TP
\fB\-\-indent=\fR\fIspaces\fR, \fB\-\-indent=\fR\fIspaces=#\fR, \fB\-s\fR, \fB\-s\fR\fI#\fR 
Indent using # spaces per indent. Between 1 to 20.  Not specifying # will
result in a default of 4 spaces per indent.
.TP
\fB\-\-indent=\fR\fItab\fR, \fB\-\-indent=\fR\fItab=#\fR, \fB\-t\fR, \fB\-t\fR\fI#\fR
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.
.TP
\fB\-\-indent=\fR\fIforce\-tab\fR, \fB\-\-indent=\fR\fIforce\-tab=#\fR, \fB\-T\fR, \fB\-T\fR\fI#\fR
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.
.TP
\fB\-\-brackets=\fR\fIbreak\fR, \fB\-b\fR
Break brackets from pre-block statements (i.e. ANSI C/C++ style).
.TP
\fB\-\-brackets=\fR\fIattach\fR, \fB\-a\fR
Attach brackets to pre-block statements (i.e. Java/K&R style).
.TP
\fB\-\-brackets=\fR\fIlinux\fR, \fB\-l\fR
Break brackets from class and function declarations, but attach brackets
to pre-block command statements.
.TP
\fB\-\-brackets=\fR\fIhorstmann\fR, \fB\-g\fR
Break brackets from their pre-block statements but allow run-in
statements on the same line as an opening bracket (e.g. Horstmann
style).
.TP
\fB\-\-brackets=\fR\fIstroustrup\fR, \fB\-u\fR
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#.

.SS "Indentation Options:"
.TP
\fB\-\-indent\-classes\fR, \fB\-C\fR
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.
.TP
\fB\-\-indent\-switches\fR, \fB\-S\fR
Indent 'switch' blocks, so that the inner 'case X:' headers are indented in
relation to the switch block.  The entire case block is indented.
.TP
\fB\-\-indent\-cases\fR, \fB\-K\fR
Indent 'case X:' lines, so that they are flush with
their bodies. Case statements not enclosed in blocks are NOT indented.
.TP
\fB\-\-indent\-brackets\fR, \fB\-B\fR
Add extra indentation to '{' and '}' block brackets. This is the option
used for Whitesmith and Banner style formatting/indenting. If both 
\fB\-\-indent\-brackets\fR and \fB\-\-indent\-blocks\fR are used the
result will be \fB\-\-indent\-blocks\fR.
.TP
\fB\-\-indent\-blocks\fR, \fB\-G\fR
Add extra indentation to blocks \fBwithin a function\fR. The opening
bracket for namespaces, classes, and functions is not indented. This is the
option used for GNU style formatting/indenting.
.TP
\fB\-\-indent\-namespaces\fR, \fB\-N\fR
Add extra indentation to namespace blocks. This option has no effect on
Java files.
.TP
\fB\-\-indent\-labels\fR, \fB\-L\fR
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).
.TP
\fB\-\-indent\-preprocessor\fR, \fB\-w\fR
Indent multi-line preprocessor definitions ending with a backslash. Should
be used with \fB\-\-convert\-tabs\fR for proper results. Does a pretty good
job, but can not perform miracles in obfuscated preprocessor definitions.
.TP
\fB\-\-indent\-col1\-comments\fR, \fB\-Y\fR
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.
.TP
\fB\-\-max\-instatement\-indent=\fR\fI#\fR, \fB\-M\fR\fI#\fR
Indent a maximum of # spaces in a continuous statement,
relative to the previous line. Must be less than 80. 
The default value is 40.
.TP
\fB\-\-min\-conditional\-indent=\fR\fI#\fR, \fB\-m\fR\fI#\fR
Indent a minimal # spaces in a continuous conditional
belonging to a conditional header.  Must be less than 40. 
The default value is \fBtwice the current indent\fR.

.SS "Formatting options:"
.TP
\fB\-\-break\-blocks\fR, \fB\-f\fR
Insert empty lines around header blocks (e.g. 'if', 'while'...).
.TP
\fB\-\-break\-blocks=\fR\fIall\fR, \fB\-F\fR
Like \-\-break\-blocks, except also insert empty lines 
around closing headers (e.g. 'else', 'catch', ...).
.TP
\fB\-\-break\-closing\-brackets\fR, \fB\-y\fR
When used with \fB\-\-brackets\fR=attach, \fB\-\-brackets=\fR\fIlinux
or \fB\-\-brackets\fR=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.
.TP
\fB\-\-break\-elseifs\fR, \fB\-e\fR
Break "else if" header combinations into separate lines. This option has
no effect if \fB\-\-keep\-one\-line\-statements\fR 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.
.TP
\fB\-\-add\-brackets\fR, \fB\-j\fR
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
\fB\-\-add\-one\-line\-brackets\fR is also used the result will be one line
brackets.
.TP
\fB\-\-add\-one\-line\-brackets\fR, \fB\-J\fR
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 \fB\-\-keep\-one\-line\-blocks\fR and will not break the
one line blocks.
.TP
\fB\-\-delete\-empty\-lines\fR, \fB\-x\fR
Delete empty lines within a function or method. Empty lines outside of
functions or methods are NOT deleted. If used with \fB\-\-break\-blocks\fR
or \fB\-\-break\-blocks\fR=all it will delete all lines \fBexcept\fR the
lines added by the \fB\-\-break\-blocks\fR options.
.TP
\fB\-\-pad\-oper\fR, \fB\-p\fR
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.
.TP
\fB\-\-pad\-paren\fR, \fB\-P\fR
Insert space padding around parenthesis on both the \fBoutside\fR and the
\fBinside\fR. Any end of line comments will remain in the original column,
if possible.
.TP
\fB\-\-pad\-paren\-out\fR, \fB\-d\fR
Insert space padding around parenthesis on the \fBoutside\fR only. Any end of
line comments will remain in the original column, if possible. This can be
used with \fB\-\-unpad\-paren\fR below to remove unwanted spaces.
.TP
\fB\-\-pad\-paren\-in\fR, \fB\-D\fR
Insert space padding around parenthesis on the \fBinside\fR only. Any end
of line comments will remain in the original column, if possible. This can
be used with \fB\-\-unpad\-paren\fR below to remove unwanted spaces.
.TP
\fB\-\-pad\-header\fR, \fB\-H\fR
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
\fB\-\-unpad\-paren\fR to remove unwanted spaces.
.TP
\fB\-\-unpad\-paren\fR, \fB\-U\fR
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
\fB\-\-pad\-paren\-out\fR and \fB\-\-pad\-paren\-in\fR 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 \fB\-\-unpad\-paren\fR to remove the
outside padding, and \fB\-\-pad\-paren\-in\fR to retain the inside padding.
Using only \fB\-\-pad\-paren\-in\fR would not remove the outside padding.
.TP
\fB\-\-keep\-one\-line\-statements\fR, \fB\-o\fR
Don't break complex statements and multiple statements residing on a single
line.
.TP
\fB\-\-keep\-one\-line\-blocks\fR, \fB\-O\fR
Don't break blocks residing completely on one line
.TP
\fB\-\-convert\-tabs\fR, \fB\-c\fR
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 \fB\-\-convert\-tabs\fR is used when changing spaces per tab. Tabs are not
replaced in quotes.
.TP
\fB\-\-align\-pointer=\fR\fItype\fR, \fB\-k\fR\fI1\fR
.TP
\fB\-\-align\-pointer=\fR\fImiddle\fR, \fB\-k\fR\fI2\fR
.TP
\fB\-\-align\-pointer=\fR\fIname\fR, \fB\-k\fR\fI3\fR
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.
.TP
\fB\-\-fill\-empty\-lines\fR, \fB\-E\fR
Fill empty lines with the white space of their previous lines.

.SS "Indentation modes:"
The modes used for indentation are set by each file's extension, but it can 
be overridden with the following options:
.TP
\fB\-\-mode=\fR\fIc\fR
Indent a C or C++ source file (default).
.TP
\fB\-\-mode=\fR\fIjava\fR
Indent a Java(TM) source file.
.TP
\fB\-\-mode=\fR\fIcs\fR
Indent a C sharp source file.

.SS "Other options:"
.TP
\fB\-\-suffix=\fR\fI####\fR
Append the suffix \fI####\fR instead of '.orig' to original filename.
.TP
\fB\-\-suffix=\fR\fInone\fR, \fB\-n\fR
Do not retain a backup of the original file. The original file is purged
after it is formatted.
.TP
\fB\-\-options=\fR\fI####\fR
Specify an options file \fI####\fR to read and use.
.TP
\fB\-\-options=\fR\fInone\fR
Disable the default options file. Only the command-line parameters will be
used.
.TP
\fB\-\-recursive\fR, \fB\-r\fR, \fB\-R\fR
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"). 
.TP
\fB\-\-exclude=\fR\fI####\fR
Specify a file or sub directory \fI####\fR 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.
\fB\-\-exclude=\fR"foo bar.cpp").
.TP
\fB\-\-errors\-to\-stdout\fR, \fB\-X\fR
Print errors and help information to standard-output rather than
to standard-error.
.TP
\fB\-\-preserve\-date\fR, \fB\-Z\fR
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.
.TP
\fB\-\-verbose\fR, \fB\-v\fR
Verbose display mode. Display optional information, such as release number
and statistical data.
.TP
\fB\-\-formatted\fR, \fB\-Q\fR
Formatted files display  mode. Display only the files that have been
formatted. Do not display files that are unchanged.
.TP
\fB\-\-quiet\fR,\fB\-q\fR
Quiet display mode. Suppress all output except error messages.
.TP
\fB\-\-lineend=\fR\fIwindows\fR, \fB\-z\fR\fI1\fR
.TP
\fB\-\-lineend=\fR\fIlinux\fR, \fB\-z\fR\fI2\fR
.TP
\fB\-\-lineend=\fR\fImacold\fR, \fB\-z\fR\fI3\fR
Force use of the specified line end style. Valid options are
\fIwindows\fR (CRLF), \fIlinux\fR (LF), and \fImacold\fR (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.
.TP
\fB\-V, \-\-version\fR
Print version number
.TP
\fB\-h, \-?, \-\-help\fR
Show summary of Options

.SH FILES
Artistic Style looks for a default options file in the
following order:
.TP
.B 1.
The contents of the file indicated by the \-\-options= command line option;
.B 2.
The contents of the \fIARTISTIC_STYLE_OPTIONS\fR environment variable if it
exists.
.TP
.B 3.
The file called \fI.astylerc\fR in the directory pointed to by the
\fIHOME\fR environment variable (i.e. \fI$HOME/.astylerc\fR).
.TP
.B 4.
The file called \fI.astylerc\fR in the directory pointed to by the
\fIHOMEPATH\fR environment variable (i.e. \fI%HOMEPATH%\.astylerc\fR).
.P
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.
.P
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.

.SH VERSION
2.01

.SH "SEE ALSO"
.BR indent(1)

.I http://astyle.sourceforge.net/
.br
.I http://www.sourceforge.net/projects/astyle/
.br
.I http://packages.debian.org/astyle

.SH 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
\fIhttp://www.netmeister.org/misc/m2p2/index.html\fR for details.

Minor modifications by Luca Filipozzi <lfilipoz@debian.org>. Updated on
August 2009 by Margarita Manterola <marga@debian.org>. Updated on April
2010, February 2011 by Matteo Cypriani <mcy@lm7.fr>.