Skip to main content

big_code_analysis_ast/roles/
cpp.rs

1//! Cpp's role rows. The Halstead keyword roles (#1693), the
2//! paying-construct roles — `Comparison`, `ShortCircuit`, `EagerLogical`,
3//! `Ternary`, `CaseArm`, `Guard`, `NullSafe` (#1694, #1695) — the space
4//! tree (#1696) and the control flow — `Branch`, `Switch`, `Loop`,
5//! `Catch`, `ElseIf`, `Exit` (#1697) — and
6//! the documentation rows (#1699) are declared.
7
8use crate::Cpp;
9use crate::role_table;
10use crate::roles::c_family::{
11    c_family_calls, c_family_conditional_kinds, c_family_decl_keywords, c_family_doc_conditionals,
12    c_family_doc_entries, c_family_doc_gates, c_family_modifiers, c_family_primitives,
13    c_family_strings, cpp_doc_entries, cpp_family_binary_owners, cpp_family_comparison_payers,
14    cpp_family_containers, cpp_family_exits, cpp_family_func_openers, cpp_family_gates,
15    cpp_family_loops, cpp_family_short_circuit_payers,
16};
17use crate::roles::control_flow::else_if_parent_clause_gate;
18
19// The documentation gates, per dialect (#1699).
20c_family_doc_gates!(CppCode);
21// The `DocTarget` row's conditional owners as a kind test (#1795).
22c_family_conditional_kinds!(Cpp);
23
24cpp_family_gates!(Cpp);
25// The chained `if` sits directly inside an `else_clause`; a nested one
26// under `else { … }` sits inside the compound statement (#1697).
27else_if_parent_clause_gate!(Cpp, ElseClause);
28
29role_table! {
30    lang: Cpp;
31    Call { owns [..c_family_calls!()] }
32    // `R"(…)"` joins the family's two: it is one string-like token to
33    // `find` and the dump (#398, the peer of #391 for Rust).
34    StringLit { owns [..c_family_strings!(), RawStringLiteral] }
35    // The C++ binary operators are one `binary_expression` kind (the
36    // aliased `BinaryExpression2` at the pinned grammar; the unsuffixed
37    // id is the never-emitted pre-alias) plus the fold, told apart by
38    // the `operator` field, so each row's owners are gated on that
39    // field holding one of its payers and each payer on applying its
40    // operator (`roles/c_family.rs` has both lists and their
41    // derivations — #1448, #1522, #1525, #1533). A `requires` clause or
42    // expression is compile-time and its operators decide nothing; the
43    // rows do not know that, because a parenthesised constraint parses
44    // as an ordinary `binary_expression` and only the root crate's
45    // `ConstraintReach` can see the clause above it. The consumers read
46    // the rows *under* that reach.
47    Comparison {
48        owns [..cpp_family_binary_owners!()]
49        pays [..cpp_family_comparison_payers!()]
50        project "operator"
51    }
52    ShortCircuit {
53        owns [..cpp_family_binary_owners!()]
54        pays [..cpp_family_short_circuit_payers!()]
55        project "operator"
56    }
57    EagerLogical { absent "C++'s `&` / `|` / `^` are bitwise; `and` / `or` are the lazy spellings" }
58    // The `conditional_expression` owns the ternary and its `?` pays,
59    // ungated: the grammar spells a bare `?` in no other production. The
60    // GNU elision `a ?: b` is the same node with its `consequence` field
61    // empty, which the ABC slot walker reads by field (#1102).
62    Ternary {
63        owns [ConditionalExpression]
64        pays [QMARK]
65        project "operator"
66    }
67    NullSafe { absent "C++ has no optional navigation or null coalescing" }
68    // A `case_statement` is the grammar's node for a `case X:` label
69    // and a `default:` label alike; the arm owns a decision when it
70    // holds the `case` keyword, which pays — one per label, so a
71    // fall-through run `case 2: case 3:` is two. The `default` keyword
72    // is the fallback and pays nothing (lesson 11, #469); Halstead
73    // bills it as the keyword it is through the byte-less arm.
74    CaseArm {
75        owns [CaseStatement(holds_payer)]
76        pays [Case]
77        excludes [Default "the fallback label, no decision (lesson 11, #469)"]
78    }
79    Guard { absent "C++ has no guard clause on a case or a function head" }
80    // The C family's control flow (#1697): the one-kind rows are spelled
81    // inline, the loop and exit lists are the two C++ grammars' own
82    // fragments (`cpp_family_loops!`, `cpp_family_exits!` in
83    // `roles/c_family.rs`), so Mozcpp is this table under other ids. The `ElseIf`
84    // gate is emitted beside this table. `Catch` pays at the `catch`
85    // keyword, which is where this dialect differs from ObjC.
86    Branch { owns [IfStatement] pays [If] }
87    Switch { owns [SwitchStatement] }
88    Loop { owns [..cpp_family_loops!()] pays [For, While] }
89    Catch { owns [CatchClause] pays [Catch] }
90    ElseIf { owns [IfStatement(gated_by continues_else_clause)] pays [] }
91    Exit { owns [..cpp_family_exits!()] }
92    // The shared C-family lists (`roles/c_family.rs`) plus C++'s own
93    // modifiers: `virtual`, `mutable`, `constinit`, `consteval`,
94    // `explicit`, `friend`, the access specifiers, the `override` /
95    // `final` virt-specifiers and the `noexcept` of an exception
96    // specification. Each is the keyword leaf of an unclassified wrapper
97    // (`virtual_specifier`, `access_specifier`,
98    // `explicit_function_specifier`, the `noexcept` node that `Noexcept`
99    // names and `Noexcept2` is the leaf of) or sits bare in its
100    // declaration (`virtual`, `friend`), so each bills once. `override`
101    // and `final` are contextual: used as a name (`int override = 1;`)
102    // they parse as an `identifier`, so they need no gate. `auto` is
103    // not here: in C++ it is a placeholder type, not a storage class,
104    // and the grammar emits it only under `placeholder_type_specifier`.
105    Modifier {
106        owns [
107            ..c_family_modifiers!(),
108            Virtual, Mutable, Constinit, Consteval, Explicit, Friend, Public, Private,
109            Protected, Override, Final, Noexcept2,
110        ]
111    }
112    // The shared list plus `class`, `namespace`, `template`, `typename`
113    // and `using` (#1552, #1557), each the leaf of an unclassified
114    // wrapper (`class_specifier`, `namespace_definition`,
115    // `template_declaration`, `type_parameter_declaration`,
116    // `alias_declaration` / `using_declaration`). `enum class` holds two
117    // of these leaves and bills both. A template-parameter `class` is
118    // the synonym of `typename`, so the two spellings of
119    // `template <class T>` score alike.
120    DeclKeyword { owns [..c_family_decl_keywords!(), Class, Namespace, Template, Typename, Using] }
121    Primitive { owns [..c_family_primitives!()] }
122    // The shared C++ openers and containers (`roles/c_family.rs`); the
123    // lambda is a closure that opens no space.
124    FuncOpener { owns [..cpp_family_func_openers!()] }
125    Closure { owns [LambdaExpression] }
126    Container { owns [..cpp_family_containers!()] }
127    // A `field_declaration` in a class body — a data member, or a
128    // bodiless member function the method consumer tells apart by its
129    // declarator (#1300). Which it is, and the access section it sits
130    // in, is the consumers' reading.
131    Member { owns [FieldDeclaration] }
132    // The one comment kind, a `DocComment` owner under Doxygen's marker
133    // gate (#1699).
134    Comment { owns [Comment] }
135    DocComment { owns [Comment(text_gated_by opens_with_doxygen_marker no_chain)] }
136    Docstring { absent "C++ documents with comments, not string literals" }
137    // What Doxygen documents from a doc block before it: the entries of
138    // `roles/c_family.rs`'s fragment, and every
139    // preprocessor conditional holding an entry in any branch
140    // (`conditional_declares`, memoised). The `ERROR` node holding an
141    // entry is the Checker's clause. Most targets are outside the
142    // space-tree rows — a macro, a typedef, an enumerator, a field, a
143    // conditional — the parity exceptions `roles/doc_tests/parity.rs` records.
144    DocTarget {
145        owns [
146            ..c_family_doc_entries!(),
147            ..cpp_doc_entries!(),
148            ..c_family_doc_conditionals!(),
149        ]
150    }
151    DocRunOpener { absent "Doxygen attaches every block to an entry or the file; none documents by its own content" }
152    DocRunDirective { absent "Doxygen reads no directive comment" }
153    DocBodyResidual { absent "Doxygen reads every block in a body as the function's in-body description; nothing withholds one" }
154}