Indenting source code

by Tal Davidson, Israel (E-mail: davidsont@bigfoot.com)

Main home Page	http://sourceforge.net
Project Page	http://www.sourceforge.net/projects/astyle

Artistic Style is a reindenter and reformatter of 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 (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 I have created Artistic Style - a series of filters, written in C++, that automatically reindent & 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.

Read Release Notes

Read License

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

New versions, Comments, Questions, Bugs and Ideas for Improvement:

• Visit Astyle's project page at http://www.sourceforge.net/projects/astyle for:
  • Astyle sources and binaries
  • Mailing lists
  • Bug tracking facilities
• Author's e-mail: Reach me directly at davidsont@bigfoot.com

To use from the command line:

1) Unzip astyle.zip and compile 'astyle' (read README.txt for instructions).

2) Either place the resulting executable file's directory in your PATH system-variable, or move the executable to a directory that appears in your PATH system-variable.

3) Run it with the following syntax:

astyle [options] < OriginalSourceFile > BeautifiedSourceFile

OR

astyle [options] Foo.java Bar.javaAnotherBar.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. 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 bring to C/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
   (e.g. --brackets=attach --pad --indent=spaces=4 ).

2. Short Options:

   These options start with a single '-', and may be appended together.
   Thus, writing -bps4 is the same as writing -b -p -s4 .

A default options file may be used to define default options:

• Artistic Style looks for the default options file in the following order: 
  1. The value of the the system variable ARTISTIC_STYLE_OPTIONS if one exists.
  2. The file named .astylerc in the directory pointed to by the HOME system variable (i.e. $PATH/.astylerc)
  3. The file named .astylerc in the directory pointed to by the HOMEPATH system variable (i.e. %HOMEPATH%\.astylerc)

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

  # default parsing is of java files
  mode=java
  # brackets should be attached to pre-bracket lines
  brackets=attach
  # set 6 spaces per indent<tt><br>indent=spaces=6
  # indent switch blocks
  indent-switches
  # suffix of original files should be .pre
  suffix=.pre
  

The following predefined style options are currently avaiable:

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

The following indentation options are currently available:

-c OR --mode=c
Indent a C, C++ or C# file.

-j OR --mode=java
Indent a Java file.

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

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

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

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

The default:

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

becomes:

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

-S OR --indent-switches
Indent 'switch' blocks so that the 'case XXX:' headers are indented in the class block.

The default:

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

default:
    a += 2;
    break;
}

becomes:

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

default:
        a += 2;
        break;
}

-K OR --indent-cases
Indent 'case XXX:' lines so that they are flush with the comand lines under them.

The default:

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

default:
    {
        a += 2;
        break;
    }
}

becomes:

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

    default:
    {
        a += 2;
        break;
    }
}

-B OR --indent-brackets
Add extra indentation to brackets.

The default:

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

becomes:

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

-G OR --indent-blocks
Add extra indentation to entire blocks.

The default:

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

becomes:

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

-N OR --indent-namespaces
Add extra indentation to namespaces.

The default:

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

becomes:

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

-L OR --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).

The default:

int foospace()
{
    while (isFoo)
    {
        ...
        goto error;

error:
        ...
    }
}

becomes:

int foospace()
{
    while (isFoo)
    {
        ...
        goto error;

error:
        ...
    }
}

-M# OR --max-instatement-indent=# 
Indent a maximal # spaces in a continuous statement, relatively to the previous line (e.g. --max-instatement-indent=40)

-m# OR --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)

The default:

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

When setting --min-conditional=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 OR --fill-empty-lines
Fill empty lines with the white space of their previous lines.

The following formatting options are currently available:

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

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

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

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

-l OR --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 OR --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-- );

-POR --pad=all
Insert space padding around operators AND parenthesies.

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

becomes:

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

-o OR--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 OR--one-line=keep-blocks
Don't break one-line blocks.

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

remains as is.

The following other options are currently available:

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

-X OR --errors-to-standard-output
Print errors and help information 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 Windows-95.

-v OR --version
Print version number.

-h OR -? OR --help
Print a help message and quit.
 

Acknowledgements:

-Special thanks to: Jim Watson, Fred Shwartz, W. Nathaniel Mills III, Danny Deschenes, Andre Houde, Richard Bullington, Paul-Michael Agapow, Daryn Adler for their patches and contributions to Artistic Style !!!

-Special thanks to Richard Bullington andMicroState for giving Artistic Style its original mailing-list !!!

-Special thanks toSourceForge for giving Artistic Style itshome !!!

-Special 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 !!!

ENJOY !!!

reference:

URL:http://www.desy.de/~njwalker/astyle.html