2099 lines
90 KiB
HTML
2099 lines
90 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
|
|
|
|
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
|
|
|
|
<head>
|
|
<title>Artistic Style</title>
|
|
<meta http-equiv="Content-Language" content="en-us" />
|
|
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
|
|
<meta name="description" content="Artistic Style is a source code indenter, source code formatter, and source code beautifier
|
|
for the C, C++, C# and Java programming languages." />
|
|
<meta name="keywords" content="artistic style, astyle, source code indenter, source code formatter, source code beautifier" />
|
|
<link href="favicon.ico" rel="shortcut icon" type="image/x-icon" />
|
|
<link href="styles.css" rel="stylesheet" type="text/css" />
|
|
|
|
<!-- the following styles are additions to styles.css -->
|
|
|
|
<style type="text/css">
|
|
hr { margin-left: -0.4in; }
|
|
/* the following styles are for formatting code samples */
|
|
div.code { background: #D8D8FF; }
|
|
/* code */
|
|
p.code { margin-left: 0.3in; }
|
|
code { color: navy; }
|
|
code.title { font-size: larger; font-weight: bold; }
|
|
/* spans */
|
|
span.brace { color: red; }
|
|
span.comment { color: dimgray; font-style: italic; }
|
|
span.option { color: saddlebrown; }
|
|
</style>
|
|
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<h1>Artistic Style 2.06</h1>
|
|
|
|
<h2>
|
|
A Free, Fast, and Small Automatic Formatter<br />
|
|
for C, C++, C++/CLI, Objective‑C, C#, and Java Source Code
|
|
</h2>
|
|
|
|
<h3 id="Contents">Contents</h3>
|
|
|
|
<p class="contents1">
|
|
<a class="contents" href="#_General_Information">General Information</a></p>
|
|
<p class="contents1">
|
|
<a class="contents" href="#_Quick_Start">Quick Start</a></p>
|
|
<p class="contents1">
|
|
<a class="contents" href="#_Usage">Usage</a></p>
|
|
<p class="contents1">
|
|
<a class="contents" href="#_Options">Options</a></p>
|
|
<p class="contents1">
|
|
<a class="contents" href="#_Options_File">Options File</a></p>
|
|
<p class="contents1">
|
|
<a class="contents" href="#_Disable_Formatting">Disable Formatting</a></p>
|
|
<p class="contents1">
|
|
<a class="contents" href="#_Bracket_Style_Options">Bracket Style Options</a></p>
|
|
<p class="contents2">
|
|
<a class="contents" href="#_default_bracket_style">default bracket style</a>
|
|
<a class="contents" href="#_style=allman">style=allman</a>
|
|
<a class="contents" href="#_style=java">style=java</a>
|
|
<a class="contents" href="#_style=kr">style=kr</a>
|
|
<a class="contents" href="#_style=stroustrup">style=stroustrup</a>
|
|
<a class="contents" href="#_style=whitesmith">style=whitesmith</a>
|
|
<a class="contents" href="#_style=vtk">style=vtk</a>
|
|
<a class="contents" href="#_style=banner">style=banner</a>
|
|
<a class="contents" href="#_style=gnu">style=gnu</a>
|
|
<a class="contents" href="#_style=linux">style=linux</a>
|
|
<a class="contents" href="#_style=horstmann">style=horstmann</a>
|
|
<a class="contents" href="#_style=1tbs">style=1tbs</a>
|
|
<a class="contents" href="#_style=google">style=google</a>
|
|
<a class="contents" href="#_style=pico">style=pico</a>
|
|
<a class="contents" href="#_style=lisp">style=lisp</a> </p>
|
|
<p class="contents1">
|
|
<a class="contents" href="#_Tab_Options">Tab Options</a></p>
|
|
<p class="contents2">
|
|
<a class="contents" href="#_default_indent">default indent</a>
|
|
<a class="contents" href="#_indent=spaces">indent=spaces</a>
|
|
<a class="contents" href="#_indent=tab">indent=tab</a>
|
|
<a class="contents" href="#_indent=force-tab">indent=force‑tab</a>
|
|
<a class="contents" href="#_indent=force-tab-x">--indent=force‑tab‑x</a> </p>
|
|
<p class="contents1">
|
|
<a class="contents" href="#_Bracket_Modify_Options">Bracket Modify Options</a></p>
|
|
<p class="contents2">
|
|
<a class="contents" href="#_attach_namespaces">attach‑namespaces</a>
|
|
<a class="contents" href="#_attach_classes">attach‑classes</a>
|
|
<a class="contents" href="#_attach_inlines">attach‑inlines</a>
|
|
<a class="contents" href="#_attach-extern-c">attach‑extern‑c</a> </p>
|
|
<p class="contents1">
|
|
<a class="contents" href="#_Indentation_Options">Indentation Options</a></p>
|
|
<p class="contents2">
|
|
<a class="contents" href="#_indent-classes">indent‑classes</a>
|
|
<a class="contents" href="#_indent-modifiers">indent‑modifiers</a>
|
|
<a class="contents" href="#_indent-switches">indent‑switches</a>
|
|
<a class="contents" href="#_indent-cases">indent‑cases</a>
|
|
<a class="contents" href="#_indent-namespaces">indent‑namespaces</a>
|
|
<a class="contents" href="#_indent-labels">indent‑labels</a>
|
|
<a class="contents" href="#_indent-preproc-block">indent‑preproc‑block</a>
|
|
<a class="contents" href="#_indent-preproc-define">indent‑preproc‑define</a>
|
|
<a class="contents" href="#_indent-preproc-cond">indent‑preproc‑cond</a>
|
|
<a class="contents" href="#_indent-col1-comments">indent‑col1‑comments</a>
|
|
<a class="contents" href="#_min-conditional-indent">min‑conditional‑indent</a>
|
|
<a class="contents" href="#_max-instatement-indent">max‑instatement‑indent</a>
|
|
</p>
|
|
<p class="contents1">
|
|
<a class="contents" href="#_Padding_Options">Padding Options</a></p>
|
|
<p class="contents2">
|
|
<a class="contents" href="#_break-blocks">break‑blocks</a>
|
|
<a class="contents" href="#_break-blocks=all">break‑blocks=all</a>
|
|
<a class="contents" href="#_pad-oper">pad‑oper</a>
|
|
<a class="contents" href="#_pad-comma">pad‑comma</a>
|
|
<a class="contents" href="#_pad-paren">pad‑paren</a>
|
|
<a class="contents" href="#_pad-paren-out">pad‑paren‑out</a>
|
|
<a class="contents" href="#_pad-first-paren-out">pad‑first‑paren‑out</a>
|
|
<a class="contents" href="#_pad-paren-in">pad‑paren‑in</a>
|
|
<a class="contents" href="#_pad-header">pad‑header</a>
|
|
<a class="contents" href="#_unpad-paren">unpad‑paren</a>
|
|
<a class="contents" href="#_delete-empty-lines">delete‑empty‑lines</a>
|
|
<a class="contents" href="#_fill-empty-lines">fill‑empty‑lines</a>
|
|
<a class="contents" href="#_align-pointer">align‑pointer</a>
|
|
<a class="contents" href="#_align-reference">align‑reference</a> </p>
|
|
<p class="contents1">
|
|
<a class="contents" href="#_Formatting_Options">Formatting Options</a></p>
|
|
<p class="contents2">
|
|
<a class="contents" href="#_break-closing-brackets">break‑closing‑brackets</a>
|
|
<a class="contents" href="#_break-elseifs">break‑elseifs</a>
|
|
<a class="contents" href="#_add-brackets">add‑brackets</a>
|
|
<a class="contents" href="#_add-one-line-brackets">add‑one‑line‑brackets</a>
|
|
<a class="contents" href="#_remove-brackets">remove‑brackets</a>
|
|
<a class="contents" href="#_keep-one-line-blocks">keep‑one‑line‑blocks</a>
|
|
<a class="contents" href="#_keep-one-line-statements">keep‑one‑line‑statements</a>
|
|
<a class="contents" href="#_convert-tabs">convert‑tabs</a>
|
|
<a class="contents" href="#_close-templates">close‑templates</a>
|
|
<a class="contents" href="#_remove-comment-prefix">remove‑comment‑prefix</a>
|
|
<a class="contents" href="#_max-code-length">max‑code‑length</a>
|
|
<a class="contents" href="#_max-code-length">break‑after‑logical</a>
|
|
<a class="contents" href="#_mode">mode</a> </p>
|
|
<p class="contents1">
|
|
<a class="contents" href="#_Objective_C_Options">Objective‑C Options</a></p>
|
|
<p class="contents2">
|
|
<a class="contents" href="#_pad-method-prefix">pad‑method‑prefix</a>
|
|
<a class="contents" href="#_unpad-method-prefix">unpad‑method‑prefix</a>
|
|
<a class="contents" href="#_pad-return-type">pad‑return‑type</a>
|
|
<a class="contents" href="#_unpad-return-type">unpad‑return‑type</a>
|
|
<a class="contents" href="#_align-method-colon">align‑method‑colon</a>
|
|
<a class="contents" href="#_pad-method-colon">pad‑method‑colon</a> </p>
|
|
<p class="contents1">
|
|
<a class="contents" href="#_Other_Options">Other Options</a> </p>
|
|
<p class="contents2">
|
|
<a class="contents" href="#_suffix">suffix</a> <a class="contents" href="#_suffix=none">suffix=none</a>
|
|
<a class="contents" href="#_recursive">recursive</a>
|
|
<a class="contents" href="#_dry-run">dry-run</a>
|
|
<a class="contents" href="#_exclude">exclude</a>
|
|
<a class="contents" href="#_ignore-exclude-errors">ignore‑exclude‑errors</a>
|
|
<a class="contents" href="#_ignore-exclude-errors-x">ignore‑exclude‑errors‑x</a>
|
|
<a class="contents" href="#_errors-to-stdout">errors‑to‑stdout</a>
|
|
<a class="contents" href="#_preserve-date">preserve‑date</a>
|
|
<a class="contents" href="#_verbose">verbose</a>
|
|
<a class="contents" href="#_formatted">formatted</a>
|
|
<a class="contents" href="#_quiet">quiet</a>
|
|
<a class="contents" href="#_lineend">lineend</a> </p>
|
|
<p class="contents1">
|
|
<a class="contents" href="#_Command_Line_Only">Command Line Only</a></p>
|
|
<p class="contents2">
|
|
<a class="contents" href="#_options=">options</a>
|
|
<a class="contents" href="#_options=none">options=none</a>
|
|
<a class="contents" href="#_ascii">ascii</a>
|
|
<a class="contents" href="#_version">version</a>
|
|
<a class="contents" href="#_help">help</a>
|
|
<a class="contents" href="#_html">html</a>
|
|
<a class="contents" href="#_html=">html=</a> </p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
|
|
<!-- * * * * * * * * * * * * General Information< * * * * * * * * * * * * -->
|
|
|
|
<h3 id="_General_Information">General Information</h3>
|
|
|
|
<h4>Line Endings</h4>
|
|
|
|
<p>
|
|
Line endings in the formatted file will be the same as the input file. If there are mixed line endings the most
|
|
frequent occurrence will be used. There is also an option to specify or change the line endings.</p>
|
|
|
|
<h4>File Type</h4>
|
|
|
|
<p>
|
|
Artistic Style will determine the file type from the file extension. The extension ".java" indicates a Java file,
|
|
and ".cs" indicates a C# file. Everything else is a C type file (C, C++, C++/CLI, or Objective-C). If you are
|
|
using a non-standard file extension for Java or C#, use one of the <code>--mode=</code> options.</p>
|
|
|
|
<h4>Wildcards and Recursion</h4>
|
|
|
|
<p>
|
|
Artistic Style can process directories recursively. Wildcards (such as "*.cpp" or "*.c??") are processed internally.
|
|
If a shell is used it should pass the wildcards to Artistic Style instead of resolving them first. For Linux use
|
|
double quotes around paths whose file name contains wildcards. For Windows use double quotes around paths whose
|
|
file name contains spaces. The <a href="#_recursive">recursive</a> option in the
|
|
<a href="#_Other_Options">Other Options</a> section contains information on recursive processing.</p>
|
|
|
|
<h4>File Names</h4>
|
|
|
|
<p>
|
|
When a file is formatted, the newly indented file retains the original file name. A copy of the original file
|
|
is created with an <code><strong>.orig</strong></code> appended to the original file name. (This can be set to
|
|
a different string by the option <code>--suffix=</code>, or suppressed altogether by the options <code>-n</code>
|
|
or <code>--suffix=none</code>). Thus, after indenting <code><em>SourceFile.cpp</em></code> the indented file will
|
|
be named <code><em>SourceFile.cpp</em></code>, while the original pre-indented file will be renamed to
|
|
<code><em>SourceFile.cpp.orig</em></code>.</p>
|
|
|
|
<h4>Internationalization</h4>
|
|
|
|
<p>
|
|
Artistic Style has been internationalized to process files and directories in any language.</p>
|
|
<p>
|
|
It has also been translated into several languages. The translation to use is determined from the User Locale
|
|
for Windows and the LANG environment variable for other systems. The translation will be done automatically from
|
|
these settings. If no translation is available it will default to English. There is an ascii option to use English
|
|
instead of the system language.</p>
|
|
<p>
|
|
The source code for the translations is at the end of ASLocalizer.cpp in the form of an English‑Translation
|
|
pair. If you make corrections to a translation, send the source as a bug report and it will be included in the
|
|
next release.</p>
|
|
<p>
|
|
To add a new language, add a new translation class to ASLocalizer.h. Add the English‑Translation pair to
|
|
the constructor in ASLocalizer.cpp. Update the WinLangCode array and add the language code to the function setTranslationClass().
|
|
The ASLocalizer.cpp program contains comments that give web pages for obtaining the LCIDs and language codes.
|
|
Send the source code as a bug report and it will be included in the next release.</p>
|
|
|
|
<h4>Other Considerations</h4>
|
|
|
|
<p>
|
|
The names of special characters used in programming vary by region. The terminology used by Artistic Style,
|
|
followed by other common names, is<strong>:</strong></p>
|
|
<blockquote>
|
|
brackets { } ‑ also called braces, curly brackets, or curly braces.<br />
|
|
parens ( ) ‑ also called parentheses, brackets, round brackets, circle brackets, or soft brackets.<br />
|
|
block parens [ ] ‑ also called brackets, square brackets, closed brackets, or hard brackets.<br />
|
|
angle brackets < > ‑ also called brackets, pointy brackets, triangular brackets, diamond brackets, tuples,
|
|
or chevrons.
|
|
</blockquote>
|
|
<p>
|
|
Visual Studio, and possibly other development environments, has an Edit option "Align Assignments" that will align
|
|
assignment operators across multiple lines. There is also an extension named "Code alignment" that will align
|
|
the code on other items as well. Formatting with these options and extensions can be used with Artistic Style.
|
|
The space padding will be maintained and the alignment will be preserved. </p>
|
|
<p>
|
|
Artistic Style can format standard class library statements such as Open GL, wxWidgets, Qt, and MFC.</p>
|
|
<p>
|
|
Embedded assembler language is formatted correctly. This includes extended assembly and Microsoft specific assembler
|
|
lines and blocks.</p>
|
|
<p>
|
|
Artistic Style can format embedded SQL statements. The SQL formatting will be maintained as long as the standard
|
|
hanging indent format is used. If the "exec sql" statement is indented more than the following statements, the
|
|
SQL will be aligned in a single column.</p>
|
|
<p>
|
|
Unicode files encoded as UTF‑16, both big and little endian, will be formatted. The files must begin with
|
|
a byte order mark (BOM) to be recognized. Files encoded as UTF‑32 will be rejected. Some compilers do not
|
|
support these encodings. These files can be converted to UTF‑8 encoding with the program "iconv". There
|
|
are Linux and Windows versions available (the Windows version does not seem to work for all encodings). A sample
|
|
command line is "iconv ‑f UTF‑16 ‑t UTF‑8 < filein.cpp > fileout.cpp. Visual
|
|
Studio can convert the files from the "File > Advanced Save Options" menu. Then select encoding "Unicode (UTF‑8
|
|
with signature) - Codepage 65001". There are other development environments and text editors, such as SciTE, that
|
|
can convert files to UTF‑8.</p>
|
|
<p>
|
|
Embedded statements that are multiple-line and are NOT in a C-type format, such as Python, are usually mal-formatted
|
|
(a C-type format has blocks enclosed by brackets and statements terminated by a semi-colon). Macros that define
|
|
functions may cause the following code to be mal-formatted because the macro is missing the brackets and semi-colons
|
|
from the definition. If you have source code with these types of statements, exclude them with the
|
|
<a href="#_exclude">exclude=####</a> option described in the <a href="#_Other_Options">Other Options</a>
|
|
section.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
|
|
<!-- * * * * * * * * * * * * * * Quick Start * * * * * * * * * * * * * * -->
|
|
|
|
<h3 id="_Quick_Start">Quick Start</h3>
|
|
|
|
<p>
|
|
If you have never used Artistic Style there are a couple of ways to start.</p>
|
|
<p>
|
|
One is to run it with no options at all. This will use the <a href="#_default_bracket_style">default bracket
|
|
style</a>, 4 spaces per indent, and no formatting changes. This will break the brackets for one
|
|
line blocks and will break one line statements. To change this use the option
|
|
<a href="#_keep-one-line-blocks">keep-one-line-blocks</a> and/or
|
|
<a href="#_keep-one-line-statements">keep-one-line-statements</a> described in the
|
|
<a href="#_Formatting_Options">Formatting Options</a> section</p>
|
|
<p>
|
|
Another way is to use one of the bracket styles described in the <a href="#_Bracket_Style_Options">Bracket Style
|
|
Options</a> section. Select one with a bracket formatting style you like. If no indentation option is set,
|
|
the default option of 4 spaces will be used. These options also break one line blocks and one line statements
|
|
as described above.</p>
|
|
<p>
|
|
Once you are familiar with the options you can customize the format to your personal preference.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
|
|
<!-- * * * * * * * * * * * * * * * Usage * * * * * * * * * * * * * * * -->
|
|
|
|
<h3 id="_Usage">Usage</h3>
|
|
|
|
<p>
|
|
Artistic style is a console program that receives information from the command line. The format of the command
|
|
line is:</p>
|
|
<pre>astyle [OPTIONS] <em>SourceFile1 SourceFile2 SourceFile3 [ . . . ]</em>
|
|
</pre>
|
|
<p>
|
|
The block parens [ ] indicate that more than one option or more than one file name can be entered. They are NOT
|
|
actually included in the command. For the options format see the following Options section.</p>
|
|
<div class="code">
|
|
<p class="code">
|
|
Example to format a single file:</p>
|
|
<pre>astyle --style=allman /home/user/project/foo.cpp
|
|
</pre>
|
|
<p class="code">
|
|
Example to format all .cpp and .h files recursively:</p>
|
|
<pre>astyle --style=allman --recursive /home/user/project/*.cpp /home/user/project/*.h
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
The < and > characters may be used to redirect the files into standard input (stdin) and out of standard output
|
|
(stdout) - don't forget them! With this option only one file at a time can be formatted. Wildcards are not
|
|
recognized, there are no console messages, and a backup is not created. On Windows the output will always have
|
|
Windows line ends.</p>
|
|
<div class="code">
|
|
<p class="code">
|
|
Example of redirection option to format a single file and change the name:</p>
|
|
<pre>astyle --style=allman < <em>OriginalSourceFile</em> > <em>BeautifiedSourceFile</em>
|
|
</pre>
|
|
</div>
|
|
<div class="code">
|
|
<p class="code">
|
|
The redirection option may be used to display the formatted file without updating:</p>
|
|
<pre>astyle --style=allman < <em>OriginalSourceFile</em> | less
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
|
|
<!-- * * * * * * * * * * * * * * * Options * * * * * * * * * * * * * * * -->
|
|
|
|
<h3 id="_Options">Options</h3>
|
|
|
|
<p>
|
|
Not specifying any options will result in the <a href="#_default_bracket_style">default bracket style</a>,
|
|
4 spaces per indent, and no formatting changes.</p>
|
|
<p>
|
|
Options may be written in two different ways.</p>
|
|
|
|
<h4>Long options</h4>
|
|
|
|
<p>
|
|
These options start with '<strong>--</strong>', and must be written one at a time.<br />
|
|
(Example: '<code>--style=allman --indent=spaces=4</code>')</p>
|
|
|
|
<h4>Short Options</h4>
|
|
|
|
<p>
|
|
These options start with a single '<strong>-</strong>', and may be concatenated together.<br />
|
|
(Example: '<code>-bps4</code>' is the same as writing '<code>-b -p -s4</code>'.)</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
|
|
<!-- * * * * * * * * * * * * * * Options File * * * * * * * * * * * * * * -->
|
|
|
|
<h3 id="_Options_File">Options File</h3>
|
|
|
|
<p>
|
|
An OPTIONAL default options file may be used to supplement or replace the command line options. </p>
|
|
<ul>
|
|
<li>The command line options have precedence. If there is a conflict between a command line option and an option in
|
|
the default options file, the command line option will be used.
|
|
</li>
|
|
<li>Artistic Style looks for this file in the following locations (in order):
|
|
<ol>
|
|
<li>the file indicated by the --options= command line option;</li>
|
|
<li>the file and directory indicated by the environment variable ARTISTIC_STYLE_OPTIONS (if it exists);</li>
|
|
<li>the file named .astylerc in the directory pointed to by the HOME environment variable (e.g. "$HOME/.astylerc"
|
|
on Linux);
|
|
</li>
|
|
<li>the file named astylerc in the directory pointed to by the USERPROFILE environment variable (e.g. "%USERPROFILE%\astylerc"
|
|
on Windows).
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
<li>This option file lookup can be disabled by specifying --options=none on the command line.</li>
|
|
<li>Options may be set apart by new-lines, tabs, commas, or spaces.</li>
|
|
<li>Long options in the options file may be written without the preceding '--'.</li>
|
|
<li>Lines within the options file that begin with '#' are considered line-comments.</li>
|
|
</ul>
|
|
<p>
|
|
Example of a default options file:</p>
|
|
<div class="code">
|
|
<pre><span class="comment"># this line is a comment</span>
|
|
--style=allman <span class="comment"># this is a line-end comment</span>
|
|
<span class="comment"># long options can be written without the preceding '--'</span>
|
|
indent-switches <span class="comment"># cannot do this on the command line</span>
|
|
<span class="comment"># short options must have the preceding '-'</span>
|
|
-t -p
|
|
<span class="comment"># short options can be concatenated together</span>
|
|
-M60Ucv</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
|
|
<hr />
|
|
|
|
<!-- * * * * * * * * * * * * * Disable Formatting * * * * * * * * * * * * * -->
|
|
|
|
<h3 id="_Disable_Formatting">Disable Formatting</h3>
|
|
|
|
<p>
|
|
Formatting and indenting can be disabled with comment tags inserted in the source code.</p>
|
|
|
|
<h4>Disable Block</h4>
|
|
|
|
<p>
|
|
Blocks of code can be disabled using "off" and "on" tags. The tags are included in the source
|
|
file as comments. The comment may be a C comment (/* ... */) or a C++ line comment (//). The tag must be included
|
|
in a single line comment. If the comment exceeds one line the indent tag will be ignored. Additional information
|
|
can be included with the tag.</p>
|
|
<p>
|
|
The beginning tag is "*INDENT-OFF*" and the ending tag is "*INDENT-ON*".
|
|
They may be used anywhere in the program with the following condition; parsing is partially disabled between the
|
|
tags. Disabling partial statements may result in incorrect formatting after the ending tag. If this happens expand
|
|
the tags to include additional code.</p>
|
|
<div class="code">
|
|
<p class="code">
|
|
The following retains the format of a preprocessor define:</p>
|
|
<pre><span class="comment">// *INDENT-OFF*</span>
|
|
#define FOO_DECLARE_int32_(name) \
|
|
FOO_API_ extern ::Int32 FOO_FLAG(name)
|
|
<span class="comment">// *INDENT-ON*</span></pre>
|
|
</div>
|
|
|
|
<h4>Disable Line</h4>
|
|
|
|
<p>
|
|
Artistic Style cannot always determine the usage of symbols with more than one meaning. For example an asterisk
|
|
(*) can be multiplication, a pointer, or a pointer dereference. The "&" and "&&"
|
|
symbols are a similar
|
|
problem.</p>
|
|
<p>
|
|
If a symbol is being padded incorrectly, padding it manually may fix the problem. If it is still being
|
|
padded incorrectly, then disabling the formatting may be necessary. To avoid having to use the "disable block"
|
|
tags above, a single line disable is available.</p>
|
|
<p>
|
|
A line-end comment tag "*NOPAD* will disable the "pad-oper", "align-pointer", and "align-reference"
|
|
options. Parsing does NOT stop and all other formatting will be applied to the line. The tag applies to the
|
|
one line only.</p>
|
|
<div class="code">
|
|
<p class="code">
|
|
The following prevents the operator padding from changing:</p>
|
|
<pre>size_t foo = (unsigned int) -1; // *NOPAD*</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
|
|
<!-- * * * * * * * * * * * * Bracket Style Options * * * * * * * * * * * * -->
|
|
|
|
<h3 id="_Bracket_Style_Options">Bracket Style Options</h3>
|
|
|
|
<p>
|
|
Bracket Style options define the bracket style to use. All options default to 4 spaces per indent, indented with
|
|
spaces. By default, none of the styles indent namespaces. Other indentations are indicated in the individual style
|
|
description. All options will break the brackets for one line blocks and will break one line statements. To change
|
|
this use the option <a href="#_keep-one-line-blocks">keep-one-line-blocks</a> and/or <a href="#_keep-one-line-statements">
|
|
keep-one-line-statements</a> described in the <a href="#_Formatting_Options">Formatting Options</a>
|
|
section.</p>
|
|
<p>
|
|
</p>
|
|
<p id="_default_bracket_style">
|
|
<code class="title">default bracket style</code><br />
|
|
If no bracket style is requested, the default bracket style will be used. The opening brackets are not changed
|
|
and the closing brackets will be broken from the preceding line. There are a few exceptions to this.</p>
|
|
<p>
|
|
</p>
|
|
<p id="_style=allman">
|
|
<code class="title">--style=allman / --style=bsd / --style=break / -A1</code><br />
|
|
Allman style uses broken brackets.</p>
|
|
<div class="code">
|
|
<pre>int Foo(bool isBar)
|
|
<span class="brace">{</span>
|
|
if (isBar)
|
|
<span class="brace">{</span>
|
|
bar();
|
|
return 1;
|
|
<span class="brace">}</span>
|
|
else
|
|
return 0;
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_style=java">
|
|
<code class="title">--style=java / --style=attach / -A2</code><br />
|
|
Java style uses attached brackets.</p>
|
|
<div class="code">
|
|
<pre>int Foo(bool isBar) <span class="brace">{</span>
|
|
if (isBar) <span class="brace">{</span>
|
|
bar();
|
|
return 1;
|
|
<span class="brace">}</span> else
|
|
return 0;
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_style=kr">
|
|
<code class="title">--style=kr / --style=k&r / --style=k/r / -A3</code><br />
|
|
Kernighan & Ritchie style uses linux brackets. Opening brackets are broken from namespaces, classes, and function
|
|
definitions. Brackets are attached to everything else including statements within a function, arrays, structs,
|
|
and enums.</p>
|
|
<p>
|
|
Using the k&r option may cause problems because of the &. This can be resolved by enclosing the k&r
|
|
in quotes (e.g. ‑‑style="k&r") or by using one of the alternates ‑‑style=kr or
|
|
‑‑style=k/r.</p>
|
|
<div class="code">
|
|
<pre>int Foo(bool isBar)
|
|
<span class="brace">{</span>
|
|
if (isBar) <span class="brace">{</span>
|
|
bar();
|
|
return 1;
|
|
<span class="brace">}</span> else
|
|
return 0;
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_style=stroustrup">
|
|
<code class="title">--style=stroustrup / -A4</code><br />
|
|
Stroustrup style uses stroustrup brackets. Brackets are broken from function definitions only. Brackets are attached
|
|
to everything else including namespaces, classes, and statements within a function, arrays, structs, and enums.
|
|
This style frequently is used with an indent of 5 spaces.</p>
|
|
<div class="code">
|
|
<pre>int Foo(bool isBar)
|
|
<span class="brace">{</span>
|
|
if (isBar) <span class="brace">{</span>
|
|
bar();
|
|
return 1;
|
|
<span class="brace">}</span> else
|
|
return 0;
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_style=whitesmith">
|
|
<code class="title">--style=whitesmith / -A5</code><br />
|
|
Whitesmith style uses broken, indented brackets. Switch blocks and class blocks are indented to prevent a 'hanging
|
|
indent' with following case statements and C++ class modifiers (public, private, protected). </p>
|
|
<div class="code">
|
|
<pre>int Foo(bool isBar)
|
|
<span class="brace">{</span>
|
|
if (isBar)
|
|
<span class="brace">{</span>
|
|
bar();
|
|
return 1;
|
|
<span class="brace">}</span>
|
|
else
|
|
return 0;
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_style=vtk">
|
|
<code class="title">--style=vtk / -A15</code><br />
|
|
VTK (Visualization Toolkit) style uses broken, indented brackets, except for the opening bracket. Switch blocks
|
|
are indented to prevent a 'hanging indent' with following case statements. </p>
|
|
<div class="code">
|
|
<pre>int Foo(bool isBar)
|
|
<span class="brace">{</span>
|
|
if (isBar)
|
|
<span class="brace">{</span>
|
|
bar();
|
|
return 1;
|
|
<span class="brace">}</span>
|
|
else
|
|
return 0;
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_style=banner">
|
|
<code class="title">--style=banner / -A6</code><br />
|
|
Banner style uses attached, indented brackets. Switch blocks and class blocks are indented to prevent a 'hanging
|
|
indent' with following case statements and C++ class modifiers (public, private, protected). </p>
|
|
<div class="code">
|
|
<pre>int Foo(bool isBar) <span class="brace">{</span>
|
|
if (isBar) <span class="brace">{</span>
|
|
bar();
|
|
return 1;
|
|
<span class="brace">}</span>
|
|
else
|
|
return 0;
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_style=gnu">
|
|
<code class="title">--style=gnu / -A7</code><br />
|
|
GNU style uses broken brackets and indented blocks. This style frequently is used with
|
|
an indent of 2 spaces.</p>
|
|
<p>
|
|
Extra indentation is added to blocks <strong>within a function</strong>. The opening bracket for namespaces, classes,
|
|
and functions is not indented.</p>
|
|
<div class="code">
|
|
<pre>int Foo(bool isBar)
|
|
<span class="brace">{</span>
|
|
if (isBar)
|
|
<span class="brace">{</span>
|
|
bar();
|
|
return 1;
|
|
<span class="brace">}</span>
|
|
else
|
|
return 0;
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_style=linux">
|
|
<code class="title">--style=linux / --style=knf / -A8</code><br />
|
|
Linux style uses linux brackets. Opening brackets are broken from namespace, class, and function
|
|
definitions. Brackets are attached to everything else including statements within a function, arrays, structs,
|
|
and enums. <strong>Minimum conditional indent</strong> 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.</p>
|
|
<p>
|
|
Also known as Kernel Normal Form (KNF) style, this is the style used in the Linux kernel.</p>
|
|
<div class="code">
|
|
<pre>int Foo(bool isBar)
|
|
<span class="brace">{</span>
|
|
if (isFoo) <span class="brace">{</span>
|
|
bar();
|
|
return 1;
|
|
<span class="brace">}</span> else
|
|
return 0;
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_style=horstmann">
|
|
<code class="title">--style=horstmann / -A9</code><br />
|
|
Horstmann style 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.</p>
|
|
<div class="code">
|
|
<pre>int Foo(bool isBar)
|
|
<span class="brace">{</span> if (isBar)
|
|
<span class="brace">{</span> bar();
|
|
return 1;
|
|
<span class="brace">}</span>
|
|
else
|
|
return 0;
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_style=1tbs">
|
|
<code class="title">--style=1tbs / --style=otbs / -A10</code><br />
|
|
"One True Brace Style" uses linux brackets and adds brackets to unbracketed one line conditional
|
|
statements. Opening brackets are broken from namespaces, classes, and function definitions. Brackets are attached
|
|
to everything else including statements within a function, arrays, structs, and enums. </p>
|
|
<p>
|
|
In the following example brackets have been added to the "<code>return 0;</code>" statement. The option
|
|
‑‑add‑one‑line‑brackets can also be used with this style.</p>
|
|
<div class="code">
|
|
<pre>int Foo(bool isBar)
|
|
<span class="brace">{</span>
|
|
if (isFoo) <span class="brace">{</span>
|
|
bar();
|
|
return 1;
|
|
<span class="brace">}</span> else <span class="brace">{</span>
|
|
return 0;
|
|
<span class="brace">}</span>
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_style=google">
|
|
<code class="title">--style=google / -A14</code><br />
|
|
Google style uses attached brackets and indented class access modifiers. See the indent-modifiers
|
|
option for an example of the indented modifiers format. This style frequently is used with an indent of
|
|
2 spaces.</p>
|
|
<div class="code">
|
|
<pre>int Foo(bool isBar) <span class="brace">{</span>
|
|
if (isBar) <span class="brace">{</span>
|
|
bar();
|
|
return 1;
|
|
<span class="brace">}</span> else
|
|
return 0;
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_style=pico">
|
|
<code class="title">--style=pico / -A11</code><br />
|
|
Pico style uses run-in brackets and attached closing 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.
|
|
If add-brackets is used they will be added as one-line brackets. This style frequently is used with an indent
|
|
of 2 spaces.</p>
|
|
<div class="code">
|
|
<pre>int Foo(bool isBar)
|
|
<span class="brace">{</span> if (isBar)
|
|
<span class="brace">{</span> bar();
|
|
return 1; <span class="brace">}</span>
|
|
else
|
|
return 0; <span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_style=lisp">
|
|
<code class="title">--style=lisp / --style=python / -A12</code><br />
|
|
Lisp style uses attached opening and closing 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.</p>
|
|
<div class="code">
|
|
<pre>int Foo(bool isBar) <span class="brace">{</span>
|
|
if (isBar) <span class="brace">{
|
|
</span> bar()
|
|
return 1; <span class="brace">}
|
|
</span> else
|
|
return 0; <span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
|
|
<!-- * * * * * * * * * * * * * * * Tab Options * * * * * * * * * * * * * * * -->
|
|
|
|
<h3 id="_Tab_Options">Tab Options</h3>
|
|
|
|
<p>
|
|
The following examples show whitespace characters. A space is indicated with a <strong>.</strong> (dot), a tab
|
|
is indicated by a > (greater than).</p>
|
|
<p id="_default_indent">
|
|
<code class="title">default indent</code><br />
|
|
If no indentation option is set, the default option of 4 spaces will be used (e.g. <code>-s<span class="option">4</span>
|
|
--indent=spaces=<span class="option">4</span>
|
|
</code>).</p>
|
|
<div class="code">
|
|
<p class="code">
|
|
with default values:</p>
|
|
<pre>void Foo() <span class="brace">{</span>
|
|
....if (isBar1
|
|
............&& isBar2) <span class="comment">// indent of this line can be changed with min-conditional-indent</span>
|
|
........bar();
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_indent=spaces">
|
|
<code class="title">--indent=spaces / --indent=spaces=<span class="option">#</span> / -s<span class="option">#</span></code><br />
|
|
Indent using # <strong>spaces</strong> per indent (e.g. <code>-s<span class="option">3</span></code> <code>--indent=spaces=<span
|
|
class="option">3</span>
|
|
</code>). # must be between 2 and 20. Not specifying # will result in a default of
|
|
4 spaces per indent.</p>
|
|
<div class="code">
|
|
<p class="code">
|
|
with indent=spaces=3</p>
|
|
<pre>void Foo() <span class="brace">{</span>
|
|
...if (isBar1
|
|
.........&& isBar2) <span class="comment">// indent of this line can be changed with min-conditional-indent</span>
|
|
......bar();
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_indent=tab">
|
|
<code class="title">--indent=tab / --indent=tab=<span class="option">#</span> / -t / -t<span class="option">#</span></code><br />
|
|
Indent using <strong>tabs for indentation, and spaces for continuation line alignment</strong>. This ensures that
|
|
the code is displayed correctly regardless of the viewer’s tab size. Treat each indent as # spaces
|
|
(e.g. <code>-t<span class="option">6</span></code> / <code>--indent=tab=<span class="option">6</span></code>).
|
|
# must be between 2 and 20. If no # is set, treats indents as 4 spaces.</p>
|
|
<div class="code">
|
|
<p class="code">
|
|
with indent=tab:</p>
|
|
<pre>void Foo() <span class="brace">{</span>
|
|
> if (isBar1
|
|
> ........&& isBar2) <span class="comment">// indent of this line can be changed with min-conditional-indent</span>
|
|
> > bar();
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
<p class="code">
|
|
with style=linux, indent=tab=8:</p>
|
|
<pre>void Foo()
|
|
<span class="brace">{</span>
|
|
> if (isBar1
|
|
> ....&& isBar2) <span class="comment">// indent of this line can NOT be changed with style=linux</span>
|
|
> > bar();
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_indent=force-tab">
|
|
<code class="title">--indent=force-tab / --indent=force-tab=<span class="option">#</span> / -T / -T<span class="option">#</span></code><br />
|
|
Indent using <strong>all tab</strong> 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. <code>-T<span class="option">6</span></code>
|
|
/ <code>--indent=<span lang="en-us">force-</span>tab=<span class="option">6</span></code>). # must be between
|
|
2 and 20. If no # is set, treats tabs as 4 spaces.</p>
|
|
<div class="code">
|
|
<p class="code">
|
|
with indent=force-tab:</p>
|
|
<pre>void Foo() <span class="brace">{</span>
|
|
> if (isBar1
|
|
> > > && isBar2) <span class="comment">// indent of this line can be changed with min-conditional-indent</span>
|
|
> > bar();
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_indent=force-tab-x">
|
|
<code class="title">--indent=force-tab-x / --indent=force-tab-x=<span class="option">#</span> / -xT / -xT<span
|
|
class="option">#</span>
|
|
</code><br />
|
|
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 <strong>a mix of both tabs and spaces.</strong> Tabs will be used to indent, if
|
|
possible. If a tab indent cannot be used, spaces will be used instead.</p>
|
|
<p>
|
|
This option sets the <strong>tab length.</strong> Treat each tab as # spaces (e.g. <code>-xT<span class="option">6</span></code>
|
|
/ <code>--indent=<span lang="en-us">force-</span>tab-x=<span class="option">6</span></code>). # must be between
|
|
2 and 20. If no # is set, treats tabs as 8 spaces. To change the <strong>indent length</strong> from the default
|
|
of 4 spaces the option "indent=force-tab" must also be used.</p>
|
|
<div class="code">
|
|
<p class="code">
|
|
with indent=force-tab-x (default tab length of 8 and default indent length of 4):</p>
|
|
<pre>void Foo() <span class="brace">{</span>
|
|
....if (isBar1
|
|
> ....&& isBar2) <span class="comment">// indent of this line can be changed with min-conditional-indent</span>
|
|
> bar();
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
|
|
<!-- * * * * * * * * * * * * Bracket Modify Options * * * * * * * * * * * * -->
|
|
|
|
<h3 id="_Bracket_Modify_Options">Bracket Modify Options</h3>
|
|
|
|
<p id="_attach_namespaces">
|
|
<code class="title">--attach-namespaces / -xn</code><br />
|
|
Attach brackets to a namespace statement. This is done regardless of the bracket style being used.</p>
|
|
<div class="code">
|
|
<p class="code">
|
|
the bracket is always attached to a namespace statement:</p>
|
|
<pre>namespace FooName <span class="brace">{</span>
|
|
...
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_attach_classes">
|
|
<code class="title">--attach-classes / -xc</code><br />
|
|
Attach brackets to a class statement. This is done regardless of the bracket style being used.</p>
|
|
<div class="code">
|
|
<p class="code">
|
|
the bracket is always attached to a class statement:</p>
|
|
<pre>class FooClass <span class="brace">{</span>
|
|
...
|
|
<span class="brace">}</span>;
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_attach_inlines">
|
|
<code class="title">--attach-inlines / -xl</code><br />
|
|
Attach brackets to class and struct inline function definitions. This is not done for run-in type brackets
|
|
(Horstmann and Pico styles). This option is effective for C++ files only.</p>
|
|
<div class="code">
|
|
<p class="code">
|
|
all brackets are always attached to class and struct inline function definitions:</p>
|
|
<pre>class FooClass
|
|
<span class="brace">{</span>
|
|
void Foo() <span class="brace">{</span>
|
|
...
|
|
<span class="brace"> }</span>
|
|
<span class="brace">}</span>;
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_attach-extern-c">
|
|
<code class="title">--attach-extern-c / -xk</code><br />
|
|
Attach brackets to a bracketed extern "C" statement. This is done regardless of the bracket style being used.
|
|
This option is effective for C++ files only.</p>
|
|
<p>
|
|
An extern "C" statement that is part of a function definition is formatted according to the requested bracket
|
|
style. Bracketed extern "C" statements are unaffected by the bracket style and this option is the only way to
|
|
change them.</p>
|
|
<div class="code">
|
|
<p class="code">
|
|
this option attaches brackets to a bracketed extern "C" statement:</p>
|
|
<pre>#ifdef __cplusplus
|
|
extern "C" <span class="brace">{</span>
|
|
#endif
|
|
</pre>
|
|
<p class="code">
|
|
but function definitions are formatted according to the requested bracket style:</p>
|
|
<pre>extern "C" EXPORT void STDCALL Foo()
|
|
<span class="brace">{}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
|
|
<!-- * * * * * * * * * * * * * Indentation Options * * * * * * * * * * * * * -->
|
|
|
|
<h3 id="_Indentation_Options">Indentation Options</h3>
|
|
|
|
<p id="_indent-classes">
|
|
<code class="title">--indent-classes / -C</code><br />
|
|
Indent '<code>class</code>' and '<code>struct</code>' blocks so that the entire block is indented. The struct
|
|
blocks are indented only if an access modifier, '<code>public:</code>', '<code>protected:</code>' or '<code>private:</code>',
|
|
is declared somewhere in the struct. This option is effective for C++ files only.</p>
|
|
<div class="code">
|
|
<pre>class Foo
|
|
<span class="brace">{</span>
|
|
public:
|
|
Foo();
|
|
virtual ~Foo();
|
|
<span class="brace">}</span>;
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>class Foo
|
|
<span class="brace">{</span>
|
|
public:
|
|
Foo();
|
|
virtual ~Foo();
|
|
<span class="brace">}</span>;
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_indent-modifiers">
|
|
<code class="title">--indent-modifiers / -xG</code><br />
|
|
Indent '<code>class</code>' and '<code>struct</code>' access modifiers, '<code>public:</code>', '<code>protected:</code>'
|
|
and '<code>private:</code>', one half indent. The rest of the class is not indented. This option is effective
|
|
for C++ files only. If used with indent‑classes this option will be ignored.</p>
|
|
<div class="code">
|
|
<pre>class Foo
|
|
<span class="brace">{</span>
|
|
public:
|
|
Foo();
|
|
virtual ~Foo();
|
|
<span class="brace">}</span>;
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>class Foo
|
|
<span class="brace">{</span>
|
|
public:
|
|
Foo();
|
|
virtual ~Foo();
|
|
<span class="brace">}</span>;
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_indent-switches">
|
|
<code class="title">--indent-switches / -S</code><br />
|
|
Indent '<code>switch</code>' blocks so that the '<code>case X:</code>' statements are indented in the <code>switch</code>
|
|
block. The entire case block is indented.</p>
|
|
<div class="code">
|
|
<pre>switch (foo)
|
|
<span class="brace">{</span>
|
|
case 1:
|
|
a += 1;
|
|
break;
|
|
|
|
case 2:
|
|
<span class="brace">{</span>
|
|
a += 2;
|
|
break;
|
|
<span class="brace">}</span>
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>switch (foo)
|
|
<span class="brace">{</span>
|
|
case 1:
|
|
a += 1;
|
|
break;
|
|
|
|
case 2:
|
|
<span class="brace">{</span>
|
|
a += 2;
|
|
break;
|
|
<span class="brace">}</span>
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_indent-cases">
|
|
<code class="title">--indent-cases / -K</code><br />
|
|
Indent '<code>case X:</code>' blocks from the '<code>case X:</code>' headers. Case statements not enclosed in
|
|
blocks are NOT indented.</p>
|
|
<div class="code">
|
|
<pre>switch (foo)
|
|
<span class="brace">{</span>
|
|
case 1:
|
|
a += 1;
|
|
break;
|
|
|
|
case 2:
|
|
<span class="brace">{</span>
|
|
a += 2;
|
|
break;
|
|
<span class="brace">}</span>
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>switch (foo)
|
|
<span class="brace">{</span>
|
|
case 1:
|
|
a += 1;
|
|
break;
|
|
|
|
case 2:
|
|
<span class="brace">{</span>
|
|
a += 2;
|
|
break;
|
|
<span class="brace">}</span>
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_indent-namespaces">
|
|
<code class="title">--indent-namespaces / -N</code><br />
|
|
Add extra indentation to namespace blocks. This option has no effect on Java files.</p>
|
|
<div class="code">
|
|
<pre>namespace foospace
|
|
<span class="brace">{</span>
|
|
class Foo
|
|
<span class="brace">{</span>
|
|
public:
|
|
Foo();
|
|
virtual ~Foo();
|
|
<span class="brace">}</span>;
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>namespace foospace
|
|
<span class="brace">{</span>
|
|
class Foo
|
|
<span class="brace">{</span>
|
|
public:
|
|
Foo();
|
|
virtual ~Foo();
|
|
<span class="brace">}</span>;
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_indent-labels">
|
|
<code class="title">--indent-labels / -L</code><br />
|
|
Add extra indentation to labels so they appear 1 indent less than the current indentation, rather than being flushed
|
|
to the left (the default).</p>
|
|
<div class="code">
|
|
<pre>void Foo() <span class="brace">{</span>
|
|
while (isFoo) <span class="brace">{</span>
|
|
if (isFoo)
|
|
goto error;
|
|
...
|
|
error:
|
|
...
|
|
<span class="brace">}</span>
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
<p class="code">
|
|
becomes (with indented 'error:'):</p>
|
|
<pre>void Foo() <span class="brace">{</span>
|
|
while (isFoo) <span class="brace">{</span>
|
|
if (isFoo)
|
|
goto error;
|
|
...
|
|
error:
|
|
...
|
|
<span class="brace">}</span>
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
|
|
<p id="_indent-preproc-block">
|
|
<code class="title">--indent-preproc-block / -xW</code><br />
|
|
Indent preprocessor blocks at bracket level zero, and immediately within a namespace. There are restrictions on
|
|
what will be indented. Blocks within methods, classes, arrays, etc, will not be indented. Blocks containing brackets
|
|
or multi-line define statements will not be indented. Without this option the preprocessor block is not
|
|
indented.</p>
|
|
<div class="code">
|
|
<pre>#ifdef _WIN32
|
|
#include <windows.h>
|
|
#ifndef NO_EXPORT
|
|
#define EXPORT
|
|
#endif
|
|
#endif
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>#ifdef _WIN32
|
|
#include <windows.h>
|
|
#ifndef NO_EXPORT
|
|
#define EXPORT
|
|
#endif
|
|
#endif
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_indent-preproc-define">
|
|
<code class="title">--indent-preproc-define / -w</code><br />
|
|
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.</p>
|
|
<div class="code">
|
|
<pre>#define Is_Bar(arg,a,b) \
|
|
(Is_Foo((arg), (a)) \
|
|
|| Is_Foo((arg), (b)))
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>#define Is_Bar(arg,a,b) \
|
|
(Is_Foo((arg), (a)) \
|
|
|| Is_Foo((arg), (b)))
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_indent-preproc-cond">
|
|
<code class="title">--indent-preproc-cond / -xw</code><br />
|
|
Indent preprocessor conditional statements to the same level as the source code.</p>
|
|
<div class="code">
|
|
<pre> isFoo = true;
|
|
#ifdef UNICODE
|
|
text = wideBuff;
|
|
#else
|
|
text = buff;
|
|
#endif</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre> isFoo = true;
|
|
#ifdef UNICODE
|
|
text = wideBuff;
|
|
#else
|
|
text = buff;
|
|
#endif
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_indent-col1-comments">
|
|
<code class="title">--indent-col1-comments / -Y</code><br />
|
|
Indent C++ comments beginning in column one. By default C++ comments beginning in column one are
|
|
assumed to be commented‑out code and not indented. This option will allow the comments to be indented with
|
|
the code.</p>
|
|
<div class="code">
|
|
<pre>void Foo()\n"
|
|
<span class="brace">{</span>
|
|
<span class="comment">// comment</span>
|
|
if (isFoo)
|
|
bar();
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>void Foo()\n"
|
|
<span class="brace">{</span>
|
|
<span class="comment">// comment</span>
|
|
if (isFoo)
|
|
bar();
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_min-conditional-indent">
|
|
<code class="title">--min-conditional-indent=<span class="option">#</span> / -m<span class="option">#</span></code><br />
|
|
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 <span class="option"><strong>#</strong></span>
|
|
indicates a <strong>number of indents</strong> and is a minimum value. The indent may be greater to align with
|
|
the data on the previous line.<br />
|
|
The valid values are:<br />
|
|
0 - no minimal indent. The lines will be aligned with the paren on the preceding line.<br />
|
|
1 - indent at least one additional indent.<br />
|
|
2 - indent at least two additional indents.<br />
|
|
3 - indent at least one-half an additional indent. This is intended for large indents (e.g. 8).<br />
|
|
The default value is <strong>2</strong>, two additional indents.</p>
|
|
<div class="code">
|
|
<pre><span class="comment">// default setting makes this non-bracketed code clear</span>
|
|
if (a < b
|
|
|| c > d)
|
|
foo++;
|
|
|
|
<span class="comment">// but creates an exaggerated indent in this bracketed code</span>
|
|
if (a < b
|
|
|| c > d)
|
|
<span class="brace">{</span>
|
|
foo++;
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
<p class="code">
|
|
becomes (when setting
|
|
<strong><code>--min-conditional-indent=<span class="option">0</span></code></strong>):</p>
|
|
<pre><span class="comment">// setting makes this non-bracketed code less clear</span>
|
|
if (a < b
|
|
|| c > d)
|
|
foo++;
|
|
|
|
<span class="comment">// but makes this bracketed code clearer</span>
|
|
if (a < b
|
|
|| c > d)
|
|
<span class="brace">{</span>
|
|
foo++;
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_max-instatement-indent">
|
|
<code class="title">--max-instatement-indent=<span class="option">#</span> / -M<span class="option">#</span></code><br />
|
|
Set the maximum of <span class="option">#</span> spaces to indent a continuation line. The <span class="option">
|
|
<strong>#</strong></span> indicates a number of columns and must not be less than <strong>40</strong> nor
|
|
greater than <strong>120</strong>. If no value is set, the default value of <strong>40</strong> will be
|
|
used. 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.</p>
|
|
<div class="code">
|
|
<pre>fooArray[] = <span class="brace">{</span> red,
|
|
green,
|
|
blue <span class="brace">}</span>;
|
|
|
|
fooFunction(barArg1,
|
|
barArg2,
|
|
barArg3);
|
|
</pre>
|
|
<p class="code">
|
|
becomes (with larger value):</p>
|
|
<pre>fooArray[] = <span class="brace">{</span> red,
|
|
green,
|
|
blue <span class="brace">}</span>;
|
|
|
|
fooFunction(barArg1,
|
|
barArg2,
|
|
barArg3);
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
|
|
<!-- * * * * * * * * * * * * * Padding Options * * * * * * * * * * * * * -->
|
|
|
|
<h3 id="_Padding_Options">Padding Options</h3>
|
|
|
|
<p id="_break-blocks">
|
|
<code class="title">--break-blocks / -f</code><br />
|
|
Pad empty lines around header blocks (e.g. '<code>if</code>', '<code>for</code>',
|
|
'<code>while</code>'...).</p>
|
|
<div class="code">
|
|
<pre>isFoo = true;
|
|
if (isFoo) <span class="brace">{</span>
|
|
bar();
|
|
<span class="brace">}</span> else <span class="brace">{</span>
|
|
anotherBar();
|
|
<span class="brace">}</span>
|
|
isBar = false;
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>isFoo = true;
|
|
|
|
if (isFoo) <span class="brace">{</span>
|
|
bar();
|
|
<span class="brace">}</span> else <span class="brace">{</span>
|
|
anotherBar();
|
|
<span class="brace">}</span>
|
|
|
|
isBar = false;
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_break-blocks=all">
|
|
<code class="title">--break-blocks=all / -F</code><br />
|
|
Pad empty lines around header blocks (e.g. '<code>if</code>', '<code>for</code>', '<code>while</code>'...). Treat
|
|
closing header blocks (e.g. '<code>else</code>', '<code>catch</code>') as stand-alone blocks.</p>
|
|
<div class="code">
|
|
<pre>isFoo = true;
|
|
if (isFoo) <span class="brace">{</span>
|
|
bar();
|
|
<span class="brace">}</span> else <span class="brace">{</span>
|
|
anotherBar();
|
|
<span class="brace">}</span>
|
|
isBar = false;
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>isFoo = true;
|
|
|
|
if (isFoo) <span class="brace">{</span>
|
|
bar();
|
|
|
|
<span class="brace">}</span> else <span class="brace">{</span>
|
|
anotherBar();
|
|
<span class="brace">}</span>
|
|
|
|
isBar = false;
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_pad-oper">
|
|
<code class="title">--pad-oper / -p </code><br />
|
|
Insert space padding around operators. This will also pad commas. 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.</p>
|
|
<div class="code">
|
|
<pre>if (foo==2)
|
|
a=bar((b-c)*a,d--);
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>if (foo == 2)
|
|
a = bar((b - c) * a, d--);
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_pad-comma">
|
|
<code class="title">--pad-comma / -xg </code><br />
|
|
Insert space padding after commas. This is not needed if pad-oper is used. 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.</p>
|
|
<div class="code">
|
|
<pre>if (isFoo(a,b)
|
|
bar(a,b);
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>if (isFoo(a, b)
|
|
bar(a, b);
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_pad-paren">
|
|
<code class="title">--pad-paren / -P </code>
|
|
<br />
|
|
Insert space padding around parenthesis on both the <strong>outside</strong> and the <strong>inside</strong>.
|
|
Any end of line comments will remain in the original column, if possible.</p>
|
|
<div class="code">
|
|
<pre>if (isFoo((a+2), b))
|
|
bar(a, b);
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>if ( isFoo ( ( a+2 ), b ) )
|
|
bar ( a, b );
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_pad-paren-out">
|
|
<code class="title">--pad-paren-out / -d </code>
|
|
<br />
|
|
Insert space padding around parenthesis on the <strong>outside</strong> only. Parentheses that are empty will
|
|
not be padded. 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.</p>
|
|
<div class="code">
|
|
<pre>if (isFoo((a+2), b))
|
|
bar(a, b);
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>if (isFoo ( (a+2), b) )
|
|
bar (a, b);
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_pad-first-paren-out">
|
|
<code class="title">--pad-first-paren-out / -xd </code>
|
|
<br />
|
|
Insert space padding around the <strong>first</strong> parenthesis in a series on the <strong>outside</strong>
|
|
only. Parentheses that are empty will not be padded. 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.</p>
|
|
<div class="code">
|
|
<pre>if (isFoo((a+2), b))
|
|
bar(a, b);
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>if (isFoo ((a+2), b))
|
|
bar (a, b);
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_pad-paren-in">
|
|
<code class="title">--pad-paren-in / -D </code>
|
|
<br />
|
|
Insert space padding around parenthesis on the <strong>inside</strong> 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.</p>
|
|
<div class="code">
|
|
<pre>if (isFoo((a+2), b))
|
|
bar(a, b);
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>if ( isFoo( ( a+2 ), b ) )
|
|
bar( a, b );
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_pad-header">
|
|
<code class="title">--pad-header / -H </code>
|
|
<br />
|
|
Insert space padding between a header (e.g. '<code>if</code>', '<code>for</code>', '<code>while</code>'...)
|
|
and the following paren. Any end of line comments will remain in the original column, if possible. This can
|
|
be used with unpad-paren to remove unwanted spaces.</p>
|
|
<div class="code">
|
|
<pre>if(isFoo((a+2), b))
|
|
bar(a, b);</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>if (isFoo((a+2), b))
|
|
bar(a, b);
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_unpad-paren">
|
|
<code class="title">--unpad-paren / -U </code>
|
|
<br />
|
|
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 <code>pad‑paren</code>,
|
|
<code>pad‑paren‑out</code>, <code>pad‑paren‑in</code>, and <code>pad‑header</code>
|
|
above. Only padding that has not been requested by other options will be removed.</p>
|
|
<p>
|
|
For example, if a source has parens padded on both the inside and outside, and you want inside only. You need
|
|
to use <code>unpad-paren</code> to remove the outside padding, and <code>pad‑paren‑in</code> to
|
|
retain the inside padding. Using only <code>pad‑paren‑in</code> would not remove the outside
|
|
padding.</p>
|
|
<div class="code">
|
|
<pre>if ( isFoo( ( a+2 ), b ) )
|
|
bar ( a, b );
|
|
</pre>
|
|
<p class="code">
|
|
becomes (with no padding option requested):</p>
|
|
<pre>if(isFoo((a+2), b))
|
|
bar(a, b);
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_delete-empty-lines">
|
|
<code class="title">--delete-empty-lines / -xe</code><br />
|
|
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.</p>
|
|
<div class="code">
|
|
<pre>void Foo()
|
|
<span class="brace">{</span>
|
|
|
|
foo1 = 1;
|
|
|
|
foo2 = 2;
|
|
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>void Foo()
|
|
<span class="brace">{</span>
|
|
foo1 = 1;
|
|
foo2 = 2;
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_fill-empty-lines">
|
|
<code class="title">--fill-empty-lines / -E</code><br />
|
|
Fill empty lines with the white space of the previous line.</p>
|
|
<p>
|
|
</p>
|
|
<p id="_align-pointer">
|
|
<code class="title">--align-pointer=type / -k1<br />
|
|
--align-pointer=middle / -k2<br />
|
|
--align-pointer=name / -k3
|
|
</code><br />
|
|
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.</p>
|
|
<div class="code">
|
|
<pre>char* foo1;
|
|
char & foo2;
|
|
String ^s1;</pre>
|
|
<p class="code">
|
|
becomes (with align-pointer=type):</p>
|
|
<pre>char* foo1;
|
|
char& foo2;
|
|
String^ s1;</pre>
|
|
</div>
|
|
<div class="code">
|
|
<pre>char* foo1;
|
|
char & foo2;
|
|
String ^s1;</pre>
|
|
<p class="code">
|
|
becomes (with align-pointer=middle):</p>
|
|
<pre>char * foo1;
|
|
char & foo2;
|
|
String ^ s1;</pre>
|
|
</div>
|
|
<div class="code">
|
|
<pre>char* foo1;
|
|
char & foo2;
|
|
String ^s1;</pre>
|
|
<p class="code">
|
|
becomes (with align-pointer=name):</p>
|
|
<pre>char *foo1;
|
|
char &foo2;
|
|
String ^s1;</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_align-reference">
|
|
<code class="title">--align-reference=none / -W0<br />
|
|
--align-reference=type / -W1<br />
|
|
--align-reference=middle / -W2<br />
|
|
--align-reference=name / -W3
|
|
</code><br />
|
|
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.</p>
|
|
<div class="code">
|
|
<pre>char &foo1;</pre>
|
|
<p class="code">
|
|
becomes (with align-reference=type):</p>
|
|
<pre>char& foo1;</pre>
|
|
</div>
|
|
<div class="code">
|
|
<pre>char& foo2;</pre>
|
|
<p class="code">
|
|
becomes (with align-reference=middle):</p>
|
|
<pre>char & foo2;</pre>
|
|
</div>
|
|
<div class="code">
|
|
<pre>char& foo3;</pre>
|
|
<p class="code">
|
|
becomes (with align-reference=name):</p>
|
|
<pre>char &foo3;</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
|
|
<!-- * * * * * * * * * * * * * Formatting Options * * * * * * * * * * * * * -->
|
|
|
|
<h3 id="_Formatting_Options">Formatting Options</h3>
|
|
|
|
<p id="_break-closing-brackets">
|
|
<code class="title">--break-closing-brackets / -y </code>
|
|
<br />
|
|
When used with --style=java, --style=kr, --style=stroustrup, --style=linux, or --style=1tbs, this breaks closing
|
|
headers (e.g. 'else', 'catch', ...) from their immediately preceding closing brackets. Closing header brackets
|
|
are always broken with the other styles.</p>
|
|
<div class="code">
|
|
<pre>void Foo(bool isFoo) <span class="brace">{</span>
|
|
if (isFoo) <span class="brace">{</span>
|
|
bar();
|
|
<span class="brace">}</span> else <span class="brace">{</span>
|
|
anotherBar();
|
|
<span class="brace">}</span>
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
<p class="code">
|
|
becomes (a broken 'else'):</p>
|
|
<pre>void Foo(bool isFoo) <span class="brace">{</span>
|
|
if (isFoo) <span class="brace">{</span>
|
|
bar();
|
|
<span class="brace">}</span>
|
|
else <span class="brace">{</span>
|
|
anotherBar();
|
|
<span class="brace">}</span>
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_break-elseifs">
|
|
<code class="title">--break-elseifs / -e</code><br />
|
|
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.</p>
|
|
<p>
|
|
If this option is NOT used, "else if" header combinations will be placed on a single line.</p>
|
|
<div class="code">
|
|
<pre>if (isFoo) <span class="brace">{</span>
|
|
bar();
|
|
<span class="brace">}</span>
|
|
else if (isFoo1()) <span class="brace">{</span>
|
|
bar1();
|
|
<span class="brace">}</span>
|
|
else if (isFoo2()) <span class="brace">{</span>
|
|
bar2;
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>if (isFoo) <span class="brace">{</span>
|
|
bar();
|
|
<span class="brace">}</span>
|
|
else
|
|
if (isFoo1()) <span class="brace">{</span>
|
|
bar1();
|
|
<span class="brace">}</span>
|
|
else
|
|
if (isFoo2()) <span class="brace">{</span>
|
|
bar2();
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_add-brackets">
|
|
<code class="title">--add-brackets / -j </code>
|
|
<br />
|
|
Add brackets to unbracketed one line conditional statements (e.g. '<code>if</code>', '<code>for</code>',
|
|
'<code>while</code>'...). 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.</p>
|
|
<div class="code">
|
|
<pre>if (isFoo)
|
|
isFoo = false;
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>if (isFoo) <span class="brace">{</span>
|
|
isFoo = false;
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_add-one-line-brackets">
|
|
<code class="title">--add-one-line-brackets / -J </code>
|
|
<br />
|
|
Add one line brackets to unbracketed one line conditional statements (e.g. '<code>if</code>', '<code>for</code>',
|
|
'<code>while</code>'...). The statement must be on a single line. The option implies --keep-one-line-blocks and
|
|
will not break the one line blocks.</p>
|
|
<div class="code">
|
|
<pre>if (isFoo)
|
|
isFoo = false;
|
|
</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>if (isFoo)
|
|
<span class="brace">{</span> isFoo = false; <span class="brace">}</span>
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_remove-brackets">
|
|
<code class="title">--remove-brackets / -xj</code><br />
|
|
Remove brackets from conditional statements (e.g. '<code>if</code>', '<code>for</code>', '<code>while</code>'...).
|
|
The statement must be a single statement on a single line. If --add-brackets or --add-one-line-brackets is also
|
|
used the result will be to add brackets. Brackets will not be removed from "One True Brace Style",
|
|
--style=1tbs.</p>
|
|
<div class="code">
|
|
<pre>if (isFoo)
|
|
<span class="brace">{</span>
|
|
isFoo = false;
|
|
<span class="brace">}</span></pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>if (isFoo)
|
|
isFoo = false;
|
|
</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_keep-one-line-blocks">
|
|
<code class="title">--keep-one-line-blocks / -O </code>
|
|
<br />
|
|
Don't break one-line blocks.</p>
|
|
<div class="code">
|
|
<pre>if (isFoo)
|
|
<span class="brace">{</span> isFoo = false; cout << isFoo << endl; <span class="brace">}</span>
|
|
</pre>
|
|
<p class="code">
|
|
remains unchanged.</p>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_keep-one-line-statements">
|
|
<code class="title">--keep-one-line-statements / -o </code>
|
|
<br />
|
|
Don't break complex statements and multiple statements residing on a single line.</p>
|
|
<div class="code">
|
|
<pre>if (isFoo)
|
|
<span class="brace">{</span>
|
|
isFoo = false; cout << isFoo << endl;
|
|
<span class="brace">}</span>
|
|
</pre>
|
|
<p class="code">
|
|
remains unchanged.</p>
|
|
<pre>if (isFoo) DoBar();
|
|
</pre>
|
|
<p class="code">
|
|
remains unchanged.</p>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_convert-tabs">
|
|
<code class="title">--convert-tabs / -c</code><br />
|
|
Converts tabs into 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.</p>
|
|
<p>
|
|
</p>
|
|
<p id="_close-templates">
|
|
<code class="title">--close-templates / -xy</code><br />
|
|
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.</p>
|
|
<div class="code">
|
|
<pre>Stack< int,List< int > > stack1;</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>Stack<int,List<int>> stack1;</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_remove-comment-prefix">
|
|
<code class="title">--remove-comment-prefix / -xp</code><br />
|
|
Remove the preceding '*' in a multi-line comment that begins a line. A trailing '*', if present, is also removed.
|
|
Text that is less than one indent is indented to one indent. Text greater than one indent is not changed. Multi-line
|
|
comments that begin a line but without the preceding '*' are indented to one indent for consistency. This can
|
|
slightly modify the indentation of commented out blocks of code. Lines containing all '*' are left unchanged.
|
|
Extra spacing is removed from the comment close '*/'.</p>
|
|
<div class="code">
|
|
<pre><em>/*
|
|
* comment line 1
|
|
* comment line 2
|
|
*/</em></pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre><em>/*
|
|
comment line 1
|
|
comment line 2
|
|
*/</em></pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_max-code-length">
|
|
<code class="title">--max-code-length=<span class="option">#</span> / -xC<span class="option">#</span>
|
|
<br />
|
|
--break-after-logical / -xL</code><br />
|
|
The option max‑code‑length will break a line if the code exceeds <span class="option"><strong>#</strong></span>
|
|
characters. The valid values are 50 thru 200. Lines without logical conditionals will break on a logical conditional
|
|
(||, &&, ...), comma, paren, semicolon, or space.</p>
|
|
<p>
|
|
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.</p>
|
|
<p>
|
|
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.</p>
|
|
<div class="code">
|
|
<pre>if (thisVariable1 == thatVariable1 || thisVariable2 == thatVariable2 || thisVariable3 == thatVariable3)
|
|
bar();</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>if (thisVariable1 == thatVariable1
|
|
|| thisVariable2 == thatVariable2
|
|
|| thisVariable3 == thatVariable3)
|
|
bar();</pre>
|
|
<p class="code">
|
|
becomes (with break‑after‑logical):</p>
|
|
<pre>if (thisVariable1 == thatVariable1 ||
|
|
thisVariable2 == thatVariable2 ||
|
|
thisVariable3 == thatVariable3)
|
|
bar();</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_mode">
|
|
<code class="title">--mode=c</code><br />
|
|
<code class="title">--mode=cs</code><br />
|
|
<code class="title">--mode=java</code><br />
|
|
Indent a C type, C#, or Java file. C type files are C, C++, C++/CLI, and Objective-C. 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.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
|
|
<!-- * * * * * * * * * * * * * Objective-C Options * * * * * * * * * * * * * -->
|
|
|
|
<h3 id="_Objective_C_Options">Objective‑C Options</h3>
|
|
|
|
<p>
|
|
These options are effective for Objective‑C files only. The paren padding options will still apply to the
|
|
Objective-C method prefix and return type unless overridden by the following options.</p>
|
|
<p>
|
|
Because of the longer indents sometimes needed for Objective‑C, the option "max-instatement-indent" may
|
|
need to be increased. If you are not getting the paren and square bracket alignment you want try increasing this
|
|
value. The option is described in the "Indentation Options" section.</p>
|
|
<p id="_pad-method-prefix">
|
|
<code class="title">--pad-method-prefix / -xQ</code><br />
|
|
Insert space padding <strong>after</strong> the '-' or '+' Objective‑C method prefix. This will add
|
|
exactly one space. Any additional spaces will be deleted. This option takes precedence over the pad-paren
|
|
options.</p>
|
|
<div class="code">
|
|
<pre>-(void)foo1;
|
|
+(void)foo2;</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>- (void)foo1;
|
|
+ (void)foo2;</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_unpad-method-prefix">
|
|
<code class="title">--unpad-method-prefix / -xR</code><br />
|
|
Remove all space padding <strong>after</strong> the '-' or '+' Objective‑C method prefix.
|
|
This option will be ignored if used with pad‑method‑prefix. It takes precedence over the pad-paren
|
|
options.</p>
|
|
<div class="code">
|
|
<pre>- (void)foo1;
|
|
+ (void)foo2;</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>-(void)foo1;
|
|
+(void)foo2;</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_pad-return-type">
|
|
<code class="title">--pad-return-type / -xq</code><br />
|
|
Insert space padding <strong>after</strong> the Objective‑C return type. This will add exactly one
|
|
space. Any additional spaces will be deleted. This option takes precedence over the pad-paren options.</p>
|
|
<div class="code">
|
|
<pre>-(void)foo1;
|
|
+(void)foo2;</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>-(void) foo1;
|
|
+(void) foo2;</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_unpad-return-type">
|
|
<code class="title">--unpad-return-type / -xr</code><br />
|
|
Remove all space padding <strong>after</strong> the Objective‑C return type. This option
|
|
will be ignored if used with pad‑return‑type. It takes precedence over the pad-paren options.</p>
|
|
<div class="code">
|
|
<pre>-(void) foo1;
|
|
+(void) foo2;</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>-(void)foo1;
|
|
+(void)foo2;</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_align-method-colon">
|
|
<code class="title">--align-method-colon / -xM</code><br />
|
|
Align the colons in Objective‑C method declarations.</p>
|
|
<div class="code">
|
|
<pre>-(void)deleteKey:(id)key
|
|
atIndex:(int)index
|
|
ofNode:(Node*)node;</pre>
|
|
<p class="code">
|
|
becomes:</p>
|
|
<pre>-(void)deleteKey:(id)key
|
|
atIndex:(int)index
|
|
ofNode:(Node*)node;</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<p id="_pad-method-colon">
|
|
<code class="title">--pad-method-colon=none / -xP0<br />
|
|
--pad-method-colon=all / -xP1<br />
|
|
--pad-method-colon=after / -xP2<br />
|
|
--pad-method-colon=before / -xP3
|
|
</code><br />
|
|
Add or remove space padding before or after the colons in an Objective‑C method call. These options will
|
|
pad exactly one space. Any additional spaces will be deleted.</p>
|
|
<div class="code">
|
|
<p class="code">
|
|
with pad-method-colon=none:</p>
|
|
<pre>[node insertKey:key];</pre>
|
|
<p class="code">
|
|
with pad-method-colon=all:</p>
|
|
<pre>[node insertKey : key];</pre>
|
|
<p class="code">
|
|
with pad-method-colon=after:</p>
|
|
<pre>[node insertKey: key];</pre>
|
|
<p class="code">
|
|
with pad-method-colon=before:</p>
|
|
<pre>[node insertKey :key];</pre>
|
|
</div>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
|
|
<!-- * * * * * * * * * * * * Other Command Line Options * * * * * * * * * * * * -->
|
|
|
|
<h3 id="_Other_Options">Other Options</h3>
|
|
|
|
<p>
|
|
These are non-formatting options available for the command-line. They can also be included in an options
|
|
file.</p>
|
|
|
|
<p id="_suffix">
|
|
<code class="title">--suffix=<span class="option">####</span></code><br />
|
|
Append the suffix #### instead of '.orig' to original file name (e.g. <code>--suffix=<span class="option">.bak</span></code>).
|
|
If this is to be a file extension, the dot '.' must be included. Otherwise the suffix will be appended to the
|
|
current file extension.</p>
|
|
<p id="_suffix=none">
|
|
<code class="title">--suffix=none / -n</code><br />
|
|
Do not retain a backup of the original file. The original file is purged after it is formatted.</p>
|
|
<p id="_recursive">
|
|
<code class="title">--recursive / -r / -R</code><br />
|
|
For each directory in the command line, process all subdirectories recursively. When using the recursive option
|
|
the file name statement should contain a wildcard. Linux users should place the file path and name in double quotes
|
|
so the shell will not resolve the wildcards (e.g. "$HOME/src/*.cpp"). Windows users should place the file path
|
|
and name in double quotes if the path or name contains spaces.</p>
|
|
<p id="_dry-run">
|
|
<code class="title">--dry-run</code><br />
|
|
Perform a trial run with no changes made to the files. The report will be output as usual.</p>
|
|
<p id="_exclude">
|
|
<code class="title">--exclude=<span class="option">####</span></code><br />
|
|
Specify a file or sub directory #### to be excluded from processing.</p>
|
|
<p>
|
|
Excludes are matched from the end of the file path. 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.</p>
|
|
<p>
|
|
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.</p>
|
|
<p>
|
|
Wildcards are NOT allowed. There may be more than one exclude statement. The file path and name may be placed
|
|
in double quotes (e.g. ‑‑exclude="foo bar.cpp").</p>
|
|
<p id="_ignore-exclude-errors">
|
|
<code class="title">--ignore-exclude-errors / -i</code><br />
|
|
Allow processing to continue if there are errors in the "exclude=###" options.<br />
|
|
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.</p>
|
|
<p id="_ignore-exclude-errors-x">
|
|
<code class="title">--ignore-exclude-errors-x / -xi</code><br />
|
|
<code class="title"></code>Allow processing to continue if there are errors in the "exclude=###" options.<br />
|
|
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.</p>
|
|
<p id="_errors-to-stdout">
|
|
<code class="title">--errors-to-stdout / -X</code><br />
|
|
Print errors to standard-output rather than to standard-error.<br />
|
|
This option should be helpful for systems/shells that do not have a separate output to standard-error, such as
|
|
in Windows95.</p>
|
|
<p id="_preserve-date">
|
|
<code class="title">--preserve-date / -Z</code><br />
|
|
Preserve the original file's date and time modified. The time modified will be changed a few micro seconds to
|
|
force the changed files to compile. This option is not effective if redirection is used to rename the input
|
|
file.</p>
|
|
<p id="_verbose">
|
|
<code class="title">--verbose / -v</code><br />
|
|
Verbose display mode. Display optional information, such as release number, date, and statistical data.</p>
|
|
<p id="_formatted">
|
|
<code class="title">--formatted / -Q</code><br />
|
|
Formatted files display mode. Display only the files that have been formatted. Do not display files that
|
|
are unchanged.</p>
|
|
<p id="_quiet">
|
|
<code class="title">--quiet / -q</code><br />
|
|
Quiet display mode. Suppress all output except error messages.</p>
|
|
<p id="_lineend">
|
|
<code class="title">--lineend=windows / -z1<br />
|
|
--lineend=linux / -z2<br />
|
|
--lineend=macold / -z3
|
|
</code><br />
|
|
Force use of the specified line end style. Valid options are windows (CRLF), linux (LF), and macold (CR). MacOld
|
|
style is the format for Mac OS 9 and earlier. 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.</p>
|
|
<p>
|
|
When <strong>redirection</strong> is used on Windows the output will always have Windows line ends. This option
|
|
will be ignored.</p>
|
|
<p>
|
|
</p>
|
|
<hr style="margin-left: -0.4in;" />
|
|
|
|
<!-- * * * * * * * * * * * * Command-Line Options * * * * * * * * * * * * -->
|
|
|
|
<h3 id="_Command_Line_Only">Command Line Only</h3>
|
|
|
|
<p>These options are available for the command-line only. They are NOT available in an options file.</p>
|
|
<p id="_options=">
|
|
<code class="title">--options=<span class="option">####</span></code><br />
|
|
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.</p>
|
|
<p id="_options=none">
|
|
<code class="title">--options=none</code><br />
|
|
Disable the default options file. Only the command-line parameters will be used.</p>
|
|
<p id="_ascii">
|
|
<code class="title">--ascii / -I</code><br />
|
|
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.</p>
|
|
<p id="_version">
|
|
<code class="title">--version / -V</code><br />
|
|
Print version number and quit. The short option must be by itself, it cannot be concatenated with other
|
|
options.</p>
|
|
<p id="_help">
|
|
<code class="title">--help / -h / -?</code><br />
|
|
Print a help message and quit. The short option must be by itself, it cannot be concatenated with other
|
|
options.</p>
|
|
<p id="_html">
|
|
<code class="title">--html / -!</code><br />
|
|
Open the HTML help
|
|
file "astyle.html" in the default browser and quit. The short option must be by itself, it
|
|
cannot be concatenated with other options. The documentation must be installed in the standard install path (/usr/share/doc/astyle/html
|
|
for Linux or %PROGRAMFILES%\AStyle\doc for Windows). If installed to a different path use html=###.</p>
|
|
<p id="_html=">
|
|
<code class="title">--html=<span class="option">####</span></code><br />
|
|
Open a HTML help file in the default browser using the file path #### and quit. A HTML file other than "astyle.help"
|
|
may be specified. The path may include a directory path and a file name, or a file name only (e.g. html=install.html).
|
|
If only a file name is used it is assumed to be in the standard install path (/usr/share/doc/astyle/html
|
|
for Linux or %PROGRAMFILES%\AStyle\doc for Windows). In both cases the file name must include the html extension.
|
|
File paths containing spaces must be enclosed in quotes.</p>
|
|
<p>
|
|
On Linux the HTML file is opened using the script "xdg-open" from the install package "xdg-utils". This should
|
|
be installed by default on most distributions.</p>
|
|
<p>
|
|
Any HTML file can be opened by this option. The files you are likely to need are astyle.html (the default), install.html,
|
|
and index.html.</p>
|
|
<p>
|
|
</p>
|
|
<hr style="margin-left: -0.4in;" />
|
|
|
|
<p style="margin-left: -0.4in; text-align: center;">
|
|
<a href="http://sourceforge.net/projects/astyle">
|
|
<img src="http://sflogo.sourceforge.net/sflogo.php?group_id=2319&type=16" alt="" />
|
|
</a></p>
|
|
|
|
<p>
|
|
</p>
|
|
<p>
|
|
</p>
|
|
|
|
</body>
|
|
|
|
</html>
|
|
|