Provided by: astyle_2.01-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

       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  broken  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.  Minimum conditional indent
              is 4 spaces, or one-half the spaces per indent if a different setting is  used.  If
              you  want  to  change the spaces per indent for this style it will be easier to use
              the K&R style instead.

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

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

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

       --keep-one-line-blocks, -O
              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  overridden
       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

       2.01

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 on April 2010,  February  2011  by  Matteo
       Cypriani <mcy@lm7.fr>.