| ========================== |
| 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. |
| ... |
| |
| 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, ...}' |
| |
| |
| 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:``. |
| |
| **AlignEscapedNewlinesLeft** (``bool``) |
| If ``true``, aligns escaped newlines as far left as possible. |
| Otherwise puts them into the right-most column. |
| |
| **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``. |
| |
| **AllowShortFunctionsOnASingleLine** (``bool``) |
| If ``true``, ``int f() { return 0; }`` can be put 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. |
| |
| **AlwaysBreakBeforeMultilineStrings** (``bool``) |
| If ``true``, always break before multiline string literals. |
| |
| **AlwaysBreakTemplateDeclarations** (``bool``) |
| If ``true``, always break after the ``template<...>`` of a |
| template declaration. |
| |
| **BinPackParameters** (``bool``) |
| If ``false``, a function call's or function definition's parameters |
| will either all be on the same line or will have one line each. |
| |
| **BreakBeforeBinaryOperators** (``bool``) |
| If ``true``, binary operators will be placed after line breaks. |
| |
| **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_Stroustrup`` (in configuration: ``Stroustrup``) |
| Like ``Attach``, but break before function definitions. |
| * ``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. |
| |
| |
| **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. |
| |
| **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. |
| |
| **DerivePointerBinding** (``bool``) |
| If ``true``, analyze the formatted file for the most common binding |
| and use ``PointerBindsToType`` only as fallback. |
| |
| **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 list of macros that should be interpreted as foreach loops instead of as |
| function calls. |
| |
| For example, ``ForEachMacros: [BOOST_FOREACH, Q_FOREACH]`` tells |
| clang-format to treat ``BOOST_FOREACH`` and ``Q_FOREACH`` as loop control |
| statements. |
| |
| **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. |
| |
| **IndentFunctionDeclarationAfterType** (``bool``) |
| If ``true``, indent when breaking function declarations which |
| are not also definitions after the type. |
| |
| **IndentWidth** (``unsigned``) |
| The number of columns to use for indentation. |
| |
| **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_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/). |
| |
| |
| **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. |
| |
| |
| **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. |
| |
| **PointerBindsToType** (``bool``) |
| Set whether & and * bind to the type as opposed to the variable. |
| |
| **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 to before trailing line comments. |
| |
| **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 ')'. |
| |
| **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 |
| |
| 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(); |
| } |
| } |
| |