558 lines
11 KiB
Markdown
558 lines
11 KiB
Markdown
# Advanced & Experimental Options
|
|
|
|
[← Prev: Comments](08-comments.md) | [Back to Index](index.md) | [Quick Reference](quick-reference.md)
|
|
|
|
**Navigation:** [Alignment](01-alignment.md) | [Breaking](02-breaking.md) | [Braces](03-braces.md) | [Indentation](04-indentation.md) | [Spacing](05-spacing.md) | [Includes](06-includes.md) | [Languages](07-languages.md) | [Comments](08-comments.md) | [Advanced](09-advanced.md)
|
|
|
|
Experimental, advanced, and less commonly used options.
|
|
|
|
## Experimental Options
|
|
|
|
### ExperimentalAutoDetectBinPacking
|
|
|
|
Automatically detect bin packing from existing code.
|
|
|
|
**Type:** `Boolean` **Default:** `false` **Status:** Experimental
|
|
|
|
When enabled, clang-format attempts to detect whether arguments/parameters are bin-packed in the existing code and maintains that style.
|
|
|
|
**Warning:** This is experimental and may not work perfectly.
|
|
|
|
## C++ Specific
|
|
|
|
### Cpp11BracedListStyle
|
|
|
|
Use C++11 braced list style.
|
|
|
|
**Type:** `BracedListStyle` **Default:** `true`
|
|
|
|
**Example:**
|
|
|
|
`true`:
|
|
|
|
```cpp
|
|
vector<int> x{1, 2, 3, 4};
|
|
vector<T> x{{}, {}, {}, {}};
|
|
f(MyMap[{composite, key}]);
|
|
new int[3]{1, 2, 3};
|
|
```
|
|
|
|
`false`:
|
|
|
|
```cpp
|
|
vector<int> x{ 1, 2, 3, 4 };
|
|
vector<T> x{ {}, {}, {}, {} };
|
|
f(MyMap[{ composite, key }]);
|
|
new int[3]{ 1, 2, 3 };
|
|
```
|
|
|
|
### AlwaysBreakTemplateDeclarations
|
|
|
|
Control breaking after template declarations (deprecated).
|
|
|
|
**Type:** `BreakTemplateDeclarationsStyle` **Note:** Use `BreakTemplateDeclarations` instead
|
|
|
|
### AlwaysBreakAfterDefinitionReturnType
|
|
|
|
Control breaking after function definition return type (deprecated).
|
|
|
|
**Type:** `DefinitionReturnTypeBreakingStyle` **Note:** Use `BreakAfterReturnType` instead
|
|
|
|
### AllowAllConstructorInitializersOnNextLine
|
|
|
|
Allow constructor initializers on next line (deprecated).
|
|
|
|
**Type:** `Boolean` **Default:** `true` **Note:** Deprecated in favor of `PackConstructorInitializers`
|
|
|
|
### ConstructorInitializerAllOnOneLineOrOnePerLine
|
|
|
|
Format constructor initializers (deprecated).
|
|
|
|
**Type:** `Boolean` **Note:** Deprecated in favor of `PackConstructorInitializers`
|
|
|
|
### PackConstructorInitializers
|
|
|
|
How to pack constructor initializers.
|
|
|
|
**Type:** `PackConstructorInitializersStyle` **Values:**
|
|
|
|
- `Never` - Always put one per line
|
|
- `BinPack` - Bin-pack constructor initializers
|
|
- `CurrentLine` - Pack on current line if it fits
|
|
- `NextLine` - Pack on next line
|
|
|
|
## BinPacking
|
|
|
|
### BinPackLongBracedList
|
|
|
|
Bin-pack long braced lists.
|
|
|
|
**Type:** `Boolean`
|
|
|
|
When true, long braced lists will be bin-packed even if arguments aren't.
|
|
|
|
## Breaking Binary Operations
|
|
|
|
### BreakBinaryOperations
|
|
|
|
Control breaking of binary operations.
|
|
|
|
**Type:** `BreakBinaryOperationsStyle` **Values:**
|
|
|
|
- `RespectPrecedence` - Break respecting precedence
|
|
- `OnePerLine` - One operation per line
|
|
- `Never` - Don't break
|
|
|
|
**Example:**
|
|
|
|
`OnePerLine`:
|
|
|
|
```cpp
|
|
auto x =
|
|
(aaaaa
|
|
+ bbbbb
|
|
+ ccccc);
|
|
```
|
|
|
|
## Template Behavior
|
|
|
|
### BreakBeforeTemplateCloser
|
|
|
|
Break before `>` in template declarations.
|
|
|
|
**Type:** `Boolean`
|
|
|
|
**Example:**
|
|
|
|
`true`:
|
|
|
|
```cpp
|
|
template<typename T
|
|
>
|
|
class Foo {};
|
|
```
|
|
|
|
`false`:
|
|
|
|
```cpp
|
|
template<typename T>
|
|
class Foo {};
|
|
```
|
|
|
|
### AlwaysBreakBeforeMultilineStrings
|
|
|
|
Always break before multiline string literals.
|
|
|
|
**Type:** `Boolean`
|
|
|
|
**Example:**
|
|
|
|
`true`:
|
|
|
|
```cpp
|
|
aaaa =
|
|
"bbbb"
|
|
"cccc";
|
|
```
|
|
|
|
`false`:
|
|
|
|
```cpp
|
|
aaaa = "bbbb"
|
|
"cccc";
|
|
```
|
|
|
|
## Special Case Handling
|
|
|
|
### AllowShortCaseExpressionOnASingleLine
|
|
|
|
Allow short case expressions on one line (for pattern matching languages).
|
|
|
|
**Type:** `Boolean`
|
|
|
|
### AllowShortCompoundRequirementOnASingleLine
|
|
|
|
Allow short compound requirements on one line (C++20 concepts).
|
|
|
|
**Type:** `Boolean`
|
|
|
|
### AllowShortNamespacesOnASingleLine
|
|
|
|
Allow short namespace declarations on one line.
|
|
|
|
**Type:** `Boolean`
|
|
|
|
**Example:**
|
|
|
|
`true`:
|
|
|
|
```cpp
|
|
namespace a { class A; }
|
|
```
|
|
|
|
`false`:
|
|
|
|
```cpp
|
|
namespace a {
|
|
class A;
|
|
}
|
|
```
|
|
|
|
### AllowBreakBeforeNoexceptSpecifier
|
|
|
|
Control breaking before noexcept specifier.
|
|
|
|
**Type:** `BreakBeforeNoexceptSpecifierStyle` **Values:**
|
|
|
|
- `Never`, `OnlyWithParen`, `Always`
|
|
|
|
### AllowBreakBeforeQtProperty
|
|
|
|
Allow breaking before Qt property keywords.
|
|
|
|
**Type:** `Boolean` **Since:** v22
|
|
|
|
Allow breaking before `Q_Property` keywords `READ`, `WRITE`, etc. as if they were preceded by a comma. This allows them to be formatted according to `BinPackParameters`.
|
|
|
|
**Example:**
|
|
|
|
When enabled with appropriate bin-packing settings, Qt property declarations can have their keywords broken across lines more flexibly.
|
|
|
|
## Numeric Literals
|
|
|
|
### NumericLiteralCase
|
|
|
|
Capitalization style for numeric literals.
|
|
|
|
**Type:** `NumericLiteralCaseStyle` **Since:** v22
|
|
|
|
Separate control for each numeric literal component.
|
|
|
|
**Sub-options:**
|
|
|
|
- `ExponentLetter` - Format floating point exponent separator letter case
|
|
- `HexDigit` - Format hexadecimal digit case
|
|
- `Prefix` - Format integer prefix case
|
|
- `Suffix` - Format suffix case (excludes case-sensitive reserved suffixes like `min` in C++)
|
|
|
|
**Values for each component:**
|
|
|
|
- `Leave` - Leave this component as is
|
|
- `Upper` - Format with uppercase characters
|
|
- `Lower` - Format with lowercase characters
|
|
|
|
**Example:**
|
|
|
|
```yaml
|
|
NumericLiteralCase:
|
|
ExponentLetter: Leave
|
|
HexDigit: Lower
|
|
Prefix: Upper
|
|
Suffix: Lower
|
|
```
|
|
|
|
**Before:**
|
|
|
|
```cpp
|
|
float a = 6.02e23 + 1.0E10;
|
|
a = 0xaBcDeF;
|
|
a = 0xF0 | 0b1;
|
|
a = 1uLL;
|
|
```
|
|
|
|
**After (with config above):**
|
|
|
|
```cpp
|
|
float a = 6.02e23 + 1.0E10; // ExponentLetter: Leave
|
|
a = 0xabcdef; // HexDigit: Lower
|
|
a = 0XF0 | 0B1; // Prefix: Upper
|
|
a = 1ull; // Suffix: Lower
|
|
```
|
|
|
|
## Spacing in Empty Constructs
|
|
|
|
### SpaceInEmptyBraces
|
|
|
|
Specifies when to insert a space in empty braces.
|
|
|
|
**Type:** `SpaceInEmptyBracesStyle` **Since:** v22 **Note:** Replaces deprecated `SpaceInEmptyBlock` option
|
|
|
|
**Values:**
|
|
|
|
- `Always` - Always insert a space in empty braces
|
|
- `Block` - Only insert a space in empty blocks (functions, classes, lambdas)
|
|
- `Never` - Never insert a space in empty braces
|
|
|
|
**Example:**
|
|
|
|
`Always`:
|
|
|
|
```cpp
|
|
void f() { }
|
|
class Unit { };
|
|
auto a = [] { };
|
|
int x{ };
|
|
```
|
|
|
|
`Block`:
|
|
|
|
```cpp
|
|
void f() { }
|
|
class Unit { };
|
|
auto a = [] { };
|
|
int x{}; // No space in initializer braces
|
|
```
|
|
|
|
`Never`:
|
|
|
|
```cpp
|
|
void f() {}
|
|
class Unit {};
|
|
auto a = [] {};
|
|
int x{};
|
|
```
|
|
|
|
**Note:** This option does not apply to initializer braces if `Cpp11BracedListStyle` is not `Block`.
|
|
|
|
## Penalty System
|
|
|
|
These options control clang-format's internal penalty system for choosing formatting. Higher values make clang-format less likely to choose that formatting.
|
|
|
|
### PenaltyBreakAssignment
|
|
|
|
Penalty for breaking around assignment operator.
|
|
|
|
**Type:** `Unsigned`
|
|
|
|
### PenaltyBreakBeforeFirstCallParameter
|
|
|
|
Penalty for breaking before first call parameter.
|
|
|
|
**Type:** `Unsigned`
|
|
|
|
### PenaltyBreakBeforeMemberAccess
|
|
|
|
Penalty for breaking before a member access operator (`.` or `->`).
|
|
|
|
**Type:** `Unsigned` **Since:** v20
|
|
|
|
Controls how reluctant clang-format is to break before member access operators. Higher values make it less likely to break.
|
|
|
|
**Example:**
|
|
|
|
With lower penalty:
|
|
|
|
```cpp
|
|
object
|
|
->member
|
|
->anotherMember();
|
|
```
|
|
|
|
With higher penalty:
|
|
|
|
```cpp
|
|
object->member->anotherMember();
|
|
```
|
|
|
|
### PenaltyBreakComment
|
|
|
|
Penalty for breaking inside comment.
|
|
|
|
**Type:** `Unsigned`
|
|
|
|
### PenaltyBreakFirstLessLess
|
|
|
|
Penalty for breaking before first `<<`.
|
|
|
|
**Type:** `Unsigned`
|
|
|
|
### PenaltyBreakOpenParenthesis
|
|
|
|
Penalty for breaking after open parenthesis.
|
|
|
|
**Type:** `Unsigned`
|
|
|
|
### PenaltyBreakScopeResolution
|
|
|
|
Penalty for breaking after scope resolution operator (`::`).
|
|
|
|
**Type:** `Unsigned` **Since:** v18
|
|
|
|
Controls how reluctant clang-format is to break after `::` in qualified names. Higher values make it less likely to break.
|
|
|
|
**Example:**
|
|
|
|
With lower penalty:
|
|
|
|
```cpp
|
|
namespace::
|
|
ClassName::
|
|
memberFunction();
|
|
```
|
|
|
|
With higher penalty:
|
|
|
|
```cpp
|
|
namespace::ClassName::memberFunction();
|
|
```
|
|
|
|
### PenaltyBreakString
|
|
|
|
Penalty for breaking string literals.
|
|
|
|
**Type:** `Unsigned`
|
|
|
|
### PenaltyBreakTemplateDeclaration
|
|
|
|
Penalty for breaking after template declaration.
|
|
|
|
**Type:** `Unsigned`
|
|
|
|
### PenaltyExcessCharacter
|
|
|
|
Penalty for each character outside column limit.
|
|
|
|
**Type:** `Unsigned`
|
|
|
|
### PenaltyIndentedWhitespace
|
|
|
|
Penalty for indented whitespace.
|
|
|
|
**Type:** `Unsigned`
|
|
|
|
### PenaltyReturnTypeOnItsOwnLine
|
|
|
|
Penalty for putting return type on its own line.
|
|
|
|
**Type:** `Unsigned`
|
|
|
|
### ShortNamespaceLines
|
|
|
|
Maximum lines for considering namespace short.
|
|
|
|
**Type:** `Unsigned`
|
|
|
|
## Raw String Formatting
|
|
|
|
### RawStringFormats
|
|
|
|
Configure formatting of raw string literals.
|
|
|
|
**Type:** `List of RawStringFormat`
|
|
|
|
**Example:**
|
|
|
|
```yaml
|
|
RawStringFormats:
|
|
- Language: TextProto
|
|
Delimiters:
|
|
- pb
|
|
- proto
|
|
EnclosingFunctions:
|
|
- PARSE_TEXT_PROTO
|
|
BasedOnStyle: Google
|
|
```
|
|
|
|
This allows formatting embedded protocol buffer text within raw strings.
|
|
|
|
## Namespace Handling
|
|
|
|
### NamespaceIndentation
|
|
|
|
Indent content in namespaces.
|
|
|
|
**Type:** `NamespaceIndentationKind` **Values:**
|
|
|
|
- `None` - Don't indent
|
|
- `Inner` - Indent inner namespaces only
|
|
- `All` - Indent all namespaces
|
|
|
|
**Example:**
|
|
|
|
`None`:
|
|
|
|
```cpp
|
|
namespace out {
|
|
namespace in {
|
|
class foo {};
|
|
}
|
|
}
|
|
```
|
|
|
|
`Inner`:
|
|
|
|
```cpp
|
|
namespace out {
|
|
namespace in {
|
|
class foo {};
|
|
}
|
|
}
|
|
```
|
|
|
|
`All`:
|
|
|
|
```cpp
|
|
namespace out {
|
|
namespace in {
|
|
class foo {};
|
|
}
|
|
}
|
|
```
|
|
|
|
### NamespaceMacros
|
|
|
|
Macros that behave like namespace declarations.
|
|
|
|
**Type:** `List of Strings`
|
|
|
|
## Fine-Tuning
|
|
|
|
### PPIndentWidth
|
|
|
|
Indentation width for preprocessor statements.
|
|
|
|
**Type:** `Integer` **Default:** Uses `IndentWidth`
|
|
|
|
Separate from `IndentPPDirectives`, this controls the width when indenting.
|
|
|
|
## When to Use Advanced Options
|
|
|
|
1. **Penalties**: Only adjust if default formatting doesn't match preferences
|
|
2. **Experimental Features**: Use with caution in production code
|
|
3. **Deprecated Options**: Migrate to newer equivalents
|
|
4. **Special Cases**: Handle edge cases in complex codebases
|
|
|
|
## Tips
|
|
|
|
1. **Start Simple**: Begin with predefined styles and common options
|
|
2. **Test Thoroughly**: Advanced options can have unexpected interactions
|
|
3. **Document Choices**: Explain why specific advanced options are used
|
|
4. **Monitor Changes**: Watch for behavioral changes in new clang-format versions
|
|
5. **Penalty Tuning**: Only adjust penalties as a last resort after trying other options
|
|
|
|
## Debugging Formatting
|
|
|
|
To understand why clang-format makes certain choices:
|
|
|
|
```bash
|
|
# See effective configuration
|
|
clang-format --dump-config file.cpp
|
|
|
|
# Verbose output (if available in your version)
|
|
clang-format --verbose file.cpp
|
|
|
|
# Check specific formatting
|
|
clang-format --style="{BasedOnStyle: llvm, ColumnLimit: 100}" --dry-run file.cpp
|
|
```
|
|
|
|
## See Also
|
|
|
|
- [Breaking & Line Wrapping](02-breaking.md) - Core breaking options
|
|
- [Comments & Misc](08-comments.md) - Common miscellaneous options
|
|
- [Quick Reference](quick-reference.md) - Complete working examples
|
|
- [Full Style Options Reference](complete/clang-format-style-options.md)
|
|
|
|
---
|
|
|
|
[← Prev: Comments](08-comments.md) | [Back to Index](index.md) | [Quick Reference](quick-reference.md)
|