1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
//! Objc's role rows. The Halstead keyword roles (#1693), the
//! paying-construct roles — `Comparison`, `ShortCircuit`, `EagerLogical`,
//! `Ternary`, `CaseArm`, `Guard`, `NullSafe` (#1694, #1695) — the space
//! tree (#1696) and the control flow — `Branch`, `Switch`, `Loop`,
//! `Catch`, `ElseIf`, `Exit` (#1697) — and
//! the documentation rows (#1699) are declared.
use crate::role_table;
use crate::roles::c_family::{
c_doc_declarations, c_family_binary_owners, c_family_calls, c_family_comparison_payers,
c_family_decl_keywords, c_family_doc_entries, c_family_doc_gates, c_family_loops,
c_family_modifiers, c_family_primitives, c_family_short_circuit_payers, c_family_strings,
objc_conditional_kinds, objc_doc_conditionals,
};
use crate::roles::control_flow::else_if_parent_clause_gate;
use crate::{Ancestors, Node, Objc};
// The documentation gates, per dialect (#1699).
c_family_doc_gates!(with_has_body ObjcCode);
// The `DocTarget` row's conditional owners as a kind test (#1795).
objc_conditional_kinds!();
/// Whether an `implementation_definition` is one Doxygen documents —
/// not a `@synthesize` / `@dynamic` property implementation, which
/// declares nothing of its own.
fn implementation_is_not_a_property(node: &Node<'_>) -> bool {
node.child(0)
.is_some_and(|d| d.kind_id() != Objc::PropertyImplementation as u16)
}
// The chained `if` sits directly inside an `else_clause`; a nested one
// under `else { … }` sits inside the compound statement (#1697).
else_if_parent_clause_gate!(Objc, ElseClause);
/// Whether `node` is the attribute word of `@property (nonatomic, copy,
/// getter=isOn)`. The grammar has no keyword for any attribute: each is
/// an `identifier`, the first child of its `property_attribute`, so the
/// word is told from a name by position alone. The `isOn` of
/// `getter=isOn` is a later child and stays an operand, the selector it
/// names. `ObjcCode::is_primitive` keys the word by its text (#1579).
fn property_attribute_name<'a>(node: &Node<'a>, ancestors: Ancestors<'a, '_>) -> bool {
ancestors.parent(node).is_some_and(|attribute| {
attribute.kind_id() == Objc::PropertyAttribute as u16
&& attribute.start_byte() == node.start_byte()
})
}
role_table! {
lang: Objc;
// A C `call_expression` (aliased to `CallExpression2`) or a message
// send `[receiver method]`.
Call { owns [..c_family_calls!(), MessageExpression] }
// ObjC has no raw string literal; `@"…"` parses as `AT` + a plain
// `string_literal`, so the family's two kinds apply.
StringLit { owns [..c_family_strings!()] }
// The Objective-C binary operators are one `binary_expression`
// kind, emitted under two production paths (`BinaryExpression`,
// `BinaryExpression2`) and told apart by the `operator` field, so
// each row's owners are gated on that field holding one of its
// payers (`roles/c_family.rs` has the lists and their derivations).
// A bare `<` / `>` also opens a `generic_specifier`, a
// `protocol_reference_list` (`id<NSCopying>`), a
// `parameterized_arguments` and an `argument_list`, which is what
// the payers' `under BinaryExpression` gate excludes.
Comparison {
owns [..c_family_binary_owners!()]
pays [..c_family_comparison_payers!()]
project "operator"
}
ShortCircuit {
owns [..c_family_binary_owners!()]
pays [..c_family_short_circuit_payers!()]
project "operator"
}
EagerLogical { absent "Objective-C's `&` / `|` / `^` are bitwise" }
// The `conditional_expression` owns the ternary and its `?` pays,
// ungated: the grammar spells a bare `?` in no other production. The
// GNU elision `a ?: b` is the same node with its `consequence` field
// empty, which the ABC slot walker reads by field (#1102).
Ternary {
owns [ConditionalExpression]
pays [QMARK]
project "operator"
}
NullSafe { absent "Objective-C has no optional navigation or null coalescing (nil-messaging is \
semantics, not syntax)" }
// A `case_statement` is the grammar's node for a `case X:` label
// and a `default:` label alike; the arm owns a decision when it
// holds the `case` keyword, which pays — one per label, so a
// fall-through run `case 2: case 3:` is two. The `default` keyword
// is the fallback and pays nothing (lesson 11, #469); Halstead
// bills it as the keyword it is through the byte-less arm.
CaseArm {
owns [CaseStatement(holds_payer)]
pays [Case]
excludes [Default "the fallback label, no decision (lesson 11, #469)"]
}
Guard { absent "Objective-C has no guard clause on a case or a function head" }
// The C family's control flow (#1697): the one-kind rows are spelled
// inline and the loop list is the family's fragment
// (`roles/c_family.rs`); the `ElseIf` gate is emitted beside this
// table. ObjC's own shape:
// `Catch` pays at the owner — its `@catch` is the `ATcatch` keyword,
// so the handler node is what pays, as the cyclomatic reading always
// had it — and `@throw` (the `throw_statement` node) joins C's
// `return`, without C++'s coroutine exits.
Branch { owns [IfStatement] pays [If] }
Switch { owns [SwitchStatement] }
Loop { owns [..c_family_loops!()] pays [For, While] }
Catch { owns [CatchClause] }
ElseIf { owns [IfStatement(gated_by continues_else_clause)] pays [] }
Exit { owns [ReturnStatement, ThrowStatement] }
// The shared C-family lists (`roles/c_family.rs`), so a `.m` scores
// a C declaration as a `.c` does, plus `auto` (a storage class here
// as in C) and ObjC's own (#1579): the ARC ownership qualifiers
// (`__weak`, `__strong`, `__block`, …) and `__bridge` casts, the
// nullability qualifiers in all three spellings (`nullable`,
// `_Nullable`, `__nullable`), `__kindof`, the `__covariant` /
// `__contravariant` variance of a generic parameter, the `out` /
// `inout` / `bycopy` / `byref` / `oneway` method-type qualifiers,
// the `@public` / `@private` / `@protected` / `@package` ivar
// visibility labels and the `@optional` / `@required` protocol
// section labels. Each is the keyword leaf of an unclassified
// `storage_class_specifier` / `type_qualifier` /
// `protocol_qualifier` / `visibility_specification` or sits bare in
// its parent, so it bills once; none has a numeric-suffix alias.
// `in` is the sixth method-type qualifier, but one kind with the
// fast-enumeration `in`, so it is not a modifier here. A property
// attribute has no keyword kind at all — its word is an
// `identifier` told by position, hence the gate.
//
// Not here: the Apple SDK macros this grammar also lists as storage
// classes and qualifiers (`NS_INLINE`, `FOUNDATION_EXPORT`,
// `IBOutlet`, `__unused`, `__ptrauth_objc_*`, …), as Mozcpp's
// `MOZ_*` macros are, since each annotates a declaration and a `.c`
// file parses the same spelling as a name; and GNU's `__real` /
// `__imag`, complex-part operators the grammar misfiles as
// qualifiers. A variable named `nullable` parses as the qualifier
// before a MISSING name and bills it, as C's `int noreturn = 1;`
// bills `noreturn`: the grammar decides that, not the row.
Modifier {
owns [
..c_family_modifiers!(),
Auto, Const2, Nullable, Nullable2, Nullable3, NullableResult, NullUnspecified,
Nonnull2, Autoreleasing, Block, Strong, UnsafeUnretained, Weak, Bridge,
BridgeRetained, BridgeTransfer, Kindof, Covariant, Contravariant, Out, Inout,
Bycopy, Byref, Oneway, ATpublic, ATprivate, ATprotected, ATpackage, AToptional,
ATrequired, Identifier(gated_by property_attribute_name),
]
}
// The shared list plus ObjC's class and protocol declarations
// (#1552), each the leaf of an unclassified `class_interface` /
// `class_implementation` / `protocol_declaration`. `@class Fwd;`
// needs no entry: it parses as an `@` token, billed on its own, and
// a separate `class` leaf, so the directive already bills one
// operator.
DeclKeyword { owns [..c_family_decl_keywords!(), ATinterface, ATimplementation, ATprotocol] }
// The shared list plus `_Complex` / `__complex`, a type keyword this
// grammar files as a qualifier.
Primitive { owns [..c_family_primitives!(), Complex, Complex2] }
// Both aliased `function_definition` ids (#285) and a
// `method_definition` — the `@implementation`-side method with a
// body; the `@interface`-side `method_declaration` has none and is
// no function — are the callables. A block literal (`^{ … }`) is a
// closure that opens no space, as the C++ lambda. `@implementation`
// carries the method bodies and opens `Class`; `@interface` and
// `@protocol` declare without bodies and open `Interface`.
FuncOpener {
owns [
FunctionDefinition(callable opens Function),
FunctionDefinition2(callable opens Function),
MethodDefinition(callable opens Function),
]
}
Closure { owns [BlockLiteral] }
Container {
owns [
TranslationUnit(opens Unit),
ClassImplementation(opens Class),
ClassInterface(opens Interface),
ProtocolDeclaration(opens Interface),
]
}
// A `@property` declaration, direct in an `@interface` /
// `@implementation` / `@protocol` or grouped under a
// `@required` / `@optional` marker, and an instance variable in
// the `{ … }` block, which the consumer counts by declarator and
// reads the access section of.
Member { owns [PropertyDeclaration, InstanceVariable] }
// The one comment kind, a `DocComment` owner under Doxygen's marker
// gate (#1699).
Comment { owns [Comment] }
DocComment { owns [Comment(text_gated_by opens_with_doxygen_marker no_chain)] }
Docstring { absent "Objective-C documents with comments, not string literals" }
// What Doxygen documents from a doc block before it: the entries of
// `roles/c_family.rs`'s fragment
// plus Objective-C's containers (a protocol's `@optional` /
// `@required` section included), property, methods and instance
// variable, and every
// preprocessor conditional holding an entry in any branch
// (`conditional_declares`, memoised). The `ERROR` node holding an
// entry is the Checker's clause. Most targets are outside the
// space-tree rows — a macro, a typedef, an enumerator, a field, a
// conditional — the parity exceptions `roles/doc_tests/parity.rs` records.
DocTarget {
owns [
..c_family_doc_entries!(),
..c_doc_declarations!(),
ClassInterface,
ClassImplementation,
ProtocolDeclaration,
QualifiedProtocolInterfaceDeclaration,
PropertyDeclaration,
MethodDeclaration,
MethodDefinition,
InstanceVariable,
ImplementationDefinition(gated_by implementation_is_not_a_property no_chain),
..objc_doc_conditionals!(),
]
}
DocRunOpener { absent "Doxygen attaches every block to an entry or the file; none documents by its own content" }
DocRunDirective { absent "Doxygen reads no directive comment" }
DocBodyResidual { absent "Doxygen reads every block in a body as the function's in-body description; nothing withholds one" }
}