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
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
/// C++ Syntax Kind Enumeration
///
/// This enum defines all possible syntax node types in the C++ syntax tree.
/// It is used to build the Abstract Syntax Tree (AST), and each enum value represents a kind of syntax structure.
///
/// Note: Only syntax structures are included here, not lexical tokens.
/// Tokens are defined in CppTokenKind.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[repr(u16)]
pub enum CppSyntaxKind {
/// Empty node, used for initialization
None,
// ========== Top-level Syntax Structure ==========
/// Translation unit - the root node of a C++ source file
/// Contains all top-level declarations and definitions
TranslationUnit,
// ========== Declarations ==========
/// Function declaration - only the function signature, no implementation
/// e.g.: int func(int x);
FunctionDecl,
/// Function definition - complete definition with implementation
/// e.g.: int func(int x) { return x + 1; }
FunctionDef,
/// Class declaration - forward declaration
/// e.g.: class MyClass;
ClassDecl,
/// Class definition - complete class definition
/// e.g.: class MyClass { ... };
ClassDef,
/// Struct declaration - forward declaration
/// e.g.: struct MyStruct;
StructDecl,
/// Struct definition - complete struct definition
/// e.g.: struct MyStruct { ... };
StructDef,
/// Union declaration - forward declaration
/// e.g.: union MyUnion;
UnionDecl,
/// Union definition - complete union definition
/// e.g.: union MyUnion { ... };
UnionDef,
/// Enum declaration - forward declaration
/// e.g.: enum Color : int;
EnumDecl,
/// Enum definition - complete enum definition
/// e.g.: enum Color { Red, Green, Blue };
EnumDef,
/// Enum class declaration - forward declaration (C++11)
/// e.g.: enum class MyEnum;
EnumClassDecl,
/// Enum class declaration - forward declaration (C++11)
/// e.g.: enum class MyEnumClass;
EnumClassDef,
/// Typedef declaration - type alias
/// e.g.: typedef int MyInt;
TypedefDecl,
/// Using declaration - introduce a name
/// e.g.: using std::cout;
UsingDecl,
/// Using directive - introduce an entire namespace
/// e.g.: using namespace std;
UsingDirective,
/// Namespace declaration
/// e.g.: namespace MyNamespace { ... }
NamespaceDecl,
/// Variable declaration
/// e.g.: int x, y = 5;
VariableDecl,
/// Field declaration - class/struct member variable
/// e.g.: class A { int member; };
FieldDecl,
/// Class/struct/union body - the `{ ... }` part of a class definition, including access
/// specifier sections and member declarations.
/// e.g.: the `{ public: void f(); }` in `class A { public: void f(); };`
ClassBody,
/// Template declaration
/// e.g.: template<typename T> class MyClass;
TemplateDecl,
/// Template specialization - specialized version of a template
/// e.g.: template<> class MyClass<int> { ... };
TemplateSpecialization,
/// Concept declaration (C++20)
/// e.g.: template<typename T> concept Copyable = ...;
ConceptDecl,
/// A **requires-clause**: `requires` followed by a constraint expression.
/// e.g.: the `requires C<T>` of `template <typename T> void f(T t) requires C<T>;`
///
/// A node of its own rather than a bare `requires` token in the declaration, because the clause is what a
/// consumer asks a declaration for when it wants to know whether the declaration is *constrained* — and
/// finding it by scanning the declaration's tokens means re-implementing where a clause may appear, which is
/// four places.
RequiresClause,
// ========== Statements ==========
/// Compound statement - block of statements in braces
/// e.g.: { statement1; statement2; }
CompoundStat,
/// Expression statement - expression ending with a semicolon
/// e.g.: x = 5;
ExpressionStat,
/// Declaration statement - declaration in statement position
/// e.g.: int x = 5;
DeclStat,
/// if statement - conditional statement
/// e.g.: if (condition) statement
IfStat,
/// else-if clause - else if part of if statement
ElseIfStat,
/// else clause - else part of if statement
/// e.g.: else statement
ElseStat,
/// switch statement - multi-branch selection
/// e.g.: switch (expr) { ... }
SwitchStat,
/// case label - case branch in switch
/// e.g.: case 1:
CaseStat,
/// default label - default branch in switch
/// e.g.: default:
DefaultStat,
/// while loop - pre-test loop
/// e.g.: while (condition) statement
WhileStat,
/// do-while loop - post-test loop
/// e.g.: do statement while (condition);
DoWhileStat,
/// for loop - traditional for loop
/// e.g.: for (init; condition; increment) statement
ForStat,
/// Range-based for loop (C++11)
/// e.g.: for (auto& item : container) statement
RangeForStat,
/// break statement - exit loop or switch
BreakStat,
/// continue statement - continue to next loop iteration
ContinueStat,
/// return statement - function return
/// e.g.: return expression;
ReturnStat,
/// goto statement - unconditional jump
/// e.g.: goto label;
GotoStat,
/// label statement - target for goto
/// e.g.: label:
LabelStat,
/// try block - exception handling
/// e.g.: try { ... }
TryStat,
/// catch block - exception catch
/// e.g.: catch (Exception& e) { ... }
CatchStat,
/// throw statement - throw exception
/// e.g.: throw exception;
ThrowStat,
/// Empty statement - single semicolon
/// e.g.: ;
EmptyStat,
// ========== Expressions ==========
/// Literal expression - numbers, strings, chars, etc.
/// e.g.: 42, "hello", 'c', true, nullptr
LiteralExpr,
/// Identifier expression - variable/function names
/// e.g.: variable, function
IdentifierExpr,
/// Parenthesized expression
/// e.g.: (expression)
ParenExpr,
/// Unary expression - unary operator
/// e.g.: -x, !flag, ++i, *ptr, &var
UnaryExpr,
/// Binary expression - binary operator
/// e.g.: a + b, x == y, ptr->member
BinaryExpr,
/// Ternary expression - conditional operator
/// e.g.: condition ? true_expr : false_expr
TernaryExpr,
/// Function call expression
/// e.g.: func(args), obj.method(args)
CallExpr,
/// Member access expression - dot operator
/// e.g.: obj.member
MemberExpr,
/// Arrow access expression - arrow operator
/// e.g.: ptr->member
ArrowExpr,
/// Index expression - array/container access
/// e.g.: arr[index], map[key]
IndexExpr,
/// Cast expression - type cast
/// e.g.: (int)x, static_cast<int>(x)
CastExpr,
/// sizeof expression - get size of type or expression
/// e.g.: sizeof(int), sizeof(expression)
SizeofExpr,
/// A C11 **generic selection** — `_Generic(expr, type: value, …, default: value)`.
///
/// Its own node rather than a call, because an association is a `type: expression` pair and nothing about a call's
/// argument list is that shape. It had no rule at all until a macro's body range was fixed and the corpus's
/// `CORPUS_TYPE_NAME(value)` began to reach the parser with its real text: four syntax errors on a file gcc compiles
/// cleanly, `expected }, but get string literal` among them.
GenericSelectionExpr,
/// typeid expression - get type info
/// e.g.: typeid(int), typeid(expression)
TypeidExpr,
/// new expression - dynamic memory allocation
/// e.g.: new int, new int[10], new MyClass()
NewExpr,
/// delete expression - free dynamic memory
/// e.g.: delete ptr, delete[] arr
DeleteExpr,
/// this expression - current object pointer
/// e.g.: this, this->member
ThisExpr,
/// Throw expression (C++17 made it one; it has always been one in operand position).
/// e.g.: `x = throw 1;`, `cond ? throw E{} : 2`
///
/// Distinct from [`CppSyntaxKind::ThrowStat`], which is the *statement* form `throw e;`. The two are
/// different nodes because they are different constructs: a rethrow is only a statement, and a throw whose
/// value is used is only an expression.
ThrowExpr,
/// A **requires-expression** (C++20): `requires (params) { requirements }`.
/// e.g.: `requires(T t) { t.f(); }`, `requires { typename T::type; }`
///
/// It is a `bool`-valued expression — the one expression whose *body* is a list of things that must be
/// well-formed rather than a computation.
RequiresExpr,
/// One requirement inside a requires-expression's body.
/// e.g.: `t.f()`, `typename T::type`, `{ t.f() } noexcept -> int`, `requires C<T>`
///
/// The four kinds share a node because they share a position and a delimiter: each is one requirement up to
/// its `;`. What differs is inside, and a consumer that needs the difference reads the tokens it holds.
Requirement,
/// Lambda expression (C++11)
/// e.g.: [capture](params) -> return_type { body }
LambdaExpr,
/// A lambda's capture list: the `[` … `]` of a lambda expression.
/// e.g.: the `[&x, y = 1]` of `[&x, y = 1](int z) { return x + y + z; }`
///
/// A node of its own because the captures are what a reader of a lambda needs first — which names it takes,
/// and whether it takes them by reference — and finding them inside the raw tokens of the whole lambda means
/// re-implementing the list's grammar.
LambdaCaptureList,
/// One capture of a lambda's capture list.
/// e.g.: `x`, `&x`, `this`, `*this`, `=`, `&`, `...`, `x = std::move(y)`
LambdaCapture,
/// Initializer list expression (C++11)
/// e.g.: {1, 2, 3}, {.x = 1, .y = 2}
InitListExpr,
/// Designated initializer expression (C++20)
/// e.g.: {.member = value}
DesignatedInitExpr,
/// Compound literal expression
/// e.g.: (struct Point){.x = 1, .y = 2}
CompoundLiteralExpr,
/// A pack expansion (C++11): a pattern followed by `...`.
/// e.g.: `args...` in `g(args...)`, `Ts...` in `std::tuple<Ts...>`, `(ts + ...)` in a fold expression
///
/// A node of its own because the `...` is not an operator applied to an operand — it is the marker that says
/// the operand stands for a *pack*, expanded once per element. `UnaryExpr(..., args)` would say the
/// ellipsis is a prefix operator, which is the one reading that is certainly wrong.
///
/// The declaration half of packs needs no node of its own: `Ts... ts` is a declarator, and its `...` is part
/// of the declaration. This is the *use* half, where the pattern is an expression or a type-id.
PackExpansionExpr,
/// The `...` operand of a **fold expression** (C++17).
/// e.g.: the `...` of `(ts + ...)`, `(... && bs)`, `(f(args) + ...)`
///
/// The `...` in a fold is not an expansion marker sitting after a pattern — it is an *operand*, the one
/// standing for "the rest of the pack". It is read as a primary expression so that the ordinary binary rule
/// builds `BinaryExpr(ts, +, FoldExpr(...))`, which leaves the pattern the user wrote intact as the left
/// side instead of turning the whole fold into an operator-less blob.
///
/// A node rather than a bare token inside the binary expression, because an expression grammar's operands
/// are nodes everywhere else and a consumer walking the tree for the pack would otherwise have to inspect
/// raw tokens of one specific operator.
FoldExpr,
// ========== Types ==========
/// Built-in type - C++ basic types
/// e.g.: int, char, float, double, bool, void
BuiltinType,
/// Pointer type - pointer to another type
/// e.g.: int*, char*, MyClass*
PointerType,
/// Reference type - lvalue reference
/// e.g.: int&, const std::string&
ReferenceType,
/// Rvalue reference type (C++11)
/// e.g.: int&&, std::string&&
RValueReferenceType,
/// Array type - fixed size array
/// e.g.: int[10], char[256]
ArrayType,
/// A structured binding's name list (C++17).
/// e.g.: the `[a, b]` of `auto [a, b] = pair;`
///
/// A node of its own because the names it introduces are *not* declarators: each one binds a
/// sub-object of whatever initializes the whole, and none of them has a type of its own. A
/// consumer looking for "the things this declaration declares" has to find them here or it
/// reports one variable named `[a, b]`.
StructuredBinding,
/// Function type - function signature type
/// e.g.: int(int, int), void()
FunctionType,
/// Qualified type - const/volatile qualified type
/// e.g.: const int, volatile double
QualifiedType,
/// Template type - template instantiation
/// e.g.: std::vector<int>, MyTemplate<T>
TemplateType,
/// **A named type that is not a template instantiation** — a class, alias or typedef written as a name.
///
/// e.g.: `String` in `struct String;`, `Widget` in `Widget w;`, `std::string` in `std::string s;`
///
/// # Why this exists rather than a bare `NameExpr`
///
/// [`CppDeclSpecifierSeq::get_type_name`] used to say *"a plain name is a `NameExpr` child, while a template-id
/// is wrapped in a `TemplateType`"* — and the implementation wrapped **both**, which is why `String` in
/// `struct String;` read as a template instantiation with no `<` anywhere.
///
/// Unwrapping the plain case is not enough, and the tests say why: `TemplateType`'s presence is **load-bearing
/// inside the parser**, not only for readers. `parse_decl_specifier_seq_with` asks
/// `events_contain_any(specifiers_from, &[TemplateType])` to answer *"has a type name been written yet?"* — the
/// question that decides whether the second name in
/// `extern "C++" __PURE_APPDOMAIN_GLOBAL _CRTDATA2_IMPORT istream cin;` joins the type or declares `cin`. A
/// version that removed the wrapper for plain names failed
/// `the_last_name_in_a_specifier_sequence_is_the_type`, `a_forward_declaration_declares_the_name`,
/// `a_member_whose_type_is_preceded_by_macros_is_named_by_its_declarator` and
/// `a_word_in_a_body_that_expands_to_nothing_does_not_stop_the_reading` — four contracts, all from one node
/// kind no longer being there.
///
/// So the name still gets a node of its own, and that node says what it is instead of overstating it. Every
/// place that asked for `TemplateType` to mean "a type name was written" now asks for both.
NamedType,
/// auto type (C++11)
/// e.g.: auto x = 5;
AutoType,
/// decltype type (C++11)
/// e.g.: decltype(expr)
DecltypeType,
/// typename type - type name in template
/// e.g.: typename T::value_type
TypenameType,
// ========== Template Related ==========
/// Template parameter - parameter in template declaration
/// e.g.: template<typename T> T
TemplateParameter,
/// Template argument - argument in template instantiation
/// e.g.: std::vector<int> int
TemplateArgument,
/// Template argument list - argument list in template instantiation
/// e.g.: <int, double>
TemplateArgumentList,
/// Template parameter list - parameter list in template declaration
/// e.g.: <typename T, int N>
TemplateParameterList,
// ========== Preprocessor Directives ==========
/// #include directive - include header file
/// e.g.: #include <iostream>
IncludeDirective,
/// #define directive - macro definition
/// e.g.: #define MAX_SIZE 100
DefineDirective,
/// #undef directive - undefine macro
/// e.g.: #undef MAX_SIZE
UndefDirective,
/// #ifdef directive - conditional compilation (defined)
/// e.g.: #ifdef DEBUG
IfdefDirective,
/// #ifndef directive - conditional compilation (not defined)
/// e.g.: #ifndef HEADER_H
IfndefDirective,
/// #if directive - conditional compilation
/// e.g.: #if VERSION > 2
IfDirective,
/// #else directive - else branch of conditional compilation
/// e.g.: #else
ElseDirective,
/// #elif directive - else if branch of conditional compilation
/// e.g.: #elif VERSION == 1
ElifDirective,
/// #endif directive - end of conditional compilation
/// e.g.: #endif
EndifDirective,
/// #pragma directive - compiler-specific directive
/// e.g.: #pragma once
PragmaDirective,
/// #error directive - compile-time error
/// e.g.: #error "Unsupported platform"
ErrorDirective,
/// #warning directive - compile-time warning
/// e.g.: #warning "Deprecated function"
WarningDirective,
/// #line directive - line number control
/// e.g.: #line 100 "file.cpp"
LineDirective,
// ========== Specifiers and Qualifiers ==========
/// Access specifier - class member access control
/// e.g.: public:
PublicAccess,
/// e.g.: private:
PrivateAccess,
/// e.g.: protected:
ProtectedAccess,
/// Storage class specifier - variable/function storage
/// e.g.: static int x;
StaticSpec,
/// e.g.: extern int x;
ExternSpec,
/// e.g.: thread_local int x;
ThreadLocalSpec,
/// e.g.: mutable int x;
MutableSpec,
/// Function specifier - special function attributes
/// e.g.: inline void func();
InlineSpec,
/// e.g.: virtual void func();
VirtualSpec,
/// e.g.: explicit MyClass(int);
ExplicitSpec,
/// e.g.: constexpr int func();
ConstexprSpec,
/// e.g.: void func() noexcept;
NoexceptSpec,
/// Alignment specifier - the `alignas` of `alignas(16) struct A { };`
/// e.g.: alignas(16), alignas(int), alignas(64)
///
/// A node of its own rather than a bare keyword because the parentheses are its *payload* and the two
/// spellings hold different things: a constant expression (`alignas(16)`) or a type-id (`alignas(int)`),
/// and a type-id here may be a template-id or qualified name. A consumer asking "what alignment?" reads the
/// node; the token alone says only that some alignment was asked for.
AlignasSpec,
/// CV qualifier - const/volatile qualifier for types
/// e.g.: const int x;
ConstQual,
/// e.g.: volatile int x;
VolatileQual,
/// e.g.: restrict int* ptr; (C extension)
RestrictQual, // ========== Other Syntax Elements ==========
/// Function parameter - single parameter in function definition/declaration
/// e.g.: int func(int param) param
Parameter,
/// Parameter list - function parameter list
/// e.g.: (int x, double y, char* z)
ParameterList,
/// The **old-style (K&R) parameter declarations** of a function definition.
///
/// The parameters are declared *after* the parenthesis rather than inside it, so the identifiers in the
/// parenthesis are names whose types arrive later:
///
/// ```c
/// int main(argc, argv)
/// int argc;
/// char *argv[];
/// { … }
/// ```
///
/// Obsolete in C++ and deprecated in C, but ordinary in C from before 1989 — and this parser is asked to read
/// C. The declarations are ordinary `Declaration`s inside this node, so a consumer finds the parameters' types
/// without re-reading tokens.
OldStyleParameterList,
/// Argument list - function call argument list
/// e.g.: func(arg1, arg2, arg3)
ArgumentList,
/// A **macro invocation used as a statement or a definition**: `BOOL_OPTION(flag)`,
/// `IF_EXIST(op) { … }`, `TEST(A, B) { … }`.
///
/// ```text
/// MacroCall
/// NameExpr the macro's name
/// ArgumentList its arguments, as raw balanced tokens — a macro's parameters are pasted into
/// identifiers and types alike, so nothing here is interpreted
/// CompoundStat …and the block, when the macro's body is a statement or a definition
/// ```
///
/// A macro is expanded in translation phase 4, so by the time the grammar runs an invocation has left behind
/// whatever the macro expanded to — a specifier, a statement, a whole block, or nothing. This node is how the
/// parser says "this is a macro, and its meaning is not knowable here" **visibly**, instead of dressing the
/// tokens up as a declaration that happens to have a strange shape. A consumer can then skip it, highlight it,
/// or ask for the macro's definition elsewhere, and a reader of the tree can see which parts of a file are
/// untouched by the grammar.
///
/// Only the shapes with no other reading are read this way, and a *statement* is only read this way when the
/// name is one this file `#define`s — see `parser::MacroNames`.
MacroCall,
// ========== Legacy Support (for migration compatibility) ==========
/// Parameter list (legacy name for compatibility)
ParamList,
/// Call argument list (legacy name for compatibility)
CallArgList,
/// Parameter name (legacy for compatibility)
ParamName,
/// Local name (legacy for compatibility)
LocalName,
/// Name expression - identifier reference
/// e.g.: variable_name
NameExpr,
/// Do statement - rarely used in C++ but exists
/// e.g.: do { ... } while(condition);
DoStat,
/// Else-if clause in conditional statement
/// e.g.: else if (condition) { ... }
ElseIfClauseStat,
/// Else clause in conditional statement
/// e.g.: else { ... }
ElseClauseStat,
/// Function statement/definition
/// e.g.: void func() { ... }
FuncStat,
/// Local function definition (for compatibility)
LocalFuncStat,
/// Local variable declaration/definition
/// e.g.: int local_var = 5;
LocalStat,
/// Assignment statement
/// e.g.: x = y + z;
AssignStat,
/// Call expression as statement
/// e.g.: func(); (function call as standalone statement)
CallExprStat,
/// Global variable/function declaration
GlobalStat,
/// Repeat statement (for compatibility - maps to do-while)
RepeatStat,
/// Specialized call expressions (for migration compatibility)
/// Assert function call
AssertCallExpr,
/// Error function call
ErrorCallExpr,
/// Require function call (for compatibility)
RequireCallExpr,
/// Type function call
TypeCallExpr,
/// Setmetatable function call (for compatibility)
SetmetatableCallExpr,
/// Closure expression - lambda expression
/// e.g.: [capture](params) { body }
ClosureExpr,
// ========== Table-like structures (for compatibility with legacy code) ==========
/// Empty table/initializer list expression
/// e.g.: {} or std::initializer_list<T>{}
TableEmptyExpr,
/// Array-like table expression
/// e.g.: {1, 2, 3} or std::array<int, 3>{1, 2, 3}
TableArrayExpr,
/// Object-like table expression
/// e.g.: {.x = 1, .y = 2} (designated initializers)
TableObjectExpr,
/// Table field assignment
/// e.g.: .field = value
TableFieldAssign,
/// Table field value
/// e.g.: field in table initialization
TableFieldValue,
/// Attribute - C++11 attribute
/// e.g.: [[nodiscard]], [[deprecated]]
Attribute,
/// Attribute list - collection of attributes
/// e.g.: [[nodiscard, deprecated("use new_func instead")]]
AttributeList,
/// Initializer - variable initializer expression
/// e.g.: int x = 5; = 5
Initializer,
/// Base specifier - inheritance specifier
/// e.g.: class Derived : public Base public Base
BaseSpecifier,
/// Member initializer - constructor member initializer list
/// e.g.: MyClass() : member(value) {}
MemberInitializer,
/// Catch handler - handler in catch block
/// e.g.: catch (const std::exception& e)
CatchHandler,
/// Enumerator declaration - enum member
/// e.g.: enum Color { Red, Green, Blue }; Red
EnumeratorDecl,
// ========== Comments and Documentation ==========
/// A line comment - `//` style comment
/// e.g.: // This is a comment
LineComment,
/// Block comment - `/* */` style comment
/// e.g.: /* This is a block comment */
BlockComment,
/// A run of consecutive comments, parsed as documentation.
///
/// The node a consumer of the tree actually walks. One node covers **one or more** adjacent
/// comments, because that is the unit a doc comment is written in:
///
/// ```text
/// /// Computes the area.
/// /// @param r the radius.
/// /// @returns the area.
/// ```
///
/// Three comments, one document. Splitting them into three nodes would push the job of grouping
/// them back onto every consumer.
///
/// A `Comment` node also covers ordinary `//` and `/* */` comments — the ones with nothing
/// documentation-shaped in them. They are kept in the tree for losslessness, and giving them the
/// same node kind means a consumer walking comments sees all of them rather than having to look
/// in two places. They simply contain no `DocCommand` children.
///
/// Constructs inside it: [`DocCommand`](Self::DocCommand), [`DocInline`](Self::DocInline).
DocComment,
/// One Doxygen command and its arguments: `@brief x`, `@param[in] x desc`, `@returns y`.
///
/// A single node kind driven by the command's *name* rather than one node kind per command, so
/// the grammar is table-driven: adding `@since` is a row in a table, not a new parse function
/// and a new kind. The name is the [`CppTokenKind::DocCommandName`] token directly inside.
DocCommand,
/// The body of a documentation comment: everything that is not part of a command.
///
/// One of these wraps the whole comment's content, and a second kind of the same name carries a
/// command's payload — see [`DocCommandBody`](Self::DocCommandBody). The wrapper exists so that a
/// consumer can iterate a comment's commands without also seeing the comment's own delimiters and
/// line markers.
DocCommentBody,
/// A command's payload: everything from the end of the command's arguments to the end of its
/// line, or to the end of a block comment.
///
/// Separate from [`DocCommand`](Self::DocCommand) so that a consumer asking "what does `@param x`
/// say about `x`?" has one node to read, whether the payload is a phrase or three paragraphs.
DocCommandBody,
/// A named argument of a command, such as the `x` of `@param[in] x`.
///
/// Its own node because it is the part a cross-reference needs: matching `@param x` against the
/// parameter named `x` is a lookup by this node's text, and doing that from a token stream means
/// re-implementing the argument grammar at every use.
DocCommandArg,
/// An inline reference inside a description: `@ref Foo`, `@p name`, `#member`, `::scope::name`.
///
/// Kept as a node rather than plain text because it is a link: it names a declaration, and that
/// is what "go to definition" from inside a comment needs.
DocInline,
/// A code block: the lines between `@code` and `@endcode`.
///
/// Its contents are *not* parsed as documentation. That is the whole point — code inside a code
/// block is full of `@`, `<` and `\`, and treating it as prose turns a snippet into nonsense.
DocCodeBlock,
// ========== Declarations (grammar detail) ==========
/// A preprocessor directive, from `#` to the end of its logical line: `#include <vector>`,
/// `#define MAX(a, b) ...`, `#if`, `#endif`.
///
/// Directives are *not* removed from the tree. They have to stay for the CST to be lossless, and
/// more importantly the branches of a conditional compilation block contain real declarations
/// that an editor must still parse and index — the preprocessor layer, which knows which branch
/// is selected, is built on top of this node rather than underneath it.
PreprocessorDirective,
// ========== Modules (C++20) ==========
// `module` and `import` are *contextual* keywords: the standard calls them "identifier with
// special meaning", so they stay usable as ordinary names and the lexer hands them over as
// identifiers. The parser decides from the text, in the contexts where the meaning is special.
/// A module declaration: `export? module name : partition? ;`.
///
/// e.g.: `export module my.mod;`, `module my.mod:part;`
ModuleDecl,
/// An import declaration: `export? import name | :partition | <header> ;`.
///
/// e.g.: `import std;`, `export import :part;`, `import <iostream>;`
ImportDecl,
/// An export block: `export { declaration-seq? }`.
ExportBlock,
/// The dotted name of a module.
///
/// e.g.: the `my.mod` in `export module my.mod;`
ModuleName,
/// A module partition, including its leading `:`.
///
/// e.g.: the `:part` in `module my.mod:part;`
ModulePartition,
/// A header unit name in an import: `<iostream>` or `"local.h"`.
HeaderName,
/// A global module fragment: `module ;` followed by preprocessing directives.
///
/// This is where `#include` is still allowed inside a module unit, because the preprocessor runs
/// before the module machinery and a header that uses configuration macros has to be included
/// rather than imported.
GlobalModuleFragment,
/// A private module fragment: `module : private ;` followed by declarations that importers of
/// the module cannot see.
PrivateModuleFragment,
// A declaration in C++ is `decl-specifier-seq init-declarator-list ;`, and every one of those
// three pieces is optional depending on the declaration, so they each get their own node
// rather than being flattened into the declaration. The AST layer needs the boundaries: "what
// is the type of this declaration" and "what is its name" are the two most common questions
// asked of a C++ tree, and neither can be answered from a flat token list.
/// One complete declaration, whatever its kind.
///
/// e.g.: `int x = 1;`, `void f();`, `MyClass obj;`, `static constexpr int n = 5;`
Declaration,
/// The `decl-specifier-seq`: type specifiers, cv-qualifiers, storage class and function
/// specifiers, in any order.
///
/// e.g.: `int`, `static const`, `virtual inline`, `std::vector<int>`, `auto`
DeclSpecifierSeq,
/// An `init-declarator`: a declarator plus an optional initializer or function body.
///
/// e.g.: `x = 1`, `*p`, `f(int a)`, `arr[10]`
InitDeclarator,
/// A `declarator`: the part that names the entity, possibly wrapped in pointers, references,
/// arrays, function parameter lists and template argument lists.
///
/// e.g.: `x`, `*p`, `&r`, `arr[10]`, `f(int)`, `ns::C::operator+`
Declarator,
/// A `friend` declaration: `friend class X;`, `friend void f();`, `friend bool operator==(...)`.
///
/// `friend` is not a specifier of the declaration that follows it; it *is* the declaration, which
/// is why this is a separate node rather than a specifier inside the friend's own declaration.
FriendDecl,
/// A type on its own, as it appears after `sizeof`, in a cast, in a parameter or as a /// `type-id`.
///
/// e.g.: `int`, `const char*`, `std::vector<int>`
TypeId,
/// A trailing return type after `->`.
///
/// This gets its own kind rather than reusing [`CppSyntaxKind::TypeId`] because it is also the
/// declarator's "this is a function" marker: a declarator whose events contain one can only be a
/// function, which is how a `{` after it is recognised as a body rather than an initializer.
///
/// e.g.: the `-> T*` in `auto begin() -> T*`
TrailingReturnType,
// ========== Error Recovery ==========
/// Error node - for error recovery in parsing
/// Used when the parser encounters unrecognized syntax
ErrorNode,
/// Missing node - represents a missing syntax element
/// Used for handling incomplete syntax structures
MissingNode,
// ========== The compilers' own constructs ==========
/// An **`asm` statement** — GCC's `asm volatile ("…" : … : … : …);`
///
/// ```cpp
/// __asm__ volatile ("tilerelease" ::); // amxtileintrin.h:56
/// __asm__ __volatile__ ("pconfig\n\t" : "=a" (retval) : "a" (leaf) : "cc");
/// ```
///
/// The **payload is not C++**: `"int {$}3":`, `[ret] "=r" (ret)` and `"a" (leaf)` are the compiler's own
/// operand language, which no expression or parameter rule can read. So this node keeps them **as tokens** —
/// what the file wrote, in order — the same treatment a macro invocation's arguments get, and for the same
/// reason: the text is what a consumer needs (a highlight, a hover, an asm block moved as a unit), and the
/// meaning belongs to a compiler this layer does not have.
///
/// Declared **last** among the kinds so that no other variant's discriminant moves: the raw conversion in
/// `kind/mod.rs` is a `transmute` bounded by the last variant, and renumbering it would change what a stored
/// kind means.
AsmStat,
/// The **`register` storage class** — a hint removed in C++17 and still written by C headers and by MinGW's
/// own (`_mingw.h:607`, `xmmintrin.h`).
///
/// It sits beside [`CppSyntaxKind::StaticSpec`] and the other storage-class specifiers in meaning; it is
/// declared here, at the end, only because a variant's discriminant may not move (see
/// [`CppSyntaxKind::AsmStat`]). `types::storage_or_function_specifier` is the one place that maps the token
/// to this kind, so the guard and the node cannot drift apart.
///
/// e.g.: `register int x;`, `register unsigned int r0;`
RegisterSpec,
/// **A CUDA kernel launch** — `kernel<<<grid, block, shmem, stream>>>(args)`.
///
/// Not C++ at all: `<<<` and `>>>` are lexed as `<<` `<` and `>>` `>`, and in ordinary C++ the line is three
/// shifts and a syntax error. `nvcc` reads it as the execution configuration of a call, and so does this parser
/// **when the unit is CUDA** ([`crate::ParserConfig::cuda`]) — the child sequence is:
///
/// ```text
/// <the kernel expression> the callee, as written
/// ArgumentList the configuration: 2 to 4 comma-separated expressions
/// ArgumentList the call's own arguments, when written
/// ```
///
/// Declared **last** among the kinds, for the reason [`CppSyntaxKind::AsmStat`] gives: a variant's discriminant
/// may not move, because the kind table is a `transmute` bounded by the last variant.
CudaLaunchExpr,
}