Man Linux: Main Page and Category List

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, --style=allman, --style=bsd, -A1
              ANSI style formatting/indenting. Uses broken brackets.

       --style=java, -A2
              Java style formatting/indenting. Uses attached brackets.

       --style=k&r, --style=k/r, -A3
              Kernighan  &  Ritchie  style  formatting/indenting.  Uses  linux
              brackets.   Brackets  are  broken  from namespaces, classes, and
              function  definitions.   Brackets  are  attached  to  statements
              within a function.

       --style=stroustrup, -A4
              Stroustrup style formatting/indenting. Uses stroustrup brackets.
              Brackets are broken from function definitions only. Brackets are
              attached   to  namespaces,  classes,  and  statements  within  a
              function.

       --style=whitesmith, -A5
              Whitesmith style  formatting/indenting.  Uses  broken,  indented
              brackets. Class blocks and switch blocks are indented to prevent
              a  ’hanging  indent’  with  switch  statements  and  C++   class
              modifiers (public, private, protected).

       --style=banner, -A6
              Banner   style  formatting/indenting.  Uses  attached,  indented
              brackets. Class blocks and switch blocks are indented to prevent
              a   ’hanging  indent’  with  switch  statements  and  C++  class
              modifiers (public, private, protected).

       --style=gnu, -A7
              GNU  style  formatting/indenting.  Uses  brocken  brackets   and
              indented  blocks.  Indentation is 2 spaces. Extra indentation is
              added to blocks within  a  function.  The  opening  bracket  for
              namespaces, classes, and functions is not indented.

       --style=linux, -A8
              Linux  style  formatting/indenting.  Uses  linux style brackets.
              Brackets  are  broken  from  namespace,  class,   and   function
              definitions.  Brackets  are  attached  to  statements  within  a
              function. Indentation is 8 spaces.  Also known as Kernel  Normal
              Form (KNF) style, this is the style used in the Linux kernel.

       --style=horstmann, -A9
              Horstmann   style   formatting/indenting  uses  horstmann  style
              brackets.  Brackets are broken with run-in statements.  Switches
              are indented.  Indentation is 3 spaces.

       --style=1tbs, --style=otbs, -A10
              "One  True  Brace  Style"  formatting/indenting uses linux style
              brackets and adds brackets to unbracketed one  line  conditional
              statements.  The option --add-one-line-brackets can also be used
              with this style.

   Tab and Bracket Options:
       If no indentation option is set, the default option of 4 spaces will be
       used.  Equivalent  to  -s4 --indent=spaces=4.  If no brackets option is
       set, the brackets will not be changed.

       --indent=spaces, --indent=spaces=#, -s, -s#
              Indent using  #  spaces  per  indent.  Between  1  to  20.   Not
              specifying # will result in a default of 4 spaces per indent.

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

       --indent=force-tab, --indent=force-tab=#, -T, -T#
              Indent  using tab characters, assuming that each tab is # spaces
              long.  Between 1 and 20. Force tabs to be used in  areas  astyle
              would   usually   prefer   to   use  spaces  (as  in  multi-line
              statements).  Not  specifying  #  will  result  in   a   default
              assumption of 4 spaces per tab.

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

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

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

       --brackets=horstmann, -g
              Break  brackets from their pre-block statements but allow run-in
              statements  on  the  same  line  as  an  opening  bracket  (e.g.
              Horstmann style).

       --brackets=stroustrup, -u
              Break  brackets  from function definitions only. Attach brackets
              to namespaces, classes, and statements within a function.

              With C++ files brackets are attached  for  function  definitions
              within  a  class (inline class functions). The brackets are also
              attached for arrays, structs, enums, and other top level objects
              that  are  not classes or functions. This does not apply to Java
              and C#.

   Indentation Options:
       --indent-classes, -C
              Indent ’class’ blocks, so that the inner ’public:’, ’protected:’
              and  ’private:’  headers  are  indented in relation to the class
              block.  This option has no effect on Java and C# files.

       --indent-switches, -S
              Indent ’switch’ blocks, so that the inner ’case X:’ headers  are
              indented in relation to the switch block.  The entire case block
              is indented.

       --indent-cases, -K
              Indent ’case X:’ lines,  so  that  they  are  flush  with  their
              bodies. Case statements not enclosed in blocks are NOT indented.

       --indent-brackets, -B
              Add extra indentation to ’{’ and ’}’ block brackets. This is the
              option     used     for     Whitesmith    and    Banner    style
              formatting/indenting.    If    both    --indent-brackets     and
              --indent-blocks are used the result will be --indent-blocks.

       --indent-blocks, -G
              Add  extra  indentation to blocks within a function. The opening
              bracket for namespaces, classes, and functions is not  indented.
              This is the option used for GNU style formatting/indenting.

       --indent-namespaces, -N
              Add  extra  indentation  to namespace blocks. This option has no
              effect on Java files.

       --indent-labels, -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-preprocessor, -w
              Indent  multi-line  preprocessor  definitions  ending   with   a
              backslash.   Should  be  used  with  --convert-tabs  for  proper
              results. Does a pretty good job, but can not perform miracles in
              obfuscated preprocessor definitions.

       --indent-col1-comments, -Y
              Indent  C++  comments  beginning  in  column one. By default C++
              comments beginning in column one are not indented.  This  option
              will allow the comments to be indented with the code.

       --max-instatement-indent=#, -M#
              Indent a maximum of # spaces in a continuous statement, relative
              to the previous line. Must be less than 80.  The  default  value
              is 40.

       --min-conditional-indent=#, -m#
              Indent  a minimal # spaces in a continuous conditional belonging
              to a conditional header.  Must be less  than  40.   The  default
              value is twice the current indent.

   Formatting options:
       --break-blocks, -f
              Insert empty lines around header blocks (e.g. ’if’, ’while’...).

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

       --break-closing-brackets, -y, --brackets=break-closing (deprecated)
              Break  brackets  before  closing  headers (e.g. ’else’, ’catch’,
              ..).  Should be appended to --brackets=attach,  --brackets=linux
              or  --brackets=stroustrup.  Closing  header  brackets are always
              broken with  broken  brackets,  indented  blocks,  and  indented
              brackets.

       --break-elseifs, -e
              Break  "else  if"  header combinations into separate lines. This
              option has no effect if --keep-one-line-statements is used,  the
              "else if" statements will remain as they are.

              If  this  option is NOT used, "else if" header combinations will
              be placed on a single line.

       --add-brackets, -j
              Add brackets to  unbracketed  one  line  conditional  statements
              (e.g.  ’if’,  ’for’,  ’while’...).  The  statement  must be on a
              single line.  The  brackets  will  be  added  according  to  the
              currently  requested  predefined  style  or  bracket type. If no
              style  or  bracket  type  is  requested  the  brackets  will  be
              attached.  If  --add-one-line-brackets  is  also used the result
              will be one line brackets.

       --add-one-line-brackets, -J
              Add one  line  brackets  to  unbracketed  one  line  conditional
              statements (e.g. ’if’, ’for’, ’while’...). The statement must be
              on a single line.  The option implies --keep-one-line-blocks and
              will not break the one line blocks.

       --delete-empty-lines, -x
              Delete  empty  lines  within  a  function or method. Empty lines
              outside of functions or methods are NOT deleted.  If  used  with
              --break-blocks  or  --break-blocks=all  it will delete all lines
              except the lines added by the --break-blocks options.

       --pad-paren, -p, --pad=paren (deprecated)
              Insert space padding around parenthesis on both the outside  and
              the inside. Any end of line comments will remain in the original
              column, if possible.

       --pad-paren-out, -d, --pad=paren-out (deprecated)
              Insert space padding around parenthesis on the outside only. Any
              end  of  line  comments  will  remain in the original column, if
              possible. This can be used with --unpad-paren  below  to  remove
              unwanted spaces.

       --pad-paren-in, -D, --pad=paren-in (deprecated)
              Insert  space padding around parenthesis on the inside only. Any
              end of line comments will remain  in  the  original  column,  if
              possible.  This  can  be used with --unpad-paren below to remove
              unwanted spaces.

       --pad-header, -H
              Insert space padding after paren headers only (e.g. ’if’, ’for’,
              ’while’...).  Any  end  of  line  comments  will  remain  in the
              original column, if possible. This can  be  used  with  --unpad-
              paren to remove unwanted spaces.

       --unpad-paren, -U, --unpad=paren (deprecated)
              Remove  extra space padding around parenthesis on the inside and
              outside.  Any end of line comments will remain in  the  original
              column,  if  possible.   This  option 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.

              For example, if a source has parens padded on  both  the  inside
              and  outside,  and  you  want  inside  only.  You  need  to  use
              --unpad-paren to remove the outside padding, and  --pad-paren-in
              to  retain  the inside padding.  Using only --pad-paren-in would
              not remove the outside padding.

       --keep-one-line-statements, -o, --one-line=keep-statements (deprecated)
              Don’t break complex statements and multiple statements  residing
              on a single line.

       --keep-one-line-blocks, -O, --one-line=keep-blocks (deprecated)
              Don’t break blocks residing completely on one line

       --convert-tabs, -c
              Convert  tabs to spaces in the non-indentation part of the line.
              The number of spaces inserted will maintain the spacing  of  the
              tab.  The current setting for spaces per tab is used. It may not
              produce the expected results  if  --convert-tabs  is  used  when
              changing spaces per tab. Tabs are not replaced in quotes.

       --align-pointer=type, -k1

       --align-pointer=middle, -k2

       --align-pointer=name, -k3
              Attach  a  pointer  or reference operator (* or &) to either the
              variable type (left) or  variable  name  (right),  or  place  it
              between the type and name. The spacing between the type and name
              will be preserved, if possible. This  option  is  effective  for
              C/C++ files only.

       --fill-empty-lines, -E
              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:

       --mode=c
              Indent a C or C++ source file (default).

       --mode=java
              Indent a Java(TM) source file.

       --mode=cs
              Indent a C sharp source file.

   Other options:
       --suffix=####
              Append the suffix #### instead of ’.orig’ to original  filename.

       --suffix=none, -n
              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.

       --recursive, -r, -R
              For   each   directory   in   the   command  line,  process  all
              subdirectories recursively. When using the recursive option  the
              file  name statement should contain a wildcard. The filepath and
              name should be placed in double quotes so  the  shell  will  not
              resolve the wildcards (e.g.  "$HOME/src/*.cpp").

       --exclude=####
              Specify  a  file  or  sub  directory  ####  to  be excluded from
              processing.

              Excludes are matched from the end of the  filepath.  An  exclude
              option   of  "templates"  will  exclude  ALL  directories  named
              "templates". An exclude option of "cpp/templates"  will  exclude
              ALL  "cpp/templates"  directories.  You may proceed backwards in
              the directory tree to exclude only the required directories.

              Specific files may be excluded in the same  manner.  An  exclude
              option   of   "default.cpp"   will   exclude   ALL  files  named
              "default.cpp". An exclude option  of  "python/default.cpp"  will
              exclude  ALL  files  named "default.cpp" contained in a "python"
              subdirectory.  You may proceed backwards in the  directory  tree
              to exclude only the required files.

              Wildcards  are  NOT allowed.  There may be more than one exclude
              statement.  The filepath and name may be placed in double quotes
              (e.g.  --exclude="foo bar.cpp").

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

       --preserve-date, -Z
              Preserve the original file’s date and time  modified.  The  date
              and  time  modified  will  not be changed in the formatted file.
              This option is not effective if redirection is used.

       --verbose, -v
              Verbose display mode.  Display  optional  information,  such  as
              release number and statistical data.

       --formatted, -Q
              Formatted  files display  mode. Display only the files that have
              been formatted. Do not display files that are unchanged.

       --quiet,-q
              Quiet display mode. Suppress all output except error messages.

       --lineend=windows, -z1

       --lineend=linux, -z2

       --lineend=macold, -z3
              Force use of the specified line end  style.  Valid  options  are
              windows (CRLF), linux (LF), and macold (CR). MacOld style is the
              format for OS 9 and earlier. Mac OS X uses the Linux style.   If
              one  of  these  options  is  not  used  the  line  ends  will be
              determined automatically from the input file.

       -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  file indicated by the --options= command
              line option; 2.   The  contents  of  the  ARTISTIC_STYLE_OPTIONS
              environment variable if it exists.

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

       4.     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.  This option file lookup can be
       disabled by specifying --options=none on the command line.

       Long  options within the default option file may be written without the
       preliminary ’--’, but short options require the  preceding  ’-’.  Lines
       within  the  options  file  that  begin  with  ’#’ are considered line-
       comments.

VERSION

       1.23

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
       August 2009 by Margarita Manterola <marga@debian.org>