forked from OSchip/llvm-project
876 lines
27 KiB
ReStructuredText
876 lines
27 KiB
ReStructuredText
==========================
|
|
Clang-Format Style Options
|
|
==========================
|
|
|
|
:doc:`ClangFormatStyleOptions` describes configurable formatting style options
|
|
supported by :doc:`LibFormat` and :doc:`ClangFormat`.
|
|
|
|
When using :program:`clang-format` command line utility or
|
|
``clang::format::reformat(...)`` functions from code, one can either use one of
|
|
the predefined styles (LLVM, Google, Chromium, Mozilla, WebKit) or create a
|
|
custom style by configuring specific style options.
|
|
|
|
|
|
Configuring Style with clang-format
|
|
===================================
|
|
|
|
:program:`clang-format` supports two ways to provide custom style options:
|
|
directly specify style configuration in the ``-style=`` command line option or
|
|
use ``-style=file`` and put style configuration in the ``.clang-format`` or
|
|
``_clang-format`` file in the project directory.
|
|
|
|
When using ``-style=file``, :program:`clang-format` for each input file will
|
|
try to find the ``.clang-format`` file located in the closest parent directory
|
|
of the input file. When the standard input is used, the search is started from
|
|
the current directory.
|
|
|
|
The ``.clang-format`` file uses YAML format:
|
|
|
|
.. code-block:: yaml
|
|
|
|
key1: value1
|
|
key2: value2
|
|
# A comment.
|
|
...
|
|
|
|
The configuration file can consist of several sections each having different
|
|
``Language:`` parameter denoting the programming language this section of the
|
|
configuration is targeted at. See the description of the **Language** option
|
|
below for the list of supported languages. The first section may have no
|
|
language set, it will set the default style options for all lanugages.
|
|
Configuration sections for specific language will override options set in the
|
|
default section.
|
|
|
|
When :program:`clang-format` formats a file, it auto-detects the language using
|
|
the file name. When formatting standard input or a file that doesn't have the
|
|
extension corresponding to its language, ``-assume-filename=`` option can be
|
|
used to override the file name :program:`clang-format` uses to detect the
|
|
language.
|
|
|
|
An example of a configuration file for multiple languages:
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
# We'll use defaults from the LLVM style, but with 4 columns indentation.
|
|
BasedOnStyle: LLVM
|
|
IndentWidth: 4
|
|
---
|
|
Language: Cpp
|
|
# Force pointers to the type for C++.
|
|
DerivePointerAlignment: false
|
|
PointerAlignment: Left
|
|
---
|
|
Language: JavaScript
|
|
# Use 100 columns for JS.
|
|
ColumnLimit: 100
|
|
---
|
|
Language: Proto
|
|
# Don't format .proto files.
|
|
DisableFormat: true
|
|
...
|
|
|
|
An easy way to get a valid ``.clang-format`` file containing all configuration
|
|
options of a certain predefined style is:
|
|
|
|
.. code-block:: console
|
|
|
|
clang-format -style=llvm -dump-config > .clang-format
|
|
|
|
When specifying configuration in the ``-style=`` option, the same configuration
|
|
is applied for all input files. The format of the configuration is:
|
|
|
|
.. code-block:: console
|
|
|
|
-style='{key1: value1, key2: value2, ...}'
|
|
|
|
|
|
Disabling Formatting on a Piece of Code
|
|
=======================================
|
|
|
|
Clang-format understands also special comments that switch formatting in a
|
|
delimited range. The code between a comment ``// clang-format off`` or
|
|
``/* clang-format off */`` up to a comment ``// clang-format on`` or
|
|
``/* clang-format on */`` will not be formatted. The comments themselves
|
|
will be formatted (aligned) normally.
|
|
|
|
.. code-block:: c++
|
|
|
|
int formatted_code;
|
|
// clang-format off
|
|
void unformatted_code ;
|
|
// clang-format on
|
|
void formatted_code_again;
|
|
|
|
|
|
Configuring Style in Code
|
|
=========================
|
|
|
|
When using ``clang::format::reformat(...)`` functions, the format is specified
|
|
by supplying the `clang::format::FormatStyle
|
|
<http://clang.llvm.org/doxygen/structclang_1_1format_1_1FormatStyle.html>`_
|
|
structure.
|
|
|
|
|
|
Configurable Format Style Options
|
|
=================================
|
|
|
|
This section lists the supported style options. Value type is specified for
|
|
each option. For enumeration types possible values are specified both as a C++
|
|
enumeration member (with a prefix, e.g. ``LS_Auto``), and as a value usable in
|
|
the configuration (without a prefix: ``Auto``).
|
|
|
|
|
|
**BasedOnStyle** (``string``)
|
|
The style used for all options not specifically set in the configuration.
|
|
|
|
This option is supported only in the :program:`clang-format` configuration
|
|
(both within ``-style='{...}'`` and the ``.clang-format`` file).
|
|
|
|
Possible values:
|
|
|
|
* ``LLVM``
|
|
A style complying with the `LLVM coding standards
|
|
<http://llvm.org/docs/CodingStandards.html>`_
|
|
* ``Google``
|
|
A style complying with `Google's C++ style guide
|
|
<http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml>`_
|
|
* ``Chromium``
|
|
A style complying with `Chromium's style guide
|
|
<http://www.chromium.org/developers/coding-style>`_
|
|
* ``Mozilla``
|
|
A style complying with `Mozilla's style guide
|
|
<https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style>`_
|
|
* ``WebKit``
|
|
A style complying with `WebKit's style guide
|
|
<http://www.webkit.org/coding/coding-style.html>`_
|
|
|
|
.. START_FORMAT_STYLE_OPTIONS
|
|
|
|
**AccessModifierOffset** (``int``)
|
|
The extra indent or outdent of access modifiers, e.g. ``public:``.
|
|
|
|
**AlignAfterOpenBracket** (``BracketAlignmentStyle``)
|
|
If ``true``, horizontally aligns arguments after an open bracket.
|
|
|
|
This applies to round brackets (parentheses), angle brackets and square
|
|
brackets.
|
|
|
|
Possible values:
|
|
|
|
* ``BAS_Align`` (in configuration: ``Align``)
|
|
Align parameters on the open bracket, e.g.:
|
|
|
|
.. code-block:: c++
|
|
|
|
someLongFunction(argument1,
|
|
argument2);
|
|
|
|
* ``BAS_DontAlign`` (in configuration: ``DontAlign``)
|
|
Don't align, instead use ``ContinuationIndentWidth``, e.g.:
|
|
|
|
.. code-block:: c++
|
|
|
|
someLongFunction(argument1,
|
|
argument2);
|
|
|
|
* ``BAS_AlwaysBreak`` (in configuration: ``AlwaysBreak``)
|
|
Always break after an open bracket, if the parameters don't fit
|
|
on a single line, e.g.:
|
|
|
|
.. code-block:: c++
|
|
|
|
someLongFunction(
|
|
argument1, argument2);
|
|
|
|
|
|
|
|
**AlignConsecutiveAssignments** (``bool``)
|
|
If ``true``, aligns consecutive assignments.
|
|
|
|
This will align the assignment operators of consecutive lines. This
|
|
will result in formattings like
|
|
|
|
.. code-block:: c++
|
|
|
|
int aaaa = 12;
|
|
int b = 23;
|
|
int ccc = 23;
|
|
|
|
**AlignConsecutiveDeclarations** (``bool``)
|
|
If ``true``, aligns consecutive declarations.
|
|
|
|
This will align the declaration names of consecutive lines. This
|
|
will result in formattings like
|
|
|
|
.. code-block:: c++
|
|
|
|
int aaaa = 12;
|
|
float b = 23;
|
|
std::string ccc = 23;
|
|
|
|
**AlignEscapedNewlinesLeft** (``bool``)
|
|
If ``true``, aligns escaped newlines as far left as possible.
|
|
Otherwise puts them into the right-most column.
|
|
|
|
**AlignOperands** (``bool``)
|
|
If ``true``, horizontally align operands of binary and ternary
|
|
expressions.
|
|
|
|
Specifically, this aligns operands of a single expression that needs to be
|
|
split over multiple lines, e.g.:
|
|
|
|
.. code-block:: c++
|
|
|
|
int aaa = bbbbbbbbbbbbbbb +
|
|
ccccccccccccccc;
|
|
|
|
**AlignTrailingComments** (``bool``)
|
|
If ``true``, aligns trailing comments.
|
|
|
|
**AllowAllParametersOfDeclarationOnNextLine** (``bool``)
|
|
Allow putting all parameters of a function declaration onto
|
|
the next line even if ``BinPackParameters`` is ``false``.
|
|
|
|
**AllowShortBlocksOnASingleLine** (``bool``)
|
|
Allows contracting simple braced statements to a single line.
|
|
|
|
E.g., this allows ``if (a) { return; }`` to be put on a single line.
|
|
|
|
**AllowShortCaseLabelsOnASingleLine** (``bool``)
|
|
If ``true``, short case labels will be contracted to a single line.
|
|
|
|
**AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``)
|
|
Dependent on the value, ``int f() { return 0; }`` can be put on a
|
|
single line.
|
|
|
|
Possible values:
|
|
|
|
* ``SFS_None`` (in configuration: ``None``)
|
|
Never merge functions into a single line.
|
|
|
|
* ``SFS_Empty`` (in configuration: ``Empty``)
|
|
Only merge empty functions.
|
|
|
|
* ``SFS_Inline`` (in configuration: ``Inline``)
|
|
Only merge functions defined inside a class. Implies "empty".
|
|
|
|
* ``SFS_All`` (in configuration: ``All``)
|
|
Merge all functions fitting on a single line.
|
|
|
|
|
|
|
|
**AllowShortIfStatementsOnASingleLine** (``bool``)
|
|
If ``true``, ``if (a) return;`` can be put on a single line.
|
|
|
|
**AllowShortLoopsOnASingleLine** (``bool``)
|
|
If ``true``, ``while (true) continue;`` can be put on a single
|
|
line.
|
|
|
|
**AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``)
|
|
The function definition return type breaking style to use. This
|
|
option is deprecated and is retained for backwards compatibility.
|
|
|
|
Possible values:
|
|
|
|
* ``DRTBS_None`` (in configuration: ``None``)
|
|
Break after return type automatically.
|
|
``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
|
|
|
|
* ``DRTBS_All`` (in configuration: ``All``)
|
|
Always break after the return type.
|
|
|
|
* ``DRTBS_TopLevel`` (in configuration: ``TopLevel``)
|
|
Always break after the return types of top-level functions.
|
|
|
|
|
|
|
|
**AlwaysBreakAfterReturnType** (``ReturnTypeBreakingStyle``)
|
|
The function declaration return type breaking style to use.
|
|
|
|
Possible values:
|
|
|
|
* ``RTBS_None`` (in configuration: ``None``)
|
|
Break after return type automatically.
|
|
``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
|
|
|
|
* ``RTBS_All`` (in configuration: ``All``)
|
|
Always break after the return type.
|
|
|
|
* ``RTBS_TopLevel`` (in configuration: ``TopLevel``)
|
|
Always break after the return types of top-level functions.
|
|
|
|
* ``RTBS_AllDefinitions`` (in configuration: ``AllDefinitions``)
|
|
Always break after the return type of function definitions.
|
|
|
|
* ``RTBS_TopLevelDefinitions`` (in configuration: ``TopLevelDefinitions``)
|
|
Always break after the return type of top-level definitions.
|
|
|
|
|
|
|
|
**AlwaysBreakBeforeMultilineStrings** (``bool``)
|
|
If ``true``, always break before multiline string literals.
|
|
|
|
This flag is mean to make cases where there are multiple multiline strings
|
|
in a file look more consistent. Thus, it will only take effect if wrapping
|
|
the string at that point leads to it being indented
|
|
``ContinuationIndentWidth`` spaces from the start of the line.
|
|
|
|
**AlwaysBreakTemplateDeclarations** (``bool``)
|
|
If ``true``, always break after the ``template<...>`` of a template
|
|
declaration.
|
|
|
|
**BinPackArguments** (``bool``)
|
|
If ``false``, a function call's arguments will either be all on the
|
|
same line or will have one line each.
|
|
|
|
**BinPackParameters** (``bool``)
|
|
If ``false``, a function declaration's or function definition's
|
|
parameters will either all be on the same line or will have one line each.
|
|
|
|
**BraceWrapping** (``BraceWrappingFlags``)
|
|
Control of individual brace wrapping cases.
|
|
|
|
If ``BreakBeforeBraces`` is set to ``BS_Custom``, use this to specify how
|
|
each individual brace case should be handled. Otherwise, this is ignored.
|
|
|
|
Nested configuration flags:
|
|
|
|
* ``bool AfterClass`` Wrap class definitions.
|
|
* ``bool AfterControlStatement`` Wrap control statements (``if``/``for``/``while``/``switch``/..).
|
|
* ``bool AfterEnum`` Wrap enum definitions.
|
|
* ``bool AfterFunction`` Wrap function definitions.
|
|
* ``bool AfterNamespace`` Wrap namespace definitions.
|
|
* ``bool AfterObjCDeclaration`` Wrap ObjC definitions (``@autoreleasepool``, interfaces, ..).
|
|
* ``bool AfterStruct`` Wrap struct definitions.
|
|
* ``bool AfterUnion`` Wrap union definitions.
|
|
* ``bool BeforeCatch`` Wrap before ``catch``.
|
|
* ``bool BeforeElse`` Wrap before ``else``.
|
|
* ``bool IndentBraces`` Indent the wrapped braces themselves.
|
|
|
|
|
|
**BreakAfterJavaFieldAnnotations** (``bool``)
|
|
Break after each annotation on a field in Java files.
|
|
|
|
**BreakBeforeBinaryOperators** (``BinaryOperatorStyle``)
|
|
The way to wrap binary operators.
|
|
|
|
Possible values:
|
|
|
|
* ``BOS_None`` (in configuration: ``None``)
|
|
Break after operators.
|
|
|
|
* ``BOS_NonAssignment`` (in configuration: ``NonAssignment``)
|
|
Break before operators that aren't assignments.
|
|
|
|
* ``BOS_All`` (in configuration: ``All``)
|
|
Break before operators.
|
|
|
|
|
|
|
|
**BreakBeforeBraces** (``BraceBreakingStyle``)
|
|
The brace breaking style to use.
|
|
|
|
Possible values:
|
|
|
|
* ``BS_Attach`` (in configuration: ``Attach``)
|
|
Always attach braces to surrounding context.
|
|
|
|
* ``BS_Linux`` (in configuration: ``Linux``)
|
|
Like ``Attach``, but break before braces on function, namespace and
|
|
class definitions.
|
|
|
|
* ``BS_Mozilla`` (in configuration: ``Mozilla``)
|
|
Like ``Attach``, but break before braces on enum, function, and record
|
|
definitions.
|
|
|
|
* ``BS_Stroustrup`` (in configuration: ``Stroustrup``)
|
|
Like ``Attach``, but break before function definitions, ``catch``, and
|
|
``else``.
|
|
|
|
* ``BS_Allman`` (in configuration: ``Allman``)
|
|
Always break before braces.
|
|
|
|
* ``BS_GNU`` (in configuration: ``GNU``)
|
|
Always break before braces and add an extra level of indentation to
|
|
braces of control statements, not to those of class, function
|
|
or other definitions.
|
|
|
|
* ``BS_WebKit`` (in configuration: ``WebKit``)
|
|
Like ``Attach``, but break before functions.
|
|
|
|
* ``BS_Custom`` (in configuration: ``Custom``)
|
|
Configure each individual brace in `BraceWrapping`.
|
|
|
|
|
|
|
|
**BreakBeforeTernaryOperators** (``bool``)
|
|
If ``true``, ternary operators will be placed after line breaks.
|
|
|
|
**BreakConstructorInitializersBeforeComma** (``bool``)
|
|
Always break constructor initializers before commas and align
|
|
the commas with the colon.
|
|
|
|
**BreakStringLiterals** (``bool``)
|
|
Allow breaking string literals when formatting.
|
|
|
|
**ColumnLimit** (``unsigned``)
|
|
The column limit.
|
|
|
|
A column limit of ``0`` means that there is no column limit. In this case,
|
|
clang-format will respect the input's line breaking decisions within
|
|
statements unless they contradict other rules.
|
|
|
|
**CommentPragmas** (``std::string``)
|
|
A regular expression that describes comments with special meaning,
|
|
which should not be split into lines or otherwise changed.
|
|
|
|
**ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``)
|
|
If the constructor initializers don't fit on a line, put each
|
|
initializer on its own line.
|
|
|
|
**ConstructorInitializerIndentWidth** (``unsigned``)
|
|
The number of characters to use for indentation of constructor
|
|
initializer lists.
|
|
|
|
**ContinuationIndentWidth** (``unsigned``)
|
|
Indent width for line continuations.
|
|
|
|
**Cpp11BracedListStyle** (``bool``)
|
|
If ``true``, format braced lists as best suited for C++11 braced
|
|
lists.
|
|
|
|
Important differences:
|
|
- No spaces inside the braced list.
|
|
- No line break before the closing brace.
|
|
- Indentation with the continuation indent, not with the block indent.
|
|
|
|
Fundamentally, C++11 braced lists are formatted exactly like function
|
|
calls would be formatted in their place. If the braced list follows a name
|
|
(e.g. a type or variable name), clang-format formats as if the ``{}`` were
|
|
the parentheses of a function call with that name. If there is no name,
|
|
a zero-length name is assumed.
|
|
|
|
**DerivePointerAlignment** (``bool``)
|
|
If ``true``, analyze the formatted file for the most common
|
|
alignment of ``&`` and ``\*``. ``PointerAlignment`` is then used only as
|
|
fallback.
|
|
|
|
**DisableFormat** (``bool``)
|
|
Disables formatting completely.
|
|
|
|
**ExperimentalAutoDetectBinPacking** (``bool``)
|
|
If ``true``, clang-format detects whether function calls and
|
|
definitions are formatted with one parameter per line.
|
|
|
|
Each call can be bin-packed, one-per-line or inconclusive. If it is
|
|
inconclusive, e.g. completely on one line, but a decision needs to be
|
|
made, clang-format analyzes whether there are other bin-packed cases in
|
|
the input file and act accordingly.
|
|
|
|
NOTE: This is an experimental flag, that might go away or be renamed. Do
|
|
not use this in config files, etc. Use at your own risk.
|
|
|
|
**ForEachMacros** (``std::vector<std::string>``)
|
|
A vector of macros that should be interpreted as foreach loops
|
|
instead of as function calls.
|
|
|
|
These are expected to be macros of the form:
|
|
|
|
.. code-block:: c++
|
|
|
|
FOREACH(<variable-declaration>, ...)
|
|
<loop-body>
|
|
|
|
In the .clang-format configuration file, this can be configured like:
|
|
|
|
.. code-block:: yaml
|
|
|
|
ForEachMacros: ['RANGES_FOR', 'FOREACH']
|
|
|
|
For example: BOOST_FOREACH.
|
|
|
|
**IncludeCategories** (``std::vector<IncludeCategory>``)
|
|
Regular expressions denoting the different ``#include`` categories
|
|
used for ordering ``#includes``.
|
|
|
|
These regular expressions are matched against the filename of an include
|
|
(including the <> or "") in order. The value belonging to the first
|
|
matching regular expression is assigned and ``#includes`` are sorted first
|
|
according to increasing category number and then alphabetically within
|
|
each category.
|
|
|
|
If none of the regular expressions match, INT_MAX is assigned as
|
|
category. The main header for a source file automatically gets category 0.
|
|
so that it is generally kept at the beginning of the ``#includes``
|
|
(http://llvm.org/docs/CodingStandards.html#include-style). However, you
|
|
can also assign negative priorities if you have certain headers that
|
|
always need to be first.
|
|
|
|
To configure this in the .clang-format file, use:
|
|
|
|
.. code-block:: yaml
|
|
|
|
IncludeCategories:
|
|
- Regex: '^"(llvm|llvm-c|clang|clang-c)/'
|
|
Priority: 2
|
|
- Regex: '^(<|"(gtest|isl|json)/)'
|
|
Priority: 3
|
|
- Regex: '.\*'
|
|
Priority: 1
|
|
|
|
**IncludeIsMainRegex** (``std::string``)
|
|
Specify a regular expression of suffixes that are allowed in the
|
|
file-to-main-include mapping.
|
|
|
|
When guessing whether a #include is the "main" include (to assign
|
|
category 0, see above), use this regex of allowed suffixes to the header
|
|
stem. A partial match is done, so that:
|
|
- "" means "arbitrary suffix"
|
|
- "$" means "no suffix"
|
|
|
|
For example, if configured to "(_test)?$", then a header a.h would be seen
|
|
as the "main" include in both a.cc and a_test.cc.
|
|
|
|
**IndentCaseLabels** (``bool``)
|
|
Indent case labels one level from the switch statement.
|
|
|
|
When ``false``, use the same indentation level as for the switch statement.
|
|
Switch statement body is always indented one level more than case labels.
|
|
|
|
**IndentWidth** (``unsigned``)
|
|
The number of columns to use for indentation.
|
|
|
|
**IndentWrappedFunctionNames** (``bool``)
|
|
Indent if a function definition or declaration is wrapped after the
|
|
type.
|
|
|
|
**JavaScriptQuotes** (``JavaScriptQuoteStyle``)
|
|
The JavaScriptQuoteStyle to use for JavaScript strings.
|
|
|
|
Possible values:
|
|
|
|
* ``JSQS_Leave`` (in configuration: ``Leave``)
|
|
Leave string quotes as they are.
|
|
|
|
* ``JSQS_Single`` (in configuration: ``Single``)
|
|
Always use single quotes.
|
|
|
|
* ``JSQS_Double`` (in configuration: ``Double``)
|
|
Always use double quotes.
|
|
|
|
|
|
|
|
**KeepEmptyLinesAtTheStartOfBlocks** (``bool``)
|
|
If true, empty lines at the start of blocks are kept.
|
|
|
|
**Language** (``LanguageKind``)
|
|
Language, this format style is targeted at.
|
|
|
|
Possible values:
|
|
|
|
* ``LK_None`` (in configuration: ``None``)
|
|
Do not use.
|
|
|
|
* ``LK_Cpp`` (in configuration: ``Cpp``)
|
|
Should be used for C, C++, ObjectiveC, ObjectiveC++.
|
|
|
|
* ``LK_Java`` (in configuration: ``Java``)
|
|
Should be used for Java.
|
|
|
|
* ``LK_JavaScript`` (in configuration: ``JavaScript``)
|
|
Should be used for JavaScript.
|
|
|
|
* ``LK_Proto`` (in configuration: ``Proto``)
|
|
Should be used for Protocol Buffers
|
|
(https://developers.google.com/protocol-buffers/).
|
|
|
|
* ``LK_TableGen`` (in configuration: ``TableGen``)
|
|
Should be used for TableGen code.
|
|
|
|
|
|
|
|
**MacroBlockBegin** (``std::string``)
|
|
A regular expression matching macros that start a block.
|
|
|
|
**MacroBlockEnd** (``std::string``)
|
|
A regular expression matching macros that end a block.
|
|
|
|
**MaxEmptyLinesToKeep** (``unsigned``)
|
|
The maximum number of consecutive empty lines to keep.
|
|
|
|
**NamespaceIndentation** (``NamespaceIndentationKind``)
|
|
The indentation used for namespaces.
|
|
|
|
Possible values:
|
|
|
|
* ``NI_None`` (in configuration: ``None``)
|
|
Don't indent in namespaces.
|
|
|
|
* ``NI_Inner`` (in configuration: ``Inner``)
|
|
Indent only in inner namespaces (nested in other namespaces).
|
|
|
|
* ``NI_All`` (in configuration: ``All``)
|
|
Indent in all namespaces.
|
|
|
|
|
|
|
|
**ObjCBlockIndentWidth** (``unsigned``)
|
|
The number of characters to use for indentation of ObjC blocks.
|
|
|
|
**ObjCSpaceAfterProperty** (``bool``)
|
|
Add a space after ``@property`` in Objective-C, i.e. use
|
|
``@property (readonly)`` instead of ``@property(readonly)``.
|
|
|
|
**ObjCSpaceBeforeProtocolList** (``bool``)
|
|
Add a space in front of an Objective-C protocol list, i.e. use
|
|
``Foo <Protocol>`` instead of ``Foo<Protocol>``.
|
|
|
|
**PenaltyBreakBeforeFirstCallParameter** (``unsigned``)
|
|
The penalty for breaking a function call after ``call(``.
|
|
|
|
**PenaltyBreakComment** (``unsigned``)
|
|
The penalty for each line break introduced inside a comment.
|
|
|
|
**PenaltyBreakFirstLessLess** (``unsigned``)
|
|
The penalty for breaking before the first ``<<``.
|
|
|
|
**PenaltyBreakString** (``unsigned``)
|
|
The penalty for each line break introduced inside a string literal.
|
|
|
|
**PenaltyExcessCharacter** (``unsigned``)
|
|
The penalty for each character outside of the column limit.
|
|
|
|
**PenaltyReturnTypeOnItsOwnLine** (``unsigned``)
|
|
Penalty for putting the return type of a function onto its own
|
|
line.
|
|
|
|
**PointerAlignment** (``PointerAlignmentStyle``)
|
|
Pointer and reference alignment style.
|
|
|
|
Possible values:
|
|
|
|
* ``PAS_Left`` (in configuration: ``Left``)
|
|
Align pointer to the left.
|
|
|
|
* ``PAS_Right`` (in configuration: ``Right``)
|
|
Align pointer to the right.
|
|
|
|
* ``PAS_Middle`` (in configuration: ``Middle``)
|
|
Align pointer in the middle.
|
|
|
|
|
|
|
|
**ReflowComments** (``bool``)
|
|
If ``true``, clang-format will attempt to re-flow comments.
|
|
|
|
**SortIncludes** (``bool``)
|
|
If ``true``, clang-format will sort ``#includes``.
|
|
|
|
**SpaceAfterCStyleCast** (``bool``)
|
|
If ``true``, a space may be inserted after C style casts.
|
|
|
|
**SpaceAfterTemplateKeyword** (``bool``)
|
|
If ``true``, a space will be inserted after the 'template' keyword.
|
|
|
|
**SpaceBeforeAssignmentOperators** (``bool``)
|
|
If ``false``, spaces will be removed before assignment operators.
|
|
|
|
**SpaceBeforeParens** (``SpaceBeforeParensOptions``)
|
|
Defines in which cases to put a space before opening parentheses.
|
|
|
|
Possible values:
|
|
|
|
* ``SBPO_Never`` (in configuration: ``Never``)
|
|
Never put a space before opening parentheses.
|
|
|
|
* ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``)
|
|
Put a space before opening parentheses only after control statement
|
|
keywords (``for/if/while...``).
|
|
|
|
* ``SBPO_Always`` (in configuration: ``Always``)
|
|
Always put a space before opening parentheses, except when it's
|
|
prohibited by the syntax rules (in function-like macro definitions) or
|
|
when determined by other style rules (after unary operators, opening
|
|
parentheses, etc.)
|
|
|
|
|
|
|
|
**SpaceInEmptyParentheses** (``bool``)
|
|
If ``true``, spaces may be inserted into ``()``.
|
|
|
|
**SpacesBeforeTrailingComments** (``unsigned``)
|
|
The number of spaces before trailing line comments
|
|
(``//`` - comments).
|
|
|
|
This does not affect trailing block comments (``/*`` - comments) as
|
|
those commonly have different usage patterns and a number of special
|
|
cases.
|
|
|
|
**SpacesInAngles** (``bool``)
|
|
If ``true``, spaces will be inserted after ``<`` and before ``>``
|
|
in template argument lists.
|
|
|
|
**SpacesInCStyleCastParentheses** (``bool``)
|
|
If ``true``, spaces may be inserted into C style casts.
|
|
|
|
**SpacesInContainerLiterals** (``bool``)
|
|
If ``true``, spaces are inserted inside container literals (e.g.
|
|
ObjC and Javascript array and dict literals).
|
|
|
|
**SpacesInParentheses** (``bool``)
|
|
If ``true``, spaces will be inserted after ``(`` and before ``)``.
|
|
|
|
**SpacesInSquareBrackets** (``bool``)
|
|
If ``true``, spaces will be inserted after ``[`` and before ``]``.
|
|
|
|
**Standard** (``LanguageStandard``)
|
|
Format compatible with this standard, e.g. use ``A<A<int> >``
|
|
instead of ``A<A<int>>`` for ``LS_Cpp03``.
|
|
|
|
Possible values:
|
|
|
|
* ``LS_Cpp03`` (in configuration: ``Cpp03``)
|
|
Use C++03-compatible syntax.
|
|
|
|
* ``LS_Cpp11`` (in configuration: ``Cpp11``)
|
|
Use features of C++11 (e.g. ``A<A<int>>`` instead of ``A<A<int> >``).
|
|
|
|
* ``LS_Auto`` (in configuration: ``Auto``)
|
|
Automatic detection based on the input.
|
|
|
|
|
|
|
|
**TabWidth** (``unsigned``)
|
|
The number of columns used for tab stops.
|
|
|
|
**UseTab** (``UseTabStyle``)
|
|
The way to use tab characters in the resulting file.
|
|
|
|
Possible values:
|
|
|
|
* ``UT_Never`` (in configuration: ``Never``)
|
|
Never use tab.
|
|
|
|
* ``UT_ForIndentation`` (in configuration: ``ForIndentation``)
|
|
Use tabs only for indentation.
|
|
|
|
* ``UT_Always`` (in configuration: ``Always``)
|
|
Use tabs whenever we need to fill whitespace that spans at least from
|
|
one tab stop to the next one.
|
|
|
|
|
|
|
|
.. END_FORMAT_STYLE_OPTIONS
|
|
|
|
Adding additional style options
|
|
===============================
|
|
|
|
Each additional style option adds costs to the clang-format project. Some of
|
|
these costs affect the clang-format development itself, as we need to make
|
|
sure that any given combination of options work and that new features don't
|
|
break any of the existing options in any way. There are also costs for end users
|
|
as options become less discoverable and people have to think about and make a
|
|
decision on options they don't really care about.
|
|
|
|
The goal of the clang-format project is more on the side of supporting a
|
|
limited set of styles really well as opposed to supporting every single style
|
|
used by a codebase somewhere in the wild. Of course, we do want to support all
|
|
major projects and thus have established the following bar for adding style
|
|
options. Each new style option must ..
|
|
|
|
* be used in a project of significant size (have dozens of contributors)
|
|
* have a publicly accessible style guide
|
|
* have a person willing to contribute and maintain patches
|
|
|
|
Examples
|
|
========
|
|
|
|
A style similar to the `Linux Kernel style
|
|
<https://www.kernel.org/doc/Documentation/CodingStyle>`_:
|
|
|
|
.. code-block:: yaml
|
|
|
|
BasedOnStyle: LLVM
|
|
IndentWidth: 8
|
|
UseTab: Always
|
|
BreakBeforeBraces: Linux
|
|
AllowShortIfStatementsOnASingleLine: false
|
|
IndentCaseLabels: false
|
|
|
|
The result is (imagine that tabs are used for indentation here):
|
|
|
|
.. code-block:: c++
|
|
|
|
void test()
|
|
{
|
|
switch (x) {
|
|
case 0:
|
|
case 1:
|
|
do_something();
|
|
break;
|
|
case 2:
|
|
do_something_else();
|
|
break;
|
|
default:
|
|
break;
|
|
}
|
|
if (condition)
|
|
do_something_completely_different();
|
|
|
|
if (x == y) {
|
|
q();
|
|
} else if (x > y) {
|
|
w();
|
|
} else {
|
|
r();
|
|
}
|
|
}
|
|
|
|
A style similar to the default Visual Studio formatting style:
|
|
|
|
.. code-block:: yaml
|
|
|
|
UseTab: Never
|
|
IndentWidth: 4
|
|
BreakBeforeBraces: Allman
|
|
AllowShortIfStatementsOnASingleLine: false
|
|
IndentCaseLabels: false
|
|
ColumnLimit: 0
|
|
|
|
The result is:
|
|
|
|
.. code-block:: c++
|
|
|
|
void test()
|
|
{
|
|
switch (suffix)
|
|
{
|
|
case 0:
|
|
case 1:
|
|
do_something();
|
|
break;
|
|
case 2:
|
|
do_something_else();
|
|
break;
|
|
default:
|
|
break;
|
|
}
|
|
if (condition)
|
|
do_somthing_completely_different();
|
|
|
|
if (x == y)
|
|
{
|
|
q();
|
|
}
|
|
else if (x > y)
|
|
{
|
|
w();
|
|
}
|
|
else
|
|
{
|
|
r();
|
|
}
|
|
}
|
|
|