clang-format.rst

当前配置内容

AllowShortFunctionsOnASingleLine: false
AllowShortIfStatementsOnASingleLine: false
AllowShortLoopsOnASingleLine: false
AlwaysBreakBeforeMultilineStrings: false
BinPackParameters: false
BreakBeforeBinaryOperators: None
BreakBeforeTernaryOperators: true
BreakConstructorInitializersBeforeComma: true
ColumnLimit: 120
BreakBeforeBraces: Linux
CommentPragmas: ''
ContinuationIndentWidth: 4
IndentCaseLabels: true
IndentWidth: 4
Language: ObjC
MaxEmptyLinesToKeep: 1
ObjCSpaceAfterProperty: true
ObjCSpaceBeforeProtocolList: true
ObjCBlockIndentWidth: 4
PenaltyBreakBeforeFirstCallParameter: 100
PenaltyBreakComment: 100
PenaltyBreakFirstLessLess: 0
PenaltyBreakString: 100
PenaltyExcessCharacter: 1
PenaltyReturnTypeOnItsOwnLine: 20
SpaceBeforeAssignmentOperators: true
SpaceBeforeParens: ControlStatements
SpaceInEmptyParentheses: false
SpacesBeforeTrailingComments: 1
SpacesInAngles: false
SpacesInCStyleCastParentheses: false
SpacesInContainerLiterals: false
SpacesInParentheses: false
SpacesInSquareBrackets: false
TabWidth: 4
UseTab: Never

每项说明

AllowShortFunctionsOnASingleLine (ShortFunctionStyle)

Used false.

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.

  void f() { bar(); }
  void f2() {
    bar2();
  }

• SFS_Inline (in configuration: Inline) Only merge functions defined inside a class. Implies "empty".

  class Foo {
    void f() { foo(); }
  };

• SFS_All (in configuration: All) Merge all functions fitting on a single line.

  class Foo {
    void f() { foo(); }
  };
  void f() { bar(); }

AllowShortIfStatementsOnASingleLine (bool)

Used false.

If true, if (a) return; can be put on a single line.

AllowShortLoopsOnASingleLine (bool)

Used false.

If true, while (true) continue; can be put on a single line.

AlwaysBreakBeforeMultilineStrings (bool)

Used false.

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.

true:                                  false:
aaaa =                         vs.     aaaa = "bbbb"
    "bbbb"                                    "cccc";
    "cccc";

BinPackParameters (bool)

Used false.

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.

true:
void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa,
       int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}

false:
void f(int aaaaaaaaaaaaaaaaaaaa,
       int aaaaaaaaaaaaaaaaaaaa,
       int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}

BreakBeforeBinaryOperators (BinaryOperatorStyle)

Used None.

The way to wrap binary operators.

Possible values:

• BOS_None (in configuration: None) Break after operators.

  LooooooooooongType loooooooooooooooooooooongVariable =
      someLooooooooooooooooongFunction();
  
  bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +
                       aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ==
                   aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa &&
               aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa >
                   ccccccccccccccccccccccccccccccccccccccccc;

• BOS_NonAssignment (in configuration: NonAssignment) Break before operators that aren't assignments.

  LooooooooooongType loooooooooooooooooooooongVariable =
      someLooooooooooooooooongFunction();
  
  bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
                       + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
                   == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
               && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
                      > ccccccccccccccccccccccccccccccccccccccccc;

• BOS_All (in configuration: All) Break before operators.

  LooooooooooongType loooooooooooooooooooooongVariable
      = someLooooooooooooooooongFunction();
  
  bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
                       + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
                   == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
               && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
                      > ccccccccccccccccccccccccccccccccccccccccc;

BreakBeforeTernaryOperators (bool)

Used true.

If true, ternary operators will be placed after line breaks.

true:
veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription
    ? firstValue
    : SecondValueVeryVeryVeryVeryLong;

true:
veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ?
    firstValue :
    SecondValueVeryVeryVeryVeryLong;

BreakConstructorInitializersBeforeComma (bool)

Used true.

Always break constructor initializers before commas and align the commas with the colon.

true:                                  false:
SomeClass::Constructor()       vs.     SomeClass::Constructor() : a(a),
    : a(a)                                                   b(b),
    , b(b)                                                   c(c) {}
    , c(c) {}

ColumnLimit (unsigned)

Used 120.

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.

BreakBeforeBraces (BraceBreakingStyle)

Used Linux.

The brace breaking style to use.

Possible values:

• BS_Attach (in configuration: Attach) Always attach braces to surrounding context.

  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.

  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.

  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.

  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.

  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.

  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.

  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.

CommentPragmas (std::string)

Used ''.

A regular expression that describes comments with special meaning, which should not be split into lines or otherwise changed.

// CommentPragmas: '^ FOOBAR pragma:'
// Will leave the following line unaffected
#include <vector> // FOOBAR pragma: keep

ContinuationIndentWidth (unsigned)

Used 4.

Indent width for line continuations.

ContinuationIndentWidth: 2

int i =         //  VeryVeryVeryVeryVeryLongComment
  longFunction( // Again a long comment
    arg);

IndentCaseLabels (bool)

Used true.

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.

false:                                 true:
switch (fool) {                vs.     switch (fool) {
case 1:                                  case 1:
  bar();                                   bar();
  break;                                   break;
default:                                 default:
  plop();                                  plop();
}                                      }

IndentWidth (unsigned)

Used 4.

The number of columns to use for indentation.

IndentWidth: 3

void f() {
   someFunction();
   if (true, false) {
      f();
   }
}

Language (LanguageKind)

Used ObjC.

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.

MaxEmptyLinesToKeep (unsigned)

Used 1.

The maximum number of consecutive empty lines to keep.

MaxEmptyLinesToKeep: 1         vs.     MaxEmptyLinesToKeep: 0
int f() {                              int f() {
  int = 1;                                 int i = 1;
                                           i = foo();
  i = foo();                               return i;
                                       }
  return i;
}

ObjCSpaceAfterProperty (bool)

Used true.

Add a space after @property in Objective-C, i.e. use @property (readonly) instead of @property(readonly).

ObjCSpaceBeforeProtocolList (bool)

Used true.

Add a space in front of an Objective-C protocol list, i.e. use Foo <Protocol> instead of Foo<Protocol>.

ObjCBlockIndentWidth (unsigned)

Used 4.

The number of characters to use for indentation of ObjC blocks.

ObjCBlockIndentWidth: 4

[operation setCompletionBlock:^{
    [self onOperationDone];
}];

PenaltyBreakBeforeFirstCallParameter (unsigned)

Used 100.

The penalty for breaking a function call after call(.

PenaltyBreakComment (unsigned)

Used 100.

The penalty for each line break introduced inside a comment.

PenaltyBreakFirstLessLess (unsigned)

Used 0.

The penalty for breaking before the first <<.

PenaltyBreakString (unsigned)

Used 100.

The penalty for each line break introduced inside a string literal.

PenaltyExcessCharacter (unsigned)

Used 1.

The penalty for each character outside of the column limit.

PenaltyReturnTypeOnItsOwnLine (unsigned)

Used 20.

Penalty for putting the return type of a function onto its own line.

SpaceBeforeAssignmentOperators (bool)

Used true.

If false, spaces will be removed before assignment operators.

true:                                  false:
int a = 5;                     vs.     int a=5;
a += 42                                a+=42;

SpaceBeforeParens (SpaceBeforeParensOptions)

Used ControlStatements.

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.

  void f() {
    if(true) {
      f();
    }
  }

SpaceInEmptyParentheses (bool)

Used false.

If true, spaces may be inserted into ().

true:                                false:
void f( ) {                    vs.   void f() {
  int x[] = {foo( ), bar( )};          int x[] = {foo(), bar()};
  if (true) {                          if (true) {
    f( );                                f();
  }                                    }
}                                    }

SpacesBeforeTrailingComments (unsigned)

Used 1.

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.

SpacesBeforeTrailingComments: 3
void f() {
  if (true) {   // foo1
    f();        // bar
  }             // foo
}

SpacesInAngles (bool)

Used false.

If true, spaces will be inserted after < and before > in template argument lists.

true:                                  false:
static_cast< int >(arg);       vs.     static_cast<int>(arg);
std::function< void(int) > fct;        std::function<void(int)> fct;

SpacesInCStyleCastParentheses (bool)

Used false.

If true, spaces may be inserted into C style casts.

true:                                  false:
x = ( int32 )y                 vs.     x = (int32)y

SpacesInContainerLiterals (bool)

Used false.

If true, spaces are inserted inside container literals (e.g. ObjC and Javascript array and dict literals).

true:                                  false:
var arr = [ 1, 2, 3 ];         vs.     var arr = [1, 2, 3];
f({a : 1, b : 2, c : 3});              f({a: 1, b: 2, c: 3});

SpacesInParentheses (bool)

Used false.

If true, spaces will be inserted after ( and before ).

true:                                  false:
t f( Deleted & ) & = delete;   vs.     t f(Deleted &) & = delete;

SpacesInSquareBrackets (bool)

Used false.

If true, spaces will be inserted after [ and before ].

Lambdas or unspecified size array declarations will not be affected.

true:                                  false:
int a[ 5 ];                    vs.     int a[5];
std::unique_ptr<int[]> foo() {} // Won't be affected

TabWidth (unsigned)

Used 4.

The number of columns used for tab stops.

UseTab (UseTabStyle)

Used Never.

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_ForContinuationAndIndentation (in configuration: ForContinuationAndIndentation) Use tabs only for line continuation and 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.