NAME¶

astyle - C syntax indenter and formatter

SYNOPSIS¶

astyle [OPTIONS] [input files]

DESCRIPTION¶

astyle provides a variety of options to apply a consistent coding style to C, C++, Java or Objective-C source code files.

When indenting a specific file, the resulting indented file RETAINS the original file-name. The original pre-indented file is renamed, with a suffix of '.orig' added to the original filename.

Wildcards (* and ?) may be used in the filename. A 'recursive' option can process directories recursively. Multiple file extensions may be separated by a comma.

By default, astyle is set up to indent with four spaces per indent, a maximal indentation of 40 spaces inside continuous statements, a minimum indentation of eight spaces inside conditional statements, and NO formatting options.

Brace Style Options¶

If no brace style is requested, the opening braces will not be changed and closing braces will be broken from the preceding line.

--style=allman OR --style=bsd OR --style=break OR -A1

Allman style formatting/indenting. Broken braces.

--style=java OR --style=attach OR -A2

Java style formatting/indenting. Attached braces.

--style=kr OR --style=k&r OR --style=k/r OR -A3

Kernighan & Ritchie style formatting/indenting. Linux braces.

--style=stroustrup OR -A4

Stroustrup style formatting/indenting. Linux braces, with broken closing headers.

--style=whitesmith OR -A5

Whitesmith style formatting/indenting. Broken, indented braces. Indented class blocks and switch blocks.

--style=vtk OR -A15

VTK style formatting/indenting. Broken, indented braces except for the opening braces.

--style=ratliff OR --style=banner OR -A6

Ratliff style formatting/indenting. Attached, indented braces.

--style=gnu OR -A7

GNU style formatting/indenting. Broken braces, indented blocks.

--style=linux OR --style=knf OR -A8

Linux style formatting/indenting. Linux braces, minimum conditional indent is one-half indent.

--style=horstmann OR --style=run-in OR -A9

Horstmann style formatting/indenting. Run-in braces, indented switches.

--style=1tbs OR --style=otbs OR -A10

One True Brace Style formatting/indenting. Linux braces, add braces to all conditionals.

--style=google OR -A14

Google style formatting/indenting. Attached braces, indented class modifiers.

--style=mozilla OR -A16

Mozilla style formatting/indenting. Linux braces, with broken braces for structs and enums, and attached braces for namespaces.

--style=webkit OR -A17

WebKit style formatting/indenting. Linux braces, with attached closing headers.

--style=pico OR -A11

Pico style formatting/indenting. Run-in opening braces and attached closing braces. Uses keep one line blocks and keep one line statements.

--style=lisp OR -A12

Lisp style formatting/indenting. Attached opening braces and attached closing braces. Uses keep one line statements.

Tab Options:¶

If no indentation option is set, the default option of 4 spaces per indent will be used.

--indent=spaces=# OR -s#

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

--indent=tab OR --indent=tab=# OR -t OR -t#

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

--indent=force-tab=# OR -T#

Indent using tab characters, assuming that each indent is # spaces long. Force tabs to be used in areas AStyle would prefer to use spaces.

--indent=force-tab-x=# OR -xT#

Allows the tab length to be set to a length that is different from the indent length. This may cause the indentation to be a mix of both spaces and tabs. This option sets the tab length.

Brace Modify Options:¶

--attach-namespaces OR -xn

Attach braces to a namespace statement.

--attach-classes OR -xc

Attach braces to a class statement.

--attach-inlines OR -xl

Attach braces to class inline function definitions.

--attach-extern-c OR -xk

Attach braces to an extern "C" statement.

--attach-closing-while OR -xV

Attach closing while of do-while to the closing brace.

Indentation Options:¶

--indent-classes OR -C

Indent 'class' blocks so that the entire block is indented.

--indent-modifiers OR -xG

Indent 'class' access modifiers, 'public:', 'protected:' or indented.

--indent-switches OR -S

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

--indent-cases OR -K

Indent case blocks from the 'case XXX:' headers. Case statements not enclosed in blocks are NOT indented.

--indent-namespaces OR -N

Indent the contents of namespace blocks.

--indent-after-parens OR -xU

Indent, instead of align, continuation lines following lines that contain an opening paren '(' or an assignment '='.

--indent-continuation=# OR -xt#

Indent continuation lines an additional # indents. The valid values are 0 thru 4 indents. The default value is 1 indent.

--indent-labels OR -L

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

--indent-preproc-block OR -xW

Indent preprocessor blocks at brace level 0. Without this option the preprocessor block is not indented.

--indent-preproc-cond OR -xw

Indent preprocessor conditional statements #if/#else/#endif to the same level as the source code.

--indent-preproc-define OR -w

Indent multi-line preprocessor #define statements.

--indent-col1-comments OR -Y

Indent line comments that start in column one.

--min-conditional-indent=# OR -m#

Indent a minimal # spaces in a continuous conditional belonging to a conditional header. The valid values are: 0 - no minimal indent. 1 - indent at least one additional indent. 2 - indent at least two additional indents. 3 - indent at least one-half an additional indent. The default value is 2, two additional indents.

--max-continuation-indent=# OR -M#

Indent a maximal # spaces in a continuation line, relative to the previous line. The minimum and default value is 40.

Padding Options¶

--break-blocks OR -f

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

--break-blocks=all OR -F

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

--pad-oper OR -p

Insert space padding around operators.

--pad-comma OR -xg

Insert space padding after commas.

--pad-paren OR -P

Insert space padding around parenthesis on both the outside and the inside.

--pad-paren-out OR -d

Insert space padding around parenthesis on the outside only.

--pad-first-paren-out OR -xd

Insert space padding around first parenthesis in a series on the outside only.

--pad-paren-in OR -D

Insert space padding around parenthesis on the inside only.

--pad-header OR -H

Insert space padding after paren headers (e.g. 'if', 'for'...).

--unpad-paren OR -U

Remove unnecessary space padding around parenthesis. This can be used in combination with the 'pad' options above.

--pad-empty-paren OR -xo

Apply padding to empty pairs of parentheses; combine with other parenthesis padding options.

--pad-brackets

Insert space padding around square brackets on both the outside and the inside.

--pad-brackets-in

Insert space padding around square brackets the inside only.

--pad-brackets-out

Insert space padding around square brackets the outside only.

--unpad-brackets

Remove unnecessary space padding around square brackets.

--delete-empty-lines OR -xe

Delete empty lines within a function or method. It will NOT delete lines added by the break-blocks options.

--fill-empty-lines OR -E

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

--align-pointer=type OR -k1

--align-pointer=middle OR -k2

--align-pointer=name OR -k3

Attach a pointer or reference operator (*, &, or ^) to either the operator type (left), middle, or operator name (right). To align the reference separately use --align-reference.

--align-reference=none OR -W0

--align-reference=type OR -W1

--align-reference=middle OR -W2

--align-reference=name OR -W3

Attach a reference operator (&) to either the operator type (left), middle, or operator name (right). If not set, follow pointer alignment.

--squeeze-lines=#

Remove superfluous empty lines exceeding the given number.

--squeeze-ws

Remove superfluous whitespace.

Formatting Options¶

--break-closing-braces OR -y

Break braces before closing headers (e.g. 'else', 'catch', ...). Use with --style=java, --style=kr, --style=stroustrup, --style=linux, or --style=1tbs."

--break-elseifs OR -e

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

--break-one-line-headers OR -xb

Break one line headers (e.g. 'if', 'while', 'else', ...) from a statement residing on the same line.

--add-braces OR -j

--add-braces=nested (experimental)

Add braces to unbraced one line conditional statements.

--add-one-line-braces OR -J

Add one line braces to unbraced one line conditional statements.

--remove-braces OR -xj

Remove braces from a braced one line conditional statements.

--break-return-type OR -xB

--break-return-type-decl OR -xD

Break the return type from the function name. Options are for the function definitions and the function declarations.

--attach-return-type OR -xf

--attach-return-type-decl OR -xh

Attach the return type to the function name. Options are for the function definitions and the function declarations.

--keep-one-line-blocks OR -O

Don't break blocks residing completely on one line.

--keep-one-line-statements OR -o

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

--convert-tabs OR -c

Convert tabs to the appropriate number of spaces.

--close-templates OR -xy

Close ending angle brackets on template definitions.

--remove-comment-prefix OR -xp

Remove the leading '*' prefix on multi-line comments and indent the comment text one indent.

--max-code-length=# OR -xC#

--break-after-logical OR -xL

max-code-length=# will break the line if it exceeds more than # characters. The valid values are 50 thru 200. If the line contains logical conditionals they will be placed first on the new line. The option break-after-logical will cause the logical conditional to be placed last on the previous line.

--mode=c

Indent a C or C++ source file (this is the default).

--mode=java

Indent a Java source file.

--mode=cs

Indent a C# source file.

--mode=objc

Indent an Objective-C source file.

--mode=js

Indent a JavaScript source file (experimental).

--mode=ghc

Indent a GHC source file (experimental).

Objective-C Options¶

--pad-method-prefix OR -xQ

Insert space padding after the '-' or '+' Objective-C method prefix.

--unpad-method-prefix OR -xR

Remove all space padding after the '-' or '+' Objective-C method prefix.

--pad-return-type OR -xq

Insert space padding after the Objective-C return type.

--unpad-return-type OR -xr

Remove all space padding after the Objective-C return type.

--pad-param-type OR -xS

Insert space padding after the Objective-C param type.

--unpad-param-type OR -xs

Remove all space padding after the Objective-C param type.

--align-method-colon OR -xM

Align the colons in an Objective-C method definition.

--pad-method-colon=none OR -xP

--pad-method-colon=all OR -xP1

--pad-method-colon=after OR -xP2

--pad-method-colon=before OR -xP3

Add or remove space padding before or after the colons in an Objective-C method call.

Other Options¶

--suffix=####

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

--suffix=none OR -n

Do not retain a backup of the original file.

--recursive OR -r OR -R

Process subdirectories recursively.

--dry-run

Perform a trial run with no changes made to check for formatting.

--exclude=####

Specify a file or directory #### to be excluded from processing.

--ignore-exclude-errors OR -i

Allow processing to continue if there are errors in the exclude=#### options. It will display the unmatched excludes.

--ignore-exclude-errors-x OR -xi

Allow processing to continue if there are errors in the exclude=#### options. It will NOT display the unmatched excludes.

--errors-to-stdout OR -X

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

--preserve-date OR -Z

Preserve the original file's date and time modified. The time modified will be changed a few micro seconds to force a compile.

--verbose OR -v

Verbose mode. Extra informational messages will be displayed.

--formatted OR -Q

Formatted display mode. Display only the files that have been formatted.

--quiet OR -q

Quiet mode. Suppress all output except error messages.

--lineend=windows OR -z1

--lineend=linux OR -z2

--lineend=macold OR -z3

Force use of the specified line end style. Valid options are windows (CRLF), linux (LF), and macold (CR).

Command Line Only¶

--options=####

--options=none

Specify a default option file #### to read and use. It must contain a file path and a file name.

--project

--project=####

--project=none

Specify a project option file #### to read and use. It must contain a file name only, without a directory path. The file should be included in the project top-level directory. The default file name is .astylerc or _astylerc.

--ascii OR -I

The displayed output will be ascii characters only.

--version OR -V

Print version number.

--help OR -h OR -?

Print this help message.

--html OR -!

Open the HTML help file "astyle.html" in the default browser. The documentation must be installed in the standard install path.

--html=####

Open a HTML help file in the default browser using the file path ####. The path may include a directory path and a file name, or a file name only. Paths containing spaces must be enclosed in quotes.

--stdin=####

Use the file path #### as input to single file formatting. This is a replacement for redirection.

--stdout=####

Use the file path #### as output from single file formatting. This is a replacement for redirection.

Option Files¶

Artistic Style looks for a default option file and/or a project option file in the following order:

1. The command line options have precedence.

2. The project option file has precedence over the default file
o the file name indicated by the --project= command line option.
o the file named .astylerc or _ astylerc.
o the file name identified by ARTISTIC_STYLE_PROJECT_OPTIONS.
o the file is disabled by --project=none on the command line.

3. The default option file that can be used for all projects.
o the file path indicated by the --options= command line option.
o the file path indicated by ARTISTIC_STYLE_OPTIONS.
o the file named .astylerc in the HOME directory (for Linux).
o the file name astylerc in the APPDATA directory (for Windows).
o the file is disabled by --project=none on the command line.

Long options within the option files may be written without '--'.

Line-end comments begin with a '#'.

Disable Formatting¶

Blocks of code can be disabled with the comment tags *INDENT-OFF* and *INDENT-ON*. It must be contained in a one-line comment.

Padding of operators can be disabled on a single line using the comment tag *NOPAD*. It must be contained in a line-end comment.

Examples¶

File conversions:

astyle --style=allman /home/project/foo.cpp

astyle --style=allman --recursive /home/project/*.cpp,*.h

astyle --style=allman < OriginalSourceFile > BeautifiedSourceFile

AUTHORS¶

Andre Simon <as@andre-simon.de>

SEE ALSO¶

More information at https://sourceforge.net/p/astyle/.