.TH ASTYLE 1 "26 September 1999" "Version 1.11.6"
.\"======================================================================
.SH NAME
astyle (Artistic Style) \- prettyprint C, C++, and Java source code
.\"======================================================================
.SH SYNOPSIS
.B astyle
.RB [ options ]
.RI < original-file
.RI > prettyprinted-file
.nf
or
.fi
.B astyle
.RB [ options ]
.RI file(s)
.PP
When indenting a specific file (instead of
.IR stdin ),
the resulting indented file
.I retains
the original filename. The original pre-indented file is renamed, with
a suffix of
.I .orig
added to the original filename.
.PP
By default,
.B astyle
is set up to indent C/C++ files, with 4 spaces per indent, a maximal
indentation of 40 spaces inside continuous statements, and
.I no
formatting.
.\"======================================================================
.SH DESCRIPTION
.B astyle
(Artistic Style) is a reindenter and reformatter of C, C++, and Java
source code.
.PP
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
.I "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.
.PP
Since the
.I 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,
suddenly becomes a mess to look at when changing to another
editor. Even if you as a programmer take care to
.I only
use spaces or tabs, looking at other people's source code can still be
problematic.
.PP
To address this problem I have created
.B astyle
(Artistic Style) \(em a series of filters, written in C++, that
automatically reindent & reformat C/C++/Java source files. These can
be used from a command line, or they can be incorporated as classes in
another C++ program.
.\"======================================================================
.SH OPTIONS
Long options (starting with
.BR \-\|\- )
must be written one at a time.  Short options (starting with
.BR \- )
may be appended together.  Thus,
.B \-bps4
is the same as
.B \-b
.B \-p
.BR \-s4.
.\"---------------------------------------------------------------------
.TP
.B \-a
.br
.ns
.TP
.BI \-\|\-brackets =attach
Attach brackets to pre-block code (i.e., Java/K&R style).
.IP
Sample formatting with this option:
.nf
\&\fCif (isFoo){
    bar();
} else {
    anotherBar();
}\fP
.fi
.\"---------------------------------------------------------------------
.TP
.B \-B
.br
.ns
.TP
.B \-\|\-indent-brackets
Add extra indentation to
.I {
and
.I }
block brackets.
.IP
Sample formatting without this option:
.nf
\&\fCif (isFoo)
{
    bar();
}
else
{
    anotherBar();
}\fP
.fi
Sample formatting with this option:
.nf
\&\fCif (isFoo)
    {
    bar();
    }
else
    {
    anotherBar();
    }\fP
.fi
.\"---------------------------------------------------------------------
.TP
.B \-b
.br
.ns
.TP
.BI \-\|\-brackets =break
Break brackets from pre-block code (i.e., ANSI C/C++ style).
.IP
Sample formatting with this option:
.nf
\&\fCif (isFoo)
{
    bar();
}
else
{
    anotherBar();
}\fP
.fi
.\"---------------------------------------------------------------------
.TP
.B \-C
.br
.ns
.TP
.B \-\|\-indent-classes
Indent
.I class
blocks, so that the inner
.IR public: ,
.IR protected: ,
and
.I private:
headers are indented in relation to the
.I class
block.
.IP
Sample formatting without this option:
.nf
\&\fCclass Foo
{
public:
    Foo();
    virtual ~Foo();
};\fP
.fi
Sample formatting with this option:
.nf
\&\fCclass Foo
{
    public:
	Foo();
	virtual ~Foo();
};\fP
.fi
.\"---------------------------------------------------------------------
.TP
.B \-c
.br
.ns
.TP
.BI \-\|\-mode =c
Indent a C or C++ source file (default).
.\"---------------------------------------------------------------------
.TP
.B \-E
.br
.ns
.TP
.B \-\|\-fill-empty-lines
Fill empty lines with the white space of their previous lines.
.\"---------------------------------------------------------------------
.TP
.B \-G
.br
.ns
.TP
.B \-\|\-indent-blocks
Add extra indentation for entire blocks (including brackets).
.IP
Sample formatting without this option:
.nf
\&\fCif (isFoo)
{
    bar();
}
else
    anotherBar();\fP
.fi
Sample formatting with this option:
.nf
\&\fCif (isFoo)
    {
	bar();
    }
else 
    anotherBar();\fP
.fi
.\"---------------------------------------------------------------------
.TP
.B \-h
.br
.ns
.TP
.B \-?
.br
.ns
.TP
.B \-\|\-help
Print help message on
.IR stderr .
.\"---------------------------------------------------------------------
.TP
.B \-j
.br
.ns
.TP
.BI \-\|\-mode =java
Indent a Java(TM) source file.
.\"---------------------------------------------------------------------
.TP
.B \-K
.br
.ns
.TP
.B \-\|\-indent-cases
Indent
.I "case XXX:"
lines, so that they are flush with their bodies.
.IP
Sample formatting without this option:
.nf
\&\fCswitch (foo)
{
case 1:
    {
	a += 2;
	break;
    }
default:
    {
	a += 2;
	break;
    }
}\fP
.fi
Sample formatting with this option:
.nf
\&\fCswitch (foo)
{
    case 1:
    {
	a += 2;
	break;
    }
    default:
    {
	a += 2;
	break;
    }
}\fP
.fi
.\"---------------------------------------------------------------------
.TP
.B \-L
.br
.ns
.TP
.B \-\|\-indent-labels
Indent labels so that they appear one indent less than the current
indentation level, rather than being flushed completely to the left
(which is the default).
.IP
Sample formatting without this option:
.nf
\&\fCint foospace()
{
    while (isFoo)
    {
	...
	goto error;
error:
	...
    }
}\fP
.fi
Sample formatting with this option:
.nf
\&\fCint foospace()
{
    while (isFoo)
    {
	...
	goto error;
    error:
	...
    }
}\fP
.fi
.\"---------------------------------------------------------------------
.TP
.B \-l
.br
.ns
.TP
.BI \-\|\-brackets =linux
Break definition-block brackets and attach command-block brackets.
.IP
Sample formatting with this option:
.nf
\&\fCnamespace foospace
{
    int Foo()
    {
	if (isBar) {
	    bar();
	    return 1;
	} else
	    return 0;
    }
}\fP
.fi
.\"---------------------------------------------------------------------
.TP
.B \-M#
.br
.ns
.TP
.BI \-\|\-max-instatement-indent =#
Indent a maximal # spaces in a continuous statement, relatively to the
previous line.
.\"---------------------------------------------------------------------
.TP
.B \-m
.br
.ns
.TP
.BI \-\|\-min-conditional-indent =#
Indent a minimal # spaces in a continuous conditional belonging to a
conditional header.
.IP
Sample formatting without this option:
.nf
\&\fC// default setting makes this non-bracketed code clear
if (a < b
	|| c > d)
    foo++;
// but creates an exaggerated indent in this bracketed code
if (a < b
	|| c > d)
{
    foo++;
}\fP
.fi
Sample formatting with 
.BI \-\|\-min-conditional-indent =0:
.nf
\&\fC// setting makes this non-bracketed code less clear
if (a < b
    || c > d)
    foo++;
// but makes this bracketed code prettier
if (a < b
    || c > d)
{
    foo++;
}\fP
.fi
.\"---------------------------------------------------------------------
.TP
.B \-N
.br
.ns
.TP
.B \-\|\-indent-namespaces
Indent the contents of namespace blocks.
.IP
Sample formatting without this option:
.nf
\&\fCnamespace foospace
{
class Foo
{
    public:
	Foo();
	virtual ~Foo();
};
}\fP
.fi
Sample formatting with this option:
.nf
\&\fCnamespace foospace
{
    class Foo
    {
	public:
	    Foo();
	    virtual ~Foo();
    };
}\fP
.fi
.\"---------------------------------------------------------------------
.TP
.B \-O
.br
.ns
.TP
.BI \-\|\-one-line =keep-blocks
Don't break blocks residing completely on one line.
.\"---------------------------------------------------------------------
.TP
.B \-o
.br
.ns
.TP
.BI \-\|\-one-line =keep-statements
Don't break lines containing multiple statements into multiple
single-statement lines.
.\"---------------------------------------------------------------------
.TP
.B \-P
.br
.ns
.TP
.BI \-\|\-pad =all
Insert space paddings around operators
.I and
parentheses.
.IP
Sample formatting without this option:
.nf
\&\fCif (isFoo)
    a = bar((b-c)*a,*d--);\fP
.fi
Sample formatting with this option:
.nf
\&\fCif ( isFoo )
    a = bar( ( b - c ) * a, *d-- );\fP
.fi
.\"---------------------------------------------------------------------
.TP
.B \-p
.br
.ns
.TP
.BI \-\|\-pad =oper
Insert space paddings around operators only.
.IP
Sample formatting without this option:
.nf
\&\fCif (isFoo)
    a = bar((b-c)*a,*d--);\fP
.fi
Sample formatting with this option:
.nf
\&\fCif (isFoo)
    a = bar((b - c) * a, *d--);\fP
.fi
.\"---------------------------------------------------------------------
.TP
.BI \-\|\-pad =paren
Insert space paddings around parentheses only.
.IP
Sample formatting without this option:
.nf
\&\fCif (isFoo)
    a = bar((b-c)*a,*d--);\fP
.fi
Sample formatting with this option:
.nf
\&\fCif ( isFoo )
    a = bar( ( b-c )*a, *d-- );\fP
.fi
.\"---------------------------------------------------------------------
.TP
.B \-S
.br
.ns
.TP
.B \-\|\-indent-switches
Indent
.I switch
blocks, so that the inner
.I "case XXX:"
headers are indented in relation to the switch block.
.IP
Sample formatting without this option:
.nf
\&\fCswitch (foo)
{
case 1:
    a += 2;
    break;
default:
    a += 2;
    break;
}\fP
.fi
Sample formatting with this option:
.nf
\&\fCswitch (foo)
{
    case 1:
	a += 2;
	break;
    default:
	a += 2;
	break;
}\fP
.fi
.\"---------------------------------------------------------------------
.TP
.B \-s
.br
.ns
.TP
.B \-s#
.br
.ns
.TP
.BI \-\|\-indent =spaces=#
Indent using # spaces per indent. Not specifying # will result in a
default of 4 spaces per indent.
.\"---------------------------------------------------------------------
.TP
.BI \-\|\-style =ansi
.br
.ns
.TP
.BI \-\|\-style =kr
.br
.ns
.TP
.BI \-\|\-style =gnu
.br
.ns
.TP
.BI \-\|\-style =java
.br
.ns
.TP
.BI \-\|\-style =linux
Choose ANSI, Kernighan & Ritchie, GNU, Java, or GNU/Linux style
prettyprinting.
.\"---------------------------------------------------------------------
.TP
.BI \-\|\-suffix =####
Append the suffix
.I ####
instead of
.I .orig
to the original filenames.
.\"---------------------------------------------------------------------
.TP
.B \-t
.br
.ns
.TP
.B \-t#
.br
.ns
.TP
.BR \-\|\-indent =tab=#
Indent using tab characters, assuming that each tab is # spaces
long. Not specifying # will result in a default assumption of 4 spaces
per tab.
.\"---------------------------------------------------------------------
.TP
.B \-v
.br
.ns
.TP
.B \-\|\-version
Print version number on
.IR stderr .
.\"---------------------------------------------------------------------
.TP
.B \-X
.br
.ns
.TP
.B \-\|\-errors-to-standard-output
Print errors and help information to
.IR stdout ,
rather than to
.IR stderr .
.\"======================================================================
.SH "DEFAULT OPTIONS"
.B astyle
looks for a default options file in the
following order:
.TP \w'1.'u+2n
1.
The contents of the file named by the
.B ARTISTIC_STYLE_OPTIONS
environment
variable, if that variable exists.
.TP
2.
The file called
.I .astylerc
in the directory pointed to by the
.B HOME
environment variable (i.e.,
.IR "$HOME/.astylerc" ).
.TP
3.
The file called
.I .astylerc
in the directory pointed to by the
.B HOMEPATH
environment variable
(i.e.,
.IR "$HOMEPATH/.astylerc" ).
.PP
At most
.I one
default options file is processed, and if one is found, the options in
it will be parsed
.I before
the command-line options.
.PP
Options within the default option file may be written without the
preliminary
.B \-
or
.BR \-\|\- .
.PP
Options may be set apart by newlines, tabs or spaces.
.PP
Long options may be written in the options file without the preceding
.BR \-\|\- .
.PP
Lines within the options file that begin with
.I #
are considered comments.
.PP
Here is a sample default options file:
.RS
.nf
\&\fC# default parsing is of java files
mode=java
# brackets should be attached to pre-bracket lines
brackets=attach
# set 6 spaces per indent
indent=spaces=6
# indent switch blocks
indent-switches
# suffix of original files should be .pre
suffix=.pre\fP
.fi
.RE
.\"======================================================================
.SH "STYLE SAMPLES"
Here are samples of each of the supported formatting styles:
.TP
.BI \-\|\-style =ansi
ANSI style formatting/indenting.
.nf
\&\fCnamespace foospace
{
    int Foo()
    {
        if (isBar)
        {
            bar();
            return 1;
        }
        else
            return 0;
    }
}\fP
.fi
.TP
.BI \-\|\-style =kr
Kernighan & Ritchie style formatting/indenting.
.nf
\&\fCnamespace foospace {
    int Foo() {
        if (isBar) {
            bar();
            return 1;
        } else
            return 0;
    }
}\fP
.fi
.TP
.BI \-\|\-style =linux
GNU/Linux style formatting/indenting (brackets are broken apart from
class/function declarations, but connected to command lines, and
indents are set to 8 spaces).
.nf
\&\fCnamespace foospace
{
        int Foo()
        {
                if (isBar) {
                        bar();
                        return 1;
                } else
                        return 0;
        }
}\fP
.fi
.TP
.BI \-\|\-style =gnu
GNU style formatting/indenting.
.nf
\&\fCnamespace foospace
  {
    int Foo()
      {
        if (isBar)
          {
            bar();
            return 1;
          }
        else
          return 0;
      }
}\fP
.fi
.TP
.BI \-\|\-style =java
Java style formatting/indenting.
.nf
\&\fCclass foospace {
    int Foo() {
        if (isBar) {
            bar();
            return 1;
        } else
            return 0;
    }
}\fP
.fi
.\"======================================================================
.SH "ENVIRONMENT VARIABLES"
.TP \w'\fBARTISTIC_STYLE_OPTIONS\fP'u+2n
.B ARTISTIC_STYLE_OPTIONS
Primary default option filename.
.TP
.B HOME
Secondary default option file directory
.RI ( $HOME/.astylerc ).
.TP
.B HOMEPATH
Tertiary default option file directory
.RI ( $HOMEPATH/.astylerc ).
.\"======================================================================
.SH "SEE ALSO"
.BR awkpretty (1),
.BR html-pretty (1),
.BR indent (1),
.BR pindent (1),
.BR pretty (1),
.BR sf3pretty (1),
.BR tex-pretty (1).
.\"======================================================================
.SH AUTHOR
.nf
Tal Davidson
Israel
email: \fCdavidsont@bigfoot.com\fP
WWW URL: \fChttp://astyle.sourceforge.net/astyle\fP
.fi
.\"==============================[The End]==============================