Provided by: astyle_2.03-1_amd64 bug

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 source code indenter, formatter, and 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 (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

       Not  specifying  any  option  will  result  in  4  spaces per indent, no change in bracket
       placement, and no formatting changes.

       Options may be written in two different ways: long options start with  two  dashes  (`--')
       and  must  be  written  one at a time; short options start with a single dash ('-') may be
       concatenated together (thus, -bps4 is the same as -b -p -s4).

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

   Bracket Style Options:
       Bracket Style options define the bracket style to use. This option  always  overrides  any
       individual  option  settings.  You will always get the requested style regardless of other
       defined options.

       All other options are available to customize the bracket style. By default,  none  of  the
       styles  indent  namespaces.  All  options  default  to  4 spaces per indent, indented with
       spaces.

       default bracket style
              If no bracket style option is set, the opening brackets will  not  be  changed  and
              closing brackets will be broken from the preceding line.

       --style=allman, --style=ansi, --style=bsd, --style=break, -A1
              Allman style formatting/indenting uses broken brackets.

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

       --style=kr, --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.  This style frequently is used with an indent of 5
              spaces.

       --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 broken  brackets  and  indented  blocks.   This
              style frequently is used with an indent of 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.  Minimum conditional indent is one-half indent. If
              you want a different minimum conditional indent use the  K&R  style  instead.  This
              style  works  best  with  a large indent. It frequently is used with an indent of 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 run-in brackets, brackets are broken and
              allow run-in statements. Switches are indented to allow a  run-in  to  the  opening
              switch block. This style frequently is used with an indent of 3 spaces.

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

       --style=pico, -A11
              Pico  style  formatting/indenting uses run-in brackets, opening brackets are broken
              and allow run-in statements.  The closing bracket is attached to the last  line  in
              the  block.   Switches  are indented to allow a run-in to the opening switch block.
              The style  implies  --keep-one-line-blocks  and  --keep-one-line-statements.   This
              style  does  not support multiple-line brackets.  If add-brackets is used they will
              be added as one-line brackets.  This style frequently is used with an indent  of  2
              spaces.

       --style=1isp, --style=python, -A12
              Lisp  style  formatting/indenting  uses  attached  brackets,  opening  brackets are
              attached at the end of the statement.  The closing bracket is attached to the  last
              line   in   the  block.   The  style  implies  --keep-one-line-statements  but  NOT
              --keep-one-line-blocks.   This  style  does  not  support  one-line  brackets.   If
              --add-one-line-brackets is used they will be added as multiple-line brackets.

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

       --indent=spaces, --indent=spaces=#, -s, -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, -t#
              Indent using tabs for indentation, and spaces for continuation line alignment. This
              ensures that the code is displayed correctly  regardless of the viewer’s tab  size.
              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.

       --indent=force-tab, --indent=force-tab=#, -T, -T#
              Indent using all tab characters, if possible. If a continuation line is not an even
              number  of tabs, spaces will be added at the end.  Treat each tab as # spaces (e.g.
              -T6 / --indent=force-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.

       --indent=force-tab-x, --indent=force-tab-x=#, -xT, -xT#
              This force-tab option allows the tab length to be set to a length that is different
              than the indent length. This may cause the indentation to be a mix of both tabs and
              spaces. Tabs will be used to indent, if possible. If a tab indent cannot  be  used,
              spaces will be used instead.

              This  option  sets  the  tab  length.   Treat  each  tab  as  # spaces (e.g. -xT6 /
              --indent=force-tab-x=6).  # must be between 2 and 20. If no # is set,  treats  tabs
              as 8 spaces.  To change the indent length --indent=force-tab must also be used.

   Indentation Options:
       --indent-classes, -C
              Indent  'class'  and 'struct' blocks so that the blocks 'public:', ´protected:' and
              'private:' are indented. The struct blocks are indented only if an access  modifier
              is  declared somewhere in the struct.  The entire block is indented. This option is
              effective for C++ files only.

       --indent-switches, -S
              Indent 'switch' blocks so that the 'case X:' statements are indented in the  switch
              block. The entire case block is indented.

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

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

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

       --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 cannot  perform
              miracles   in   obfuscated  preprocessor  definitions.   Without  this  option  the
              preprocessor statements remain unchanged.

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

       --min-conditional-indent=#, -m#
              Set the minimal indent that is added when a header is built of multiple lines. This
              indent helps to easily separate the header from the command statements that follow.
              The value for # indicates a number of indents and is a minimum  value.  The  indent
              may be greater to align with the data on the previous line.

              The valid values are:
               0  -  no minimal indent. The lines will be aligned with the paren on the preceding
              line.
               1 - indent at least one additional indent.
               2 - indent at least two additional indents.
               3 - indent at least one-half an additional indent.  This  is  intended  for  large
              indents (e.g. 8).

              The default value is 2, two additional indents.

       --max-instatement-indent=#, -M#
              Set  the   maximum  of  #  spaces to indent a continuation line. The  # indicates a
              number of columns and must not be greater than 120.  If no # is  set,  the  default
              value  of  40  will  be  used.  A  maximum  of less than two indent lengths will be
              ignored. This option will prevent continuation lines from extending too far to  the
              right.  Setting  a  larger  value will allow the code to be extended further to the
              right.

   Padding Options:
       --break-blocks, -f
              Pad empty lines around header blocks (e.g. 'if', 'for', 'while'...).

       --break-blocks=all, -F
              Pad empty lines around header blocks (e.g. 'if', 'for', 'while'...).  Treat closing
              header blocks (e.g. 'else', 'catch') as stand-alone blocks.

       --pad-oper, -p
              Insert  space padding around operators. Any end of line comments will remain in the
              original column, if possible. Note that there is no option to unpad.  Once  padded,
              they stay padded.

       --pad-paren, -P
              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
              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-first-paren-out, -xd
              Insert space padding around the first parenthesis in a series 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.  If used with --pad-paren
              or  --pad-paren-out, this option will be ignored.  If used with --pad-paren-in, the
              result will be the same as pad-paren.

       --pad-paren-in, -D
              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
              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.

       --delete-empty-lines, -xe
              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.

       --fill-empty-lines, -E
              Fill empty lines with the white space of their previous lines.

       --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 (middle).
              The spacing between the type and name will be preserved, if possible.  This  option
              is  for  C/C++,  C++/CLI,  and  C#  files.  To format references separately use the
              following --align-reference option.

       --align-reference=none, -W0
       --align-reference=type, -W1
       --align-reference=middle, -W2
       --align-reference=name, -W3
              This option will align references separate from pointers. Pointers are not  changed
              by  this  option.  If  pointers  and references are to be aligned the same, use the
              previous --align-pointer option.  The option --align-reference=none will not change
              the  reference  alignment.  The  other options are the same as for --align-pointer.
              This option is for C/C++, C++/CLI, and C# files.

   Formatting Options:
       --break-closing-brackets, -y
              When used with --brackets=attach, --brackets=linux or  --brackets=stroustrup,  this
              breaks closing headers (e.g. ´else´, ´catch´, ...) from their immediately preceding
              closing brackets. Closing header brackets are always broken with  broken  brackets,
              horstmann 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.

       --keep-one-line-blocks, -O
              Don't break one-line blocks.

       --keep-one-line-statements, -o
              Don't break complex statements and multiple statements residing on a single 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.

       --close-templates, -xy
              Closes  whitespace  in  the  angle  brackets  of template definitions.  Closing the
              ending angle brackets is now allowed by the C++11 standard.  Be sure your  compiler
              supports this before making the changes.

       --max-code-length=#, -xC#
       --break-after-logical, -xL
              The  option --max\[u2011]code\[u2011]length will break a line if the code exceeds #
              characters. The valid values are 50 thru 200. Lines  without  logical  conditionals
              will  break  on  a  logical  conditional (||, &&, ...), comma, paren, semicolon, or
              space.

              Some code will not be broken, such as comments, quotes, and arrays.  If  used  with
              keep‑one‑line‑blocks  or  add-one-line-brackets  the  blocks will NOT be broken. If
              used with keep‑one‑line‑statements the statements will be broken at a semicolon  if
              the  line goes over the maximum length. If there is no available break point within
              the max code length, the line will be broken at the  first  available  break  point
              after the max code length.

              By  default  logical conditionals will be placed first on the new line.  The option
              break‑after‑logical will cause the logical conditionals to be placed  last  on  the
              previous line. This option has no effect without max‑code‑length.

       --mode=c
       --mode=cs
       --mode=java
              Indent a C/C++, C#, or Java file. The option is usually set from the file extension
              for each file. You can override the setting with this entry. It will  be  used  for
              all  files  regardless  of the file extension.  It allows the formatter to identify
              language specific syntax such as C++ classes, templates, and keywords.

   Other options:
       --suffix=####
              Append  the  suffix  ####  instead  of   '.orig'   to   original   filename   (e.g.
              --suffix=.bak).  If  this  is to be a file extension, the dot '.' must be included.
              Otherwise the suffix will be appended to the current file extension.

       --suffix=none, -n
              Do not retain a backup of the original file. The original file is purged  after  it
              is formatted.

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

       --ignore-exclude-errors, -i
              Allow processing to continue if there are  errors  in  the  --exclude=###  options.
              This  option  lets  the excludes for several projects be entered in a single option
              file. This option may be placed in the same option file as the  excludes.  It  will
              display the unmatched excludes. The following option will not display the unmatched
              excludes.

       --ignore-exclude-errors-x, -xi
              Allow processing to continue if there are  errors  in  the  --exclude=###  options.
              This  option  lets  the excludes for several projects be entered in a single option
              file. This option may be placed in the same option file as the  excludes.  It  will
              NOT display the unmatched excludes. The preceding option will display the unmatched
              excludes.

       --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 to rename the input file.  Please note that  the  date  is  not
              actually  preserved:  10  seconds are added to the original date (this behaviour is
              reported as Debian bug #686317).

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

   Command Line Only:
       These  options  are  available  for  the  command-line  only. They are NOT available in an
       options file.

       --options=####
              Specify an options file #### to read and use. It must contain a file path  for  the
              file. This will allow the file name to be changed from astylerc or .astylerc.

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

       --ascii, -I
              The  displayed  output will be ascii characters only. The text will be displayed in
              English and numbers will not be formatted. The short option must be by  itself,  it
              cannot be concatenated with other options.

       --version, -V
              Print  version  number  and  quit. The short option must be by itself, it cannot be
              concatenated with other options.

       --help, -h, -?
              Print a help message and quit. The short option must be by  itself,  it  cannot  be
              concatenated with other 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

       2.03

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>.  Updated  from  2010  to 2013 by Matteo Cypriani
       <mcy@lm7.fr>.