Artistic Style
Description: Artistic Style is a source code indenter, source code formatter, and source code beautifier for the C, C++, C# and Java programming languages.
Keywords: artistic style, astyle, source code indenter, source code formatter, source code beautifier

> # Artistic Style 1.19

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

> #### by Tal Davidson
> and Jim Pattee

> Home Page: | http://astyle.sourceforge.net/
> Project Page: | http://sourceforge.net/projects/astyle/

> Artistic Style is a source code indenter, source code formatter, and source code 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 (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, suddenly 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 people's source code can still be problematic.

> To address this problem, Artistic Style was created - a filter written in C++ that automatically re-indents and re-formats C / C++ / C# / Java source files. It can be used from a command line, or it can be incorporated as classes in another C++ program.

> Artistic Style may be used and distributed under the GNU General Public License (GPL).

> ### Read the News and Release Notes

> Bug fixes for `pad=oper` and `pad=paren`, a new option `unpad=paren,` padding of paren headers, and new release frequency.

> ### Read the Supplemental Documentation

> There are some formatting problems with `--break-blocks` (or `--break-blocks=all`).

> ### Read the Installation Information

> Download the latest release from the file releases page. The latest release is indicated by the line with a green background. Get the file for the appropriate platform (Linux or Windows).
> Decompress the package, if necessary. Most operating systems will decompress and display the package contents automatically. It can then be copied to a work folder.
> Follow the installation information for the appropriate platform.

> ### Bug Reports, Change Requests, Notification

> Bug reports and change requests should submitted to the bug tracker page. It is best to log in to SourceForge before submitting a report so you can be contacted if necessary. Note that code copied and pasted into the bug report will not be indented after the data is submitted. You must indicate the indentation when you submit the request (e.g. replace leading spaces with periods).

> Notification of new releases is activated from the file releases page. In Latest File Releases, under Notes / Monitor, click on the envelope. You will receive notification when a new release is available.

> To contact the project by email use the address jimp03@email.com.

> ## Usage

> Artistic style is a console program that receives information from the command line. The format of the command line is:

>     astyle [options]  SourceFile1.cpp  SourceFile2.cpp  SourceFile3.cpp [ . . . ]

> Or to save the file with a different name:

>     astyle [options] < OriginalSourceFile > BeautifiedSourceFile

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

> With the first option, 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 `SourceFile1.cpp` as above, the indented result will be named `SourceFile1.cpp`, while the original pre-indented file will be renamed to `SourceFile1.cpp.orig` .

> With the second option, the file is saved with a different name. Therefore a copy is not created.

> `Wildcards` (such as "*.cpp"), can be used if the project is compiled to include them. See the above Installation Information for instructions.

> ## 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:

> - Long options:
>   These options start with '`--`', and must be written one at a time.
>   (Example: '`--brackets=attach --pad --indent=spaces=4`)
> - 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 favorite source style.

> - The command line options have precedence. If there is a conflict between a command line option and an option in the default options file, the command line option will be used.
> - 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 (e.g. "$HOME/.astylerc" on Linux);
>   4. the file named astylerc in the directory pointed to by the USERPROFILE environment variable (e.g. "%USERPROFILE%\astylerc" on Windows).
> - 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 Style Options

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

> > >     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=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=java`
> > Java style formatting/indenting.

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

> ### Tab and Bracket Options

> > `default indent option`
> > If no indentation option is set, the default option of 4 spaces will be used (e.g. `-s4 --indent=spaces=4`).

> > `--indent=spaces=# / -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#`
> > Indent using tab characters. 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.

> > `--force-indent=tab=# / -T#`
> > Indent using tab characters. Treat each tab as `#` spaces (e.g. `-T6` / `--force-indent=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.

> > `default brackets option`
> > If no brackets option is set, the brackets will not be changed.

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

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

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

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

> > `--brackets=linux / -l`
> > 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();
> > >     }

> ### Indentation Options

> > `--indent-classes / -C`
> > 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();
> > >     };

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

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

> > >     case 2:
> > >     {
> > >         a += 2;
> > >         break;
> > >     }
> > >     }

> > > becomes:

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

> > >         case 2:
> > >         {
> > >             a += 2;
> > >             break;
> > >         }
> > >     }

> > `--indent-cases / -K`
> > Indent '`case X:`' blocks from the '`case X:`' headers. Case statements not enclosed in blocks are NOT indented.

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

> > >         case 2:
> > >         {
> > >             a += 2;
> > >             break;
> > >         }
> > >     }

> > > becomes:

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

> > >         case 2:
> > >             {
> > >                 a += 2;
> > >                 break;
> > >             }
> > >     }

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

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

> > > becomes:

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

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

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

> > > becomes:

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

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

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

> > > becomes:

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

> > `--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).

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

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

> > > becomes:

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

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

> > `--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.

> > `--max-instatement-indent=# / -M#`
> > Indent a maximum of `#` spaces in a continuous statement, relative to the previous line (e.g. `--max-instatement-indent=40`). # must be less than 80. If no `#` is set, the default value of 40 will be used.

> > >     fooArray[] = { red,
> > >              green,
> > >              darkblue };

> > >     fooFunction(barArg1,
> > >              barArg2,
> > >              barArg3);

> > > becomes (with larger value):

> > >     fooArray[] = { red,
> > >                    green,
> > >                    darkblue };

> > >     fooFunction(barArg1,
> > >                 barArg2,
> > >                 barArg3);

> > `--min-conditional-indent=# / -m#`
> > 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`). # must be less than 40. If no `#` is set, the default value of 8 will be used.

> > >     // 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 clearer
> > >     if (a < b
> > >         || c > d)
> > >     {
> > >         foo++;
> > >     }

> ### Formatting Options

> > `--break-blocks`
> > Pad empty lines around header blocks (e.g. '`if`', '`while`'...). Be sure to read the Supplemental Documentation before using this option.

> > >     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. Be sure to read the Supplemental Documentation before using this option.

> > >     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 separate lines.

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

> > > becomes:

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

> > `--pad=oper / -p`
> > Insert space padding around operators. Operators inside block parens [] are not padded. Note that there is no option to unpad. Once padded, they stay padded.

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

> > > becomes:

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

> > `--pad=paren / -P`
> > Insert space padding around parenthesis on both the outside and the inside.

> > >     if (isFoo(a, b))
> > >         bar(a, b);

> > > becomes:

> > >     if ( isFoo ( a, b ) )
> > >         bar ( a, b );

> > `--pad=paren-out / -d`
> > Insert space padding around parenthesis on the outside only. This can be used with `unpad=paren` below to remove unwanted spaces.

> > >     if (isFoo(a, b))
> > >         bar(a, b);

> > > becomes:

> > >     if (isFoo (a, b) )
> > >         bar (a, b);

> > `--pad=paren-in / -D`
> > Insert space padding around parenthesis on the inside only. This can be used with `unpad=paren` below to remove unwanted spaces.

> > >     if (isFoo(a, b))
> > >         bar(a, b);

> > > becomes:

> > >     if ( isFoo( a, b ) )
> > >         bar( a, b );

> > `--unpad=paren / -U`
> > Remove space padding around parenthesis on the inside and outside. 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.

> > >     if ( isFoo( a, b ) )
> > >         bar( a, b );

> > > becomes (with no padding requested):

> > >     if (isFoo(a, b))
> > >         bar(a, b);

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

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

> > > remains as is.

> > >     if (isFoo) DoBar();

> > > remains as is.

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

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

> > > remains as is.

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

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

> > `--mode=c / -c`
> > Indent a C or C++ file. The option is set from the file extension for each file. You can override the setting with this entry. It allows the formatter to identify language specific syntax such as C classes and C templates.

> > `--mode=java / -j`
> > Indent a Java file. The option is set from the file extension for each file. You can override the setting with this entry. It allows the formatter to identify language specific syntax such as Java classes.

> ### Other Options

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

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

> > `--options=none`
> > Disable the default options file. Only the command-line parameters will be used.

> > `--errors-to-standard-output / -X`
> > 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.

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

> > `--help / -h / -?`
> > 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 SourceForge for giving Artistic Style its home;
> - Thanks to all the dedicated beta-testers and bug notifiers!

> ## ENJOY !!!