# 2) The preservation of meticulously formatted code found in many files.
#
# This file should be considered as a style-guide for new code.
#
# The comments before each option are reStructuredText formatted text converted
# from the https://clang.llvm.org/docs/ClangFormatStyleOptions.html web page.
---
# **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++.
# * ``LK_Java`` (in configuration: ``Java``) Should be used for Java.
# * ``LK_JavaScript`` (in configuration: ``JavaScript``) Should be used for JavaScript.
# * ``LK_ObjC`` (in configuration: ``ObjC``) Should be used for Objective-C, Objective-C++.
# * ``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.
# * ``LK_TextProto`` (in configuration: ``TextProto``) Should be used for Protocol Buffer messages in text format (https://developers.google.com/protocol-buffers/).
Language: Cpp
# **BasedOnStyle** (``string``)
# The style used for all options not specifically set in the configuration.
#
# This option is supported only in the **clang-format** configuration (both within ``-style='{...}'`` and the ``.clang-format`` file).
#
# Possible values:
#
# * ``LLVM`` A style complying with the `LLVM coding standards`_
# * ``Google`` A style complying with `Google's C++ style guide`_
# * ``Chromium`` A style complying with `Chromium's style guide`_
# * ``Mozilla`` A style complying with `Mozilla's style guide`_
# * ``WebKit`` A style complying with `WebKit's style guide`_
# If the function declaration doesn't fit on a line, allow putting all parameters of a function declaration onto the next line even if ``BinPackParameters`` is ``false``.
#
# .. parsed-literal::
#
# true:
# void myFunction(
# int a, int b, int c, int d, int e);
#
# false:
# void myFunction(int a,
# int b,
# int c,
# int d,
# int e);
# Rational: Average FG style with minimal diff.
# Rational: Preservation of formatting.
AllowAllParametersOfDeclarationOnNextLine: true
# **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.
# * ``SFS_InlineOnly`` (in configuration: ``InlineOnly``) Only merge functions defined inside a class. Same as "inline", except it does not implies "empty": i.e. top level empty functions are not merged either.
# 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.
#
# .. parsed-literal::
#
# true: false:
# aaaa = vs. aaaa = "bbbb"
# "bbbb" "cccc";
# "cccc";
# Rational: Average FG style with minimal diff.
AlwaysBreakBeforeMultilineStrings: false
# **AlwaysBreakTemplateDeclarations** (``bool``)
# If ``true``, always break after the ``template<...>`` of a template declaration.
#
# .. parsed-literal::
#
# true: false:
# template <typename T> vs. template <typename T> class C {};
# class C {};
# Rational: Average FG style with minimal diff.
AlwaysBreakTemplateDeclarations: false
# **BinPackArguments** (``bool``)
# If ``false``, a function call's arguments will either be all on the same line or will have one line each.
#
# .. parsed-literal::
#
# true:
# void f() {
# f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa,
# aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
# }
#
# false:
# void f() {
# f(aaaaaaaaaaaaaaaaaaaa,
# aaaaaaaaaaaaaaaaaaaa,
# aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
# }
# Rational: Average FG style with minimal diff.
BinPackArguments: true
# **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.
#
# .. parsed-literal::
#
# true:
# void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa,
# int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
#
# false:
# void f(int aaaaaaaaaaaaaaaaaaaa,
# int aaaaaaaaaaaaaaaaaaaa,
# int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
# Rational: Average FG style with minimal diff.
BinPackParameters: true
# **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.
#
# .. parsed-literal::
#
# # Example of usage:
# BreakBeforeBraces: Custom
# BraceWrapping:
# AfterEnum: true
# AfterStruct: false
# SplitEmptyFunction: false
#
# Nested configuration flags:
#
# * ``bool AfterClass`` Wrap class definitions.
#
# .. parsed-literal::
#
# true:
# class foo {};
#
# false:
# class foo
# {};
#
# * ``bool AfterControlStatement`` Wrap control statements (``if``/``for``/``while``/``switch``/..).
#
# .. parsed-literal::
#
# true:
# if (foo())
# {
# } else
# {}
# for (int i = 0; i < 10; ++i)
# {}
#
# false:
# if (foo()) {
# } else {
# }
# for (int i = 0; i < 10; ++i) {
# }
#
# * ``bool AfterEnum`` Wrap enum definitions.
#
# .. parsed-literal::
#
# true:
# enum X : int
# {
# B
# };
#
# false:
# enum X : int { B };
#
# * ``bool AfterFunction`` Wrap function definitions.
# * ``bool AfterObjCDeclaration`` Wrap ObjC definitions (interfaces, implementations...). @autoreleasepool and @synchronized blocks are wrapped according to *AfterControlStatement* flag.
# * ``bool IndentBraces`` Indent the wrapped braces themselves.
#
# * ``bool SplitEmptyFunction`` If ``false``, empty function body can be put on a single line. This option is used only if the opening brace of the function has already been wrapped, i.e. the *AfterFunction* brace wrapping mode is set, and the function could/should not be put on a single line (as per *AllowShortFunctionsOnASingleLine* and constructor formatting options).
#
# .. parsed-literal::
#
# int f() vs. inf f()
# {} {
# }
#
# * ``bool SplitEmptyRecord`` If ``false``, empty record (e.g. class, struct or union) body can be put on a single line. This option is used only if the opening brace of the record has already been wrapped, i.e. the *AfterClass* (for classes) brace wrapping mode is set.
#
# .. parsed-literal::
#
# class Foo vs. class Foo
# {} {
# }
#
# * ``bool SplitEmptyNamespace`` If ``false``, empty namespace body can be put on a single line. This option is used only if the opening brace of the namespace has already been wrapped, i.e. the *AfterNamespace* brace wrapping mode is set.
# * ``BS_Attach`` (in configuration: ``Attach``) Always attach braces to surrounding context.
#
# .. parsed-literal::
#
# try {
# foo();
# } catch () {
# }
# void foo() { bar(); }
# class foo {};
# if (foo()) {
# } else {
# }
# enum X : int { A, B };
#
# * ``BS_Linux`` (in configuration: ``Linux``) Like ``Attach``, but break before braces on function, namespace and class definitions.
#
# .. parsed-literal::
#
# try {
# foo();
# } catch () {
# }
# void foo() { bar(); }
# class foo
# {
# };
# if (foo()) {
# } else {
# }
# enum X : int { A, B };
#
# * ``BS_Mozilla`` (in configuration: ``Mozilla``) Like ``Attach``, but break before braces on enum, function, and record definitions.
#
# .. parsed-literal::
#
# try {
# foo();
# } catch () {
# }
# void foo() { bar(); }
# class foo
# {
# };
# if (foo()) {
# } else {
# }
# enum X : int { A, B };
#
# * ``BS_Stroustrup`` (in configuration: ``Stroustrup``) Like ``Attach``, but break before function definitions, ``catch``, and ``else``.
#
# .. parsed-literal::
#
# try {
# foo();
# } catch () {
# }
# void foo() { bar(); }
# class foo
# {
# };
# if (foo()) {
# } else {
# }
# enum X : int
# {
# A,
# B
# };
#
# * ``BS_Allman`` (in configuration: ``Allman``) Always break before braces.
#
# .. parsed-literal::
#
# try {
# foo();
# }
# catch () {
# }
# void foo() { bar(); }
# class foo {
# };
# if (foo()) {
# }
# else {
# }
# enum X : int { A, B };
#
# * ``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.
#
# .. parsed-literal::
#
# try
# {
# foo();
# }
# catch ()
# {
# }
# void foo() { bar(); }
# class foo
# {
# };
# if (foo())
# {
# }
# else
# {
# }
# enum X : int
# {
# A,
# B
# };
#
# * ``BS_WebKit`` (in configuration: ``WebKit``) Like ``Attach``, but break before functions.
#
# .. parsed-literal::
#
# try {
# foo();
# } catch () {
# }
# void foo() { bar(); }
# class foo {
# };
# if (foo()) {
# } else {
# }
# enum X : int { A, B };
#
# * ``BS_Custom`` (in configuration: ``Custom``) Configure each individual brace in *BraceWrapping*.
# Rational: Average FG style with minimal diff.
BreakBeforeBraces: Custom
# **BreakBeforeInheritanceComma** (``bool``)
# If ``true``, in the class inheritance expression clang-format will break before ``:`` and ``,`` if there is multiple inheritance.
#
# .. parsed-literal::
#
# true: false:
# class MyClass vs. class MyClass : public X, public Y {
# : public X };
# , public Y {
# };
# Clang version >= 5.
#BreakBeforeInheritanceComma: false
# **BreakBeforeTernaryOperators** (``bool``)
# If ``true``, ternary operators will be placed after line breaks.
# * ``BCIS_BeforeColon`` (in configuration: ``BeforeColon``) Break constructor initializers before the colon and after the commas.
#
# Constructor()
# : initializer1(),
# initializer2()
#
# * ``BCIS_BeforeComma`` (in configuration: ``BeforeComma``) Break constructor initializers before the colon and commas, and align the commas with the colon.
#
# Constructor()
# : initializer1() , initializer2()
#
# * ``BCIS_AfterColon`` (in configuration: ``AfterColon``) Break constructor initializers after the colon and commas.
# Always break constructor initializers before commas and align the commas with the colon.
# Clang version < 5.
# Rational: Average FG style with minimal diff.
BreakConstructorInitializersBeforeComma: false
# **BreakStringLiterals** (``bool``)
# Allow breaking string literals when formatting.
# Rational: Average FG style with minimal diff.
BreakStringLiterals: false
# **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.
# Rational: Average FG style with minimal diff.
ColumnLimit: 0
# **CommentPragmas** (``std::string``)
# A regular expression that describes comments with special meaning, which should not be split into lines or otherwise changed.
#
# .. parsed-literal::
#
# // CommentPragmas: '^ FOOBAR pragma:'
# // Will leave the following line unaffected
# #include <vector> // FOOBAR pragma: keep
# Rational: Average FG style with minimal diff.
CommentPragmas: None
# **CompactNamespaces** (``bool``)
# If ``true``, consecutive namespace declarations will be on the same line. If ``false``, each namespace is declared on a new line.
#
# .. parsed-literal::
#
# true:
# namespace Foo { namespace Bar {
# }}
#
# false:
# namespace Foo {
# namespace Bar {
# }
# }
#
# If it does not fit on a single line, the overflowing namespaces get wrapped:
# The number of characters to use for indentation of constructor initializer lists.
# Rational: Preservation of formatting.
ConstructorInitializerIndentWidth: 4
# **ContinuationIndentWidth** (``unsigned``)
# Indent width for line continuations.
#
# .. parsed-literal::
#
# ContinuationIndentWidth: 2
#
# int i = // VeryVeryVeryVeryVeryLongComment
# longFunction( // Again a long comment
# arg);
# Rational: Average FG style with minimal diff.
ContinuationIndentWidth: 4
# **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.
# Rational: Switch to the C++11 braced lists format.
Cpp11BracedListStyle: true
# **DerivePointerAlignment** (``bool``)
# If ``true``, analyze the formatted file for the most common alignment of ``&`` and ``*``. Pointer and reference alignment styles are going to be updated according to the preferences found in the file. ``PointerAlignment`` is then used only as fallback.
# Rational: Do not override PointerAlignment!
DerivePointerAlignment: false
# **DisableFormat** (``bool``)
# Disables formatting completely.
# Rational: N/A.
DisableFormat: false
# **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.
# Rational: N/A.
#ExperimentalAutoDetectBinPacking: false
# **FixNamespaceComments** (``bool``)
# If ``true``, clang-format adds missing namespace end comments and fixes invalid existing ones.
#
# .. parsed-literal::
#
# true: false:
# namespace a { vs. namespace a {
# foo(); foo();
# } // namespace a; }
# Clang version >= 5.
# Rational: This should be set to ``true`` when possible.
# Dependent on the value, multiple ``#include`` blocks can be sorted as one and divided based on category.
#
# Possible values:
#
# * ``IBS_Preserve`` (in configuration: ``Preserve``) Sort each ``#include`` block separately.
#
# .. parsed-literal::
#
# #include "b.h" into #include "b.h"
#
# #include <lib/main.h> #include "a.h"
# #include "a.h" #include <lib/main.h>
#
# * ``IBS_Merge`` (in configuration: ``Merge``) Merge multiple ``#include`` blocks together and sort as one.
#
# .. parsed-literal::
#
# #include "b.h" into #include "a.h"
# #include "b.h"
# #include <lib/main.h> #include <lib/main.h>
# #include "a.h"
#
# * ``IBS_Regroup`` (in configuration: ``Regroup``) Merge multiple ``#include`` blocks together and sort as one. Then split into groups based on category priority. See ``IncludeCategories``.
# 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:
#
# .. parsed-literal::
#
# IncludeCategories:
# - Regex: '^"(llvm|llvm-c|clang|clang-c)/'
# Priority: 2
# - Regex: '^(<|"(gtest|gmock|isl|json)/)'
# Priority: 3
# - Regex: '.*'
# Priority: 1
# Rational: Left on the default LLVM values.
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"
# 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.
# A raw string with a matching delimiter or a matching enclosing function name will be reformatted assuming the specified language based on the style for that language defined in the .clang-format file. If no style has been defined in the .clang-format file for the specific language, a predefined style given by 'BasedOnStyle' is used. If 'BasedOnStyle' is not found, the formatting is based on llvm style. A matching delimiter takes precedence over a matching enclosing function name for determining the language of the raw string contents.
# The order of using declarations is defined as follows: Split the strings by "\:\:" and discard any initial empty strings. The last element of each list is a non-namespace name; all others are namespace names. Sort the lists of names lexicographically, where the sort order of individual names is that all non-namespace names come before all namespace names, and within those groups, names are in case-insensitive lexicographic order.
# 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.
#
# .. parsed-literal::
#
# void f() {
# if(true) {
# f();
# }
# }
#
# * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``) Put a space before opening parentheses only after control statement keywords (``for/if/while...``).
#
# .. parsed-literal::
#
# void f() {
# if (true) {
# f();
# }
# }
#
# * ``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.)
