Linux Certif

Toute la documentation sur la certification Linux LPI

astyle

NAME

astyle - indentation and reformatting filters for C, C++, C#, Java

SYNOPSIS

astyle [OPTIONS] < Original > Beautified

astyle [OPTIONS] [FILE1] [FILE2] [...]

DESCRIPTION

Artistic Style (or astyle) is a reindenter and reformatter 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 astyle 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.

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

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

A summary of the options supported by astyle is included below.

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.

--style=ansi ANSI style formatting/indenting.

--style=kr

Kernighan&Ritchie style formatting/indenting.

--style=gnu

GNU style formatting/indenting.

--style=java

Java mode, with standard java style formatting/indenting.

--style=linux

Linux mode (i.e. 8 spaces per indent, break definition-block brackets but attach command-block brackets).

Tab and Bracket Options:

-s, -s#, --indent=spaces=#

Indent using # spaces per indent. Between 2 to 20. Not specifying # will result in a default of 4 spaces per indent.

-t, -t#, --indent=tab=#

Indent using tab characters, assuming that each tab is # spaces long. Between 2 and 20. Not specifying # will result in a default assumption of 4 spaces per tab.

-T#, --indent-tab=#

Indent using tab characters, assuming that each tab is # spaces long. Between 2 and 20. Force tabs to be used in areas astyle would usually prefer to use spaces (as in multi-line statements).

-b, --brackets=break

Break brackets from pre-block code (i.e. ANSI C/C++ style).

-a, --brackets=attach

Attach brackets to pre-block code (i.e. Java/K&R style).

-l, --brackets=linux

Break brackets from class and function declarations, but attach brackets to pre-block command statements.

-y, --brackets=break-closing

Break brackets before closing headers (e.g. 'else', 'catch', ..). Should be appended to --brackets=attach or --brackets=linux.

Indentation Options:

-C, --indent-classes

Indent 'class' blocks, so that the inner 'public:', 'protected:' and 'private:' headers are indented in relation to the class block.

-S, --indent-switches

Indent 'switch' blocks, so that the inner 'case XXX:' headers are indented in relation to the switch block. The entire case block is indented.

-K, --indent-cases

Indent 'case XXX:' lines, so that they are flush with their bodies. Case statements not enclosed in blocks are NOT indented.

-N, --indent-namespaces

Indent the contents of namespace blocks.

-B, --indent-brackets

Add extra indentation to '{' and '}' block brackets. This option has no effect if --indent-blocks is used.

-G, --indent-blocks

Add extra indentation entire blocks (including brackets).

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

-w, --indent-preprocessor

Indent multi-line preprocessor definitions. Should be used with --convert-tabs for proper results.

-m#, --min-conditional-indent=#FR

Indent a minimal # spaces in a continuous conditional belonging to a conditional header. Must be less than 40. The default value is 8.

-M#, --max-instatement-indent=#

Indent a maximal # spaces in a continuous statement, relatively to the previous line. Must be less than 80. The default value is 40.

Formatting options:

-f, --break-blocks

Insert empty lines around unrelated blocks, labels, classes, ...

-F, --break-blocks=all

Like --break-blocks, except also insert empty lines around closing headers (e.g. 'else', 'catch', ...).

-e, --break-elseifs

Break 'else if()' statements into two different lines.

-p, --pad=oper

Insert space paddings around operators only. Operators inside block parens [] are not padded.

-P, --pad=paren

Insert space paddings around parenthesies on both the outside and the inside.

-d, --pad=paren-out

Insert space paddings around parenthesies on the outside only. This can be used with unpad=paren to remove unwanted spaces.

-D, --pad=paren-in

Insert space paddings around parenthesies on the inside only. This can be used with unpad=paren to remove unwanted spaces.

-U, --unpad=paren

Remove space padding around parenthesis on the inside and outside. Can be used in combination with the paren padding options. Only padding that has not been requested by other options will be removed.

-o, --one-line=keep-statements

Don't break lines containing multiple statements into multiple single-statement lines.

-O, --one-line=keep-blocks

Don't break blocks residing completely on one line

-v, --convert-tabs

Convert tabs to spaces.

-E, --fill-empty-lines

Fill empty lines with the white space of their previous lines.

Indentation modes:

The modes used for indentation are set by each file's extension, but it can be overriden with the following options: -c,--mode=c Indent a C or C++ source file (default)

-j,--mode=java

Indent a Java(TM) source file

Other options:

--suffix=####

Append the suffix #### instead of '.orig' to original filename.

-n, --suffix=none

Do not retain a backup of the original file. The original file is purged after it is formatted.

--options=####

Specify an options file #### to read and use.

--options=none

Disable the default options file. Only the command-line parameters will be used.

-X, --errors-to-standard-output

Print errors and help information to standard-output rather than to standard-error.

-V, --version

Print version number

-h, -?, --help

Show summary of Options

FILES

Artistic Style looks for a default options file in the following order:

1.

The contents of the ARTISTIC_STYLE_OPTIONS environment variable if it exists.

2.

The file called .astylerc in the directory pointed to by the HOME environment variable ( i.e. $HOME/.astylerc).

3.

The file called .astylerc in the directory pointed to by the HOMEPATH environment variable ( i.e. %HOMEPATH%.astylerc).

If a default options file is found, the options in this file will be parsed BEFORE the command-line options. Options within the default option file may be written without the preliminary '-' or '--'.

VERSION

1.20.2

SEE ALSO

indent(1)

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

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

Minor modifications by Luca Filipozzi <lfilipoz@debian.org>. Updated on March 2007 by Margarita Manterola <marga@debian.org>