Artistic Style

# Artistic Style 1.17.0-dev

## A Free, Fast and Small Automatic Formatter
for C, C++, C#, and Java Source Codes

Project Overview | http://astyle.sourceforge.net
Sources, Binaries, Bug Tracker, Mailinglists | http://www.sourceforge.net/projects/astyle/
Original Author | Tal Davidson, Israel (tald@users.sourceforge.net)
Maintainer | Martin Baute, Germany (devsolar@sourceforge.net)

Artistic Style is a reindenter and reformatter for C, C++, C#, and Java source code.

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 (unless the user sets up the number to his liking...), one of the standard problems programmers are facing when moving from one 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, Artistic Style was created - a filter written in C++, that automatically reindents & reformats C / C++ / C# / Java source files. It can be used from a command line, or it can be incorporated in another C++ program.

The AStyle executable is distributed under the terms of the GNU General Public License (GPL); you may incorporate the core classes (ASBeautifier and ASFormatter) in other projects subject to the GNU Lesser General Public License (LGPL). You may want to read the Release Notes.

## Installation

1. Download the 'astyle.zip' package from the SourceForge homepage;
2. unzip the package;
3. read the file README.txt for instructions;
4. compile 'astyle'.

For Windows users, we provide precompiled binaries in the 'astyle_win32.zip' package.

Either place the resulting executable file in your command path, or add the executable's directory to your command path.

## Usage

    astyle [options] <OriginalSourceFile >BeautifiedSourceFile

or

    astyle [options] Foo.java Bar.java Baz.java [ . . . ]

The < and > characters are used to redirect the files into standard input and out of standard output - don't forget them!

The newly indented file retains the original file name, while a copy of the original file is created with a "`.orig`" appended to the original file name. (This can be set to a different string by the option '`--suffix`', or suppressed altogether by the options '`-n`' or '`--suffix=none`.) Thus, after indenting "`Foo.java`" as above, the indented result will be named "`Foo.java`, while the original pre-indented file will be renamed to "`Foo.java.orig`".

### Options

Not specifying any option will result in C/C++ style indentation, with a default of 4 spaces per indent, and NO formatting.

Options may be written in two different ways:

1. Long options:
   These options start with '`--`', and must be written one at a time.
   (Example: '`--brackets=attach --pad --indent=spaces=4`)
2. Short Options:
   These options start with a single '`-`', and may be concatenated together.
   (Example: '`-bps4`' is the same as writing '`-b -p -s4`'.)

A default options file may be used to set your favourite source style. Artistic Style looks for this file in the following locations (in order):

1. the file indicated by the --options= command line option;
2. the file indicated by the environment variable ARTISTIC_STYLE_OPTIONS (if it exists);
3. the file named .astylerc in the directory pointed to by the HOME environment variable (i.e. '$HOME/.astylerc');
4. the file named .astylerc in the directory pointed to by the HOMEDRIVE and HOMEPATH environment variables (i.e. '%HOMEDRIVE%%HOMEPATH%\.astylerc).

This option file lookup can be disabled by specifying --options=none on the command line.

- Options may be set apart by new-lines, tabs or spaces.
- Long options in the options file may be written without the preceding '--'.
- Lines within the options file that begin with '#' are considered line-comments.

Example of a default options file:

>     # set default parsing to 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

#### Predefined Styles

> `--style=ansi`
> ANSI style formatting/indenting.

> >     namespace foospace
> >     {
> >         int Foo()
> >         {
> >             if (isBar)
> >             {
> >                 bar();
> >                 return 1;
> >             }
> >             else
> >                 return 0;
> >         }
> >     }

> `--style=kr`
> Kernighan&Ritchie style formatting/indenting.

> >     namespace foospace {
> >         int Foo() {
> >             if (isBar) {
> >                 bar();
> >                 return 1;
> >             } else
> >                 return 0;
> >         }
> >     }

> `--style=linux`
> Linux style formatting/indenting (brackets are broken apart from class/function declarations, but connected to command lines, and indents are set to 8 spaces).

> >     namespace foospace
> >     {
> >             int Foo()
> >             {
> >                     if (isBar) {
> >                             bar();
> >                             return 1;
> >                     } else
> >                             return 0;
> >             }
> >     }

> `--style=gnu`
> GNU style formatting/indenting.

> >     namespace foospace
> >     {
> >       int Foo()
> >         {
> >           if (isBar)
> >             {
> >               bar();
> >               return 1;
> >             }
> >           else
> >             return 0;
> >         }
> >     }

> `--style=java`
> Java style formatting/indenting.

> >     class foospace {
> >         int Foo() {
> >             if (isBar) {
> >                 bar();
> >                 return 1;
> >             } else
> >                 return 0;
> >         }
> >     }

#### Indentation Options

> `-c` / `--mode=c`
> Indent a C or C++ file.

> `-j` / `--mode=java`
> Indent a Java file.

> `--mode=csharp`
> Indent a C# file.

> `-s#` / `--indent=spaces=#`
> Indent using `#` spaces per indent (e.g. `-s4` / `--indent=spaces=4`).

> `-t` / `-t#` / `--indent=tab=#`
> Indent using tab characters. Treat each tab as `#` spaces. If no '`#`' is set, treats tabs as `4` spaces.

> `-T#` / `--force-indent=tab=#`
> Indent using tab characters. Treat each tab as `#` spaces. Uses tabs as indents where '`--indent=tab`' prefers to use spaces, such as inside multi-line statements.

> `-C` / `--indent-classes`
> Indent '`class`' blocks so that the headers '`public:`', '`protected:`' and '`private:`' are indented in the class block.

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

> > becomes:

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

> `-S` / `--indent-switches`
> Indent '`switch`' blocks so that the '`case X:`' headers are indented in the `switch` block.

> >     switch (foo)
> >     {
> >     case 1:
> >         a += 2;
> >         break;
> >     default:
> >         a += 3;
> >         break;
> >     }

> > becomes:

> >     switch (foo)
> >     {
> >         case 1:
> >             a += 2;
> >             break;
> >         default:
> >             a += 2;
> >             break;
> >     }

> `-K` / `--indent-cases`
> Indent '`case X:`' lines so that they are flush with the comand lines under them.

> >     switch (foo)
> >     {
> >     case 1:
> >         {
> >             a += 2;
> >             break;
> >         }
> >     default:
> >         {
> >             a += 2;
> >             break;
> >         }
> >     }

> > becomes:

> >     switch (foo)
> >     {
> >         case 1:
> >         {
> >             a += 2;
> >             break;
> >         }
> >         default:
> >         {
> >             a += 2;
> >             break;
> >         }
> >     }

> `-B` / `--indent-brackets`
> Add extra indentation to brackets.

> >     if (isFoo)
> >     {
> >         bar();
> >     }
> >     else
> >     {
> >         anotherBar();
> >     }

> > becomes:

> >     if (isFoo)
> >         {
> >         bar();
> >         }
> >     else
> >         {
> >         anotherBar();
> >         }

> `-G` / `--indent-blocks`
> Add extra indentation to entire blocks.

> >     if (isFoo)
> >     {
> >         bar();
> >     }
> >     else
> >         anotherBar();

> > becomes:

> >     if (isFoo)
> >         {
> >             bar();
> >         }
> >     else
> >         anotherBar();

> `-N` / `--indent-namespaces`
> Add extra indentation to namespaces.

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

> > becomes:

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

> `-L` / `--indent-labels`
> Add extra indentation to labels so they they appear 1 indent less than the current indentation, rather than being flushed to the left (the default).

> >     int foo()
> >     {
> >         while (isFoo)
> >         {
> >             ...
> >             goto error;

> >     error:
> >             ...
> >         }
> >     }

> > becomes:

> >     int foo()
> >     {
> >         while (isFoo)
> >         {
> >             ...
> >             goto error;

> >         error:
> >             ...
> >         }
> >     }

> `-M#` / `--max-instatement-indent=#`
> Indent a maximum of `#` spaces in a continuous statement, relatively to the previous line (e.g. `--max-instatement-indent=40`).

> `-m#` / `--min-conditional-indent=#`
> Set the minimal indent that is added when a header is built of multiple-lines. This indent makes helps to easily separate the header from the command statements that follow. The default setting for this option is twice the current indent (e.g. `--min-conditional-indent=8`).

> >     // 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++;
> >     }

> > becomes (when setting `--min-conditional-indent=0`):

> >     // 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++;
> >     }

> `--indent-preprocessor`
> Indent multi-line preprocessor definitions. should be used with `--convert-tabs` for proper results. Does a pretty good job, but can not perform miracles in obfuscated preprocessor definitions.

> `--convert-tabs`
> Converts tabs into single spaces.

> `-E` / `--fill-empty-lines`
> Fill empty lines with the white space of their previous lines.

#### Formatting Options

> `-b` / `--brackets=break`
> Break brackets from their pre-block statements ( i.e. ANSI C / C++ style ).

> >     if (isFoo)
> >     {
> >         bar();
> >     }
> >     else
> >     {
> >         baz();
> >     }

> `-a` / `--brackets=attach`
> Attach brackets to their pre-block statements ( i.e. Java / K&R style ).

> >     if (isFoo) {
> >         bar();
> >     } else {
> >         baz();
> >     }

> `-l` / `--brackets=linux`
> Break brackets from class/function declarations, but attach brackets to pre-block command statements.

> >     namespace foospace
> >     {
> >         int Foo()
> >         {
> >             if (isBar) {
> >                 bar();
> >                 return 1;
> >         }
> >             else
> >                 return 0;
> >         }
> >     }

> `--brackets=break-closing-headers`
> When used with either `--brackets=attach` or `--brackets= linux`, breaks closing headers (e.g. '`else`', '`catch`', ...) from their immediately preceding closing brackets.

> >     if (isFoo) {
> >         bar();
> >     } else {
> >         anotherBar();
> >     }

> > becomes:

> >     if (isFoo) {
> >         bar();
> >     }
> >     else {
> >         anotherBar();
> >     }

> `--break-blocks`
> Pad empty lines around header blocks (e.g. '`if`', '`while`'...).

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

> > becomes:

> >     isFoo = true;

> >     if (isFoo) {
> >         bar();
> >     } else {
> >         anotherBar();
> >     }

> >     isBar = false;

> `--break-blocks=all`
> Pad empty lines around header blocks (e.g. '`if`', '`while`'...). Treat closing header blocks (e.g. '`else`', '`catch`') as stand-alone blocks.

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

> > becomes:

> >     isFoo = true;

> >     if (isFoo) {
> >         bar();

> >     } else {
> >         anotherBar();
> >     }

> >     isBar = false;

> `--break-elseifs`
> Break '`else if()`' header combinations into seperate lines.

> >     if (isFoo) {
> >         bar();
> >     } else if (isBar()) {
> >         anotherBar();
> >     }

> > becomes:

> >     if (isFoo) {
> >         bar();
> >     } else
> >     if (isBar()) {
> >         anotherBar();
> >     }

> `-p` / `--pad=oper`
> Insert space padding around operators only.

> >     if (isFoo)
> >         a = bar((b-c)*a,*d--);

> > becomes:

> >     if (isFoo)
> >         a = bar((b - c) * a, *d--);

> `--pad=paren`
> Insert space padding around parenthesies only.

> >     if (isFoo)
> >         a = bar((b-c)*a,*d--);

> > becomes:

> >     if ( isFoo )
> >         a = bar( ( b-c )*a, *d-- );

> `-P` / `--pad=all`
> Insert space padding around operators and parentheses.

> >     if (isFoo)
> >         a = bar((b-c)*a,*d--);

> > becomes:

> >     if ( isFoo )
> >         a = bar( ( b - c ) * a, *d-- );

> `-o` / `--one-line=keep-statements`
> Don't break complex statements and multiple statements residing in a single line.

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

> > remains as is.

> >     if (isFoo) DoBar();

> > remains as is.

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

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

> > remains as is.

#### Other Options

> `--suffix=####`
> Append the suffix #### instead of '.orig' to original filename (e.g. --suffix=.bak).

> `-n` / `--suffix=none`
> Tells Astyle not to keep backups of the original source files.
> WARNING: Use this option with care, as Astyle comes with NO WARRANTY...

> `--options=####`
> Specify an options file #### to read and use.

> `--options=none`
> Disable options file lookup altogether.

> `-X` / `--errors-to-standard-output`
> Print errors to standard-output rather than to standard-error.
> This option should be helpful for systems/shells that do not have this option, such as in Windows95.

> `-v` / `--version`
> Print version number.

> `-h` / `-?` / `--help`
> Print a help message and quit.

### Acknowledgements

- Thanks to Jim Watson, Fred Shwartz, W. Nathaniel Mills III, Danny Deschenes, Andre Houde, Richard Bullington, Paul-Michael Agapow, and Daryn Adler for their patches and contributions to Artistic Style;
- thanks to Richard Bullington and MicroState for giving Artistic Style its first mailing-list;
- thanks to SourceForge for giving Artistic Style its home;
- thanks to Paul Michael Agapow for creating a GUI interface for Artistic Style on the Macintosh;
- thanks to all the dedicated beta-testers and bug notifiers!

### Copying

Astyle is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

Astyle is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

This documentation is placed in the Public Domain. Use, modify, and redistribute at will.