Initial commit

2025-11-29 18:49:58 +08:00
commit 5007abf04b
89 changed files with 44129 additions and 0 deletions
--- a/skills/clang-format/references/09-advanced.md
+++ b/skills/clang-format/references/09-advanced.md
@@ -0,0 +1,557 @@
+# 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)