Skip to main content

dive_syntax/
kind.rs

1//! Token and node kinds of the concrete syntax tree.
2
3/// Defines [`SyntaxKind`] and the table used to convert raw `u16` values back.
4macro_rules! syntax_kinds {
5    ($($(#[doc = $doc:literal])* $name:ident),* $(,)?) => {
6        /// The kind of a token or node in the concrete syntax tree.
7        ///
8        /// Token kinds come first, then node kinds. The numeric values are an
9        /// implementation detail and are not stable across versions.
10        #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
11        #[repr(u16)]
12        #[allow(non_camel_case_types, reason = "rust-analyzer style SCREAMING_CASE kinds")]
13        pub enum SyntaxKind {
14            $($(#[doc = $doc])* $name),*
15        }
16
17        impl SyntaxKind {
18            /// Every kind, indexed by its raw value.
19            const ALL: &'static [SyntaxKind] = &[$(SyntaxKind::$name),*];
20
21            /// The kind's name, for tree dumps and JSON output.
22            #[must_use]
23            pub fn name(self) -> &'static str {
24                match self {
25                    $(SyntaxKind::$name => stringify!($name)),*
26                }
27            }
28        }
29    };
30}
31
32syntax_kinds! {
33    // ---- Trivia -------------------------------------------------------------
34    /// Spaces, tabs, carriage returns and line feeds.
35    WHITESPACE,
36    /// A `\*` comment, up to but excluding the line terminator.
37    LINE_COMMENT,
38    /// A `(* ... *)` comment; these nest. PlusCal algorithms live here.
39    BLOCK_COMMENT,
40    /// Text before the first module header, which SANY ignores.
41    PRELUDE,
42    /// Text after the end of the top-level module, which SANY ignores.
43    TRAILER,
44
45    // ---- Module structure tokens -------------------------------------------
46    /// `---- MODULE`, the start of a module (dashes, spaces and the keyword).
47    BEGIN_MODULE,
48    /// A line of four or more dashes.
49    SEPARATOR,
50    /// A line of four or more equals signs, ending a module.
51    END_MODULE,
52    /// `--->`, the start of a SANY pragma before the module.
53    PRAGMA_START,
54
55    // ---- Keywords -----------------------------------------------------------
56    /// `ACTION` or `ACTIONS`.
57    ACTION_KW,
58    /// `ASSUME`.
59    ASSUME_KW,
60    /// `[]ASSUME`.
61    BOX_ASSUME_KW,
62    /// `ASSUMPTION` or `AXIOM`.
63    ASSUMPTION_KW,
64    /// `CASE`.
65    CASE_KW,
66    /// `CHOOSE`.
67    CHOOSE_KW,
68    /// `CONSTANT` or `CONSTANTS`.
69    CONSTANT_KW,
70    /// `ELSE`.
71    ELSE_KW,
72    /// `EXCEPT`.
73    EXCEPT_KW,
74    /// `\E`, `\exists` or `∃`.
75    EXISTS_KW,
76    /// `EXTENDS`.
77    EXTENDS_KW,
78    /// `\A`, `\forall` or `∀`.
79    FORALL_KW,
80    /// `IF`.
81    IF_KW,
82    /// `INSTANCE`.
83    INSTANCE_KW,
84    /// `LET`.
85    LET_KW,
86    /// `IN` (of `LET ... IN`).
87    IN_KW,
88    /// `LOCAL`.
89    LOCAL_KW,
90    /// `MODULE` (in `USE MODULE M` and similar).
91    MODULE_KW,
92    /// `NEW`.
93    NEW_KW,
94    /// `OTHER`.
95    OTHER_KW,
96    /// `PROPOSITION`, `LEMMA` or `COROLLARY`.
97    PROPOSITION_KW,
98    /// `SF_`.
99    SF_KW,
100    /// `\EE`.
101    TEMPORAL_EXISTS_KW,
102    /// `\AA`.
103    TEMPORAL_FORALL_KW,
104    /// `THEN`.
105    THEN_KW,
106    /// `BY`.
107    BY_KW,
108    /// `ONLY`.
109    ONLY_KW,
110    /// `DEFINE`.
111    DEFINE_KW,
112    /// `DEF` or `DEFS`.
113    DEF_KW,
114    /// `THEOREM`.
115    THEOREM_KW,
116    /// `USE`.
117    USE_KW,
118    /// `HIDE`.
119    HIDE_KW,
120    /// `HAVE`.
121    HAVE_KW,
122    /// `OBVIOUS`.
123    OBVIOUS_KW,
124    /// `OMITTED`.
125    OMITTED_KW,
126    /// `LAMBDA`.
127    LAMBDA_KW,
128    /// `TAKE`.
129    TAKE_KW,
130    /// `PROOF`.
131    PROOF_KW,
132    /// `PROVE`.
133    PROVE_KW,
134    /// `[]PROVE`.
135    BOX_PROVE_KW,
136    /// `QED`.
137    QED_KW,
138    /// `RECURSIVE`.
139    RECURSIVE_KW,
140    /// `STATE`.
141    STATE_KW,
142    /// `TEMPORAL` or `TEMPORALS`.
143    TEMPORAL_KW,
144    /// `PICK`.
145    PICK_KW,
146    /// `WITNESS`.
147    WITNESS_KW,
148    /// `SUFFICES`.
149    SUFFICES_KW,
150    /// `VARIABLE` or `VARIABLES`.
151    VARIABLE_KW,
152    /// `WF_`.
153    WF_KW,
154    /// `WITH`.
155    WITH_KW,
156
157    // ---- Punctuation --------------------------------------------------------
158    /// `,`.
159    COMMA,
160    /// `:`.
161    COLON,
162    /// `::` or `∷`.
163    COLON_COLON,
164    /// `.`.
165    DOT,
166    /// `_`.
167    UNDERSCORE,
168    /// `==` or `≜`.
169    DEF_EQ,
170    /// `(`.
171    L_PAREN,
172    /// `)`.
173    R_PAREN,
174    /// The literal `-|-`, which SANY lexes as its internal definition marker.
175    DEFBREAK_LIT,
176    /// `[`.
177    L_BRACK,
178    /// `]_`.
179    R_BRACK_UNDERSCORE,
180    /// `]`.
181    R_BRACK,
182    /// `{`.
183    L_BRACE,
184    /// `}`.
185    R_BRACE,
186    /// `<<` or `⟨`.
187    L_ANGLE,
188    /// `>>_` or `⟩_`.
189    R_ANGLE_UNDERSCORE,
190    /// `>>` or `⟩`.
191    R_ANGLE,
192    /// `!`.
193    BANG,
194    /// `->` or `→`.
195    ARROW,
196    /// `<-` or `←`.
197    LEFT_ARROW,
198    /// `|->` or `↦`.
199    MAPS_TO,
200
201    // ---- Literals and names -------------------------------------------------
202    /// A natural number: decimal digits, or `\b`, `\o`, `\h` forms.
203    NUMBER,
204    /// A string literal with its quotes.
205    STRING,
206    /// An identifier, `@`, or one of `ℕ ℤ ℝ`.
207    IDENT,
208    /// SANY's `x./\` and `x.\/` lexemes, which no production accepts.
209    BAD_JUNCTION,
210    /// A lexical error: a character or string no token matches.
211    LEX_ERROR,
212
213    // ---- Proof step numbers -------------------------------------------------
214    /// `<1>2`: a numbered step name.
215    STEP_NUMBER,
216    /// `<*>a` or `<+>a`: a step name with an implicit level.
217    STEP_IMPLICIT,
218    /// `<1>2.`: a step start followed by dots.
219    STEP_DOT,
220    /// `<1>`, `<*>` or `<+>`: a bare level.
221    STEP_BARE,
222    /// `<1>.`, `<1>*` or `<1>-`: an unnumbered step start.
223    STEP_UNNUMBERED,
224
225    // ---- Operators ----------------------------------------------------------
226    /// A prefix operator: `~ \lnot \neg ¬ ENABLED UNCHANGED SUBSET UNION DOMAIN`.
227    PREFIX_OP,
228    /// `[]` or `□`: the always operator and the `CASE` separator.
229    BOX_OP,
230    /// `<>` or `◇`.
231    DIAMOND_OP,
232    /// `-.`, the name of prefix minus.
233    NEG_DOT_OP,
234    /// A postfix operator: `' ^+ ⁺ ^* ^#`.
235    POSTFIX_OP,
236    /// An infix operator other than the specially handled ones below.
237    INFIX_OP,
238    /// `/\` or `∧` (also a conjunction-list bullet).
239    AND_OP,
240    /// `\/` or `∨` (also a disjunction-list bullet).
241    OR_OP,
242    /// `\in` or `∈`.
243    IN_OP,
244    /// `=`.
245    EQ_OP,
246    /// `-` (infix minus, and prefix minus in expressions).
247    MINUS_OP,
248    /// End of input (never appears in the tree).
249    EOF,
250
251    // ---- Nodes: module level -----------------------------------------------
252    /// The root: prelude, top-level module and trailer.
253    SOURCE_FILE,
254    /// A module, top-level or nested.
255    MODULE,
256    /// `---- MODULE Name ----`.
257    MODULE_HEADER,
258    /// The `EXTENDS` clause.
259    EXTENDS,
260    /// SANY's pragma before a module.
261    PRAGMA,
262    /// `VARIABLE(S) x, y`.
263    VARIABLE_DECL,
264    /// `CONSTANT(S) ...`.
265    CONSTANT_DECL,
266    /// `RECURSIVE ...`.
267    RECURSIVE_DECL,
268    /// `Id` or `Id(_, _)` in a declaration.
269    IDENT_DECL,
270    /// `-. _` or `~ _` in a declaration.
271    PREFIX_DECL,
272    /// `_ + _` in a declaration.
273    INFIX_DECL,
274    /// `_ ^+` in a declaration.
275    POSTFIX_DECL,
276    /// `Op(params) == expr` and the other operator definition forms.
277    OPERATOR_DEF,
278    /// `f[x \in S] == expr`.
279    FUNCTION_DEF,
280    /// `I == INSTANCE M WITH ...`.
281    MODULE_DEF,
282    /// The left-hand side `Id` or `Id(params)`.
283    IDENT_LHS,
284    /// The left-hand side `op x` of a prefix operator definition.
285    PREFIX_LHS,
286    /// The left-hand side `x op y` of an infix operator definition.
287    INFIX_LHS,
288    /// The left-hand side `x op` of a postfix operator definition.
289    POSTFIX_LHS,
290    /// `[LOCAL] INSTANCE M WITH ...` as a module unit.
291    INSTANCE,
292    /// `INSTANCE M WITH ...`.
293    INSTANTIATION,
294    /// `x <- expr` in an `INSTANCE ... WITH`.
295    SUBSTITUTION,
296    /// `ASSUME` / `ASSUMPTION` / `AXIOM` unit.
297    ASSUMPTION,
298    /// `THEOREM` / `LEMMA` / `PROPOSITION` / `COROLLARY` unit, with its proof.
299    THEOREM,
300    /// `USE` or `HIDE` (also a proof step body).
301    USE_OR_HIDE,
302    /// `MODULE M` inside `USE`, `HIDE`, `BY` or `DEF` lists.
303    MODULE_REF,
304
305    // ---- Nodes: proofs ------------------------------------------------------
306    /// A non-terminal proof: optional `PROOF` then steps ending in `QED`.
307    PROOF,
308    /// `BY ...`, `OBVIOUS` or `OMITTED`, optionally after `PROOF`.
309    TERMINAL_PROOF,
310    /// A proof step: step start token, body, optional proof.
311    PROOF_STEP,
312    /// `QED`.
313    QED_STEP,
314    /// `DEFINE` and/or definitions as a step.
315    DEF_STEP,
316    /// `HAVE expr`.
317    HAVE_STEP,
318    /// `TAKE ...`.
319    TAKE_STEP,
320    /// `WITNESS ...`.
321    WITNESS_STEP,
322    /// `PICK ... : expr`.
323    PICK_STEP,
324    /// `CASE expr` as a step.
325    CASE_STEP,
326    /// An assertion step: optional `SUFFICES`, then an expression or `ASSUME/PROVE`.
327    ASSERT_STEP,
328    /// `ASSUME ... PROVE ...`.
329    ASSUME_PROVE,
330    /// `NEW x \in S`, `CONSTANT c`, `VARIABLE v`, `STATE f` and similar.
331    NEW_DECL,
332
333    // ---- Nodes: expressions -------------------------------------------------
334    /// A possibly qualified name such as `x`, `M!Op` or `Op!1!<<`.
335    GENERAL_ID,
336    /// The `M!N!` qualification of a [`SyntaxKind::GENERAL_ID`].
337    ID_PREFIX,
338    /// One `name[(args)]!` element of an [`SyntaxKind::ID_PREFIX`].
339    ID_PREFIX_ELEMENT,
340    /// A structural subexpression selector `<<`, `>>`, `:`, `@` or a number.
341    STRUCT_OP,
342    /// `Op(args)`.
343    OP_APPLICATION,
344    /// `(arg, ...)`.
345    OP_ARGS,
346    /// A bare operator symbol passed as an argument or substituted: `F(+)`.
347    OP_REF,
348    /// A natural number literal.
349    NUMBER_LIT,
350    /// A decimal literal `1.5`.
351    DECIMAL_LIT,
352    /// A string literal.
353    STRING_LIT,
354    /// `op e` for a prefix operator.
355    PREFIX_EXPR,
356    /// `a op b`.
357    INFIX_EXPR,
358    /// `e op` for a postfix operator.
359    POSTFIX_EXPR,
360    /// `A \X B \X C` (n-ary Cartesian product).
361    CARTESIAN_PRODUCT,
362    /// `(e)`.
363    PAREN_EXPR,
364    /// `r.field`.
365    RECORD_FIELD,
366    /// `f[a, b]`.
367    FCN_APPL,
368    /// `<<a, b>>`.
369    TUPLE,
370    /// `{a, b}`.
371    SET_ENUM,
372    /// `{x \in S : P}`.
373    SET_FILTER,
374    /// `{e : x \in S}`.
375    SET_MAP,
376    /// `[x \in S |-> e]`.
377    FCN_CONSTRUCTOR,
378    /// `[S -> T]`.
379    SET_OF_FCNS,
380    /// `[a |-> 1, b |-> 2]`.
381    RECORD,
382    /// `a |-> 1` inside a record.
383    FIELD_VAL,
384    /// `[a : S, b : T]`.
385    SET_OF_RECORDS,
386    /// `a : S` inside a set of records.
387    FIELD_SET,
388    /// `[f EXCEPT ![x] = y]`.
389    EXCEPT,
390    /// `![x].y = e` inside `EXCEPT`.
391    EXCEPT_SPEC,
392    /// `[x]` or `.y` inside an [`SyntaxKind::EXCEPT_SPEC`].
393    EXCEPT_COMPONENT,
394    /// `[A]_v` or `<<A>>_v`.
395    ACTION_EXPR,
396    /// `WF_v(A)` or `SF_v(A)`.
397    FAIRNESS_EXPR,
398    /// `IF c THEN a ELSE b`.
399    IF_EXPR,
400    /// `CASE ...`.
401    CASE_EXPR,
402    /// `p -> e` inside `CASE`.
403    CASE_ARM,
404    /// `OTHER -> e` inside `CASE`.
405    OTHER_ARM,
406    /// `LET ... IN e`.
407    LET_EXPR,
408    /// The definitions of a `LET`.
409    LET_DEFS,
410    /// A bulleted `/\` list.
411    CONJ_LIST,
412    /// One `/\ e` item.
413    CONJ_ITEM,
414    /// A bulleted `\/` list.
415    DISJ_LIST,
416    /// One `\/ e` item.
417    DISJ_ITEM,
418    /// `\A x \in S : P` and `\E x \in S : P`.
419    BOUNDED_QUANT,
420    /// `\A x : P` and `\E x : P`.
421    UNBOUNDED_QUANT,
422    /// `\AA x : P` and `\EE x : P`.
423    TEMPORAL_QUANT,
424    /// `x, y \in S` or `<<x, y>> \in S`.
425    QUANT_BOUND,
426    /// `<<x, y>>` as a bound variable tuple.
427    IDENT_TUPLE,
428    /// `CHOOSE x \in S : P`.
429    CHOOSE,
430    /// `LAMBDA x, y : e`.
431    LAMBDA,
432    /// `lab :: e` (also labels on `ASSUME/PROVE`).
433    LABEL,
434    /// Tokens skipped while recovering from a syntax error.
435    ERROR,
436}
437
438impl SyntaxKind {
439    /// Converts a raw value produced by [`SyntaxKind::to_raw`] back to a kind.
440    #[must_use]
441    pub fn from_raw(raw: u16) -> Option<Self> {
442        Self::ALL.get(usize::from(raw)).copied()
443    }
444
445    /// The raw value of this kind.
446    #[must_use]
447    pub fn to_raw(self) -> u16 {
448        self as u16
449    }
450
451    /// Whether the kind is trivia (whitespace, comments, ignored text).
452    #[must_use]
453    pub fn is_trivia(self) -> bool {
454        matches!(
455            self,
456            Self::WHITESPACE
457                | Self::LINE_COMMENT
458                | Self::BLOCK_COMMENT
459                | Self::PRELUDE
460                | Self::TRAILER
461        )
462    }
463
464    /// Whether the kind is a keyword token.
465    #[must_use]
466    pub fn is_keyword(self) -> bool {
467        (Self::ACTION_KW..=Self::WITH_KW).contains(&self)
468    }
469
470    /// Whether the kind is an operator token.
471    #[must_use]
472    pub fn is_operator(self) -> bool {
473        (Self::PREFIX_OP..=Self::MINUS_OP).contains(&self)
474    }
475
476    /// Whether the kind is a node kind (as opposed to a token kind).
477    #[must_use]
478    pub fn is_node(self) -> bool {
479        self >= Self::SOURCE_FILE
480    }
481}
482
483/// The rowan language tag for TLA+.
484#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
485pub enum TlaLanguage {}
486
487impl rowan::Language for TlaLanguage {
488    type Kind = SyntaxKind;
489
490    fn kind_from_raw(raw: rowan::SyntaxKind) -> SyntaxKind {
491        // Only kinds produced by this crate are ever stored in trees, so the
492        // fallback is unreachable in practice; ERROR is the safe choice.
493        SyntaxKind::from_raw(raw.0).unwrap_or(SyntaxKind::ERROR)
494    }
495
496    fn kind_to_raw(kind: SyntaxKind) -> rowan::SyntaxKind {
497        rowan::SyntaxKind(kind.to_raw())
498    }
499}
500
501impl From<SyntaxKind> for rowan::SyntaxKind {
502    fn from(kind: SyntaxKind) -> Self {
503        rowan::SyntaxKind(kind.to_raw())
504    }
505}
506
507/// A node in the red (cursor) syntax tree.
508pub type SyntaxNode = rowan::SyntaxNode<TlaLanguage>;
509/// A token in the red (cursor) syntax tree.
510pub type SyntaxToken = rowan::SyntaxToken<TlaLanguage>;
511/// A node or a token.
512pub type SyntaxElement = rowan::SyntaxElement<TlaLanguage>;
513
514#[cfg(test)]
515mod tests {
516    use super::SyntaxKind;
517
518    #[test]
519    fn raw_round_trip() {
520        for (i, k) in SyntaxKind::ALL.iter().enumerate() {
521            assert_eq!(usize::from(k.to_raw()), i);
522            assert_eq!(SyntaxKind::from_raw(k.to_raw()), Some(*k));
523        }
524        assert_eq!(SyntaxKind::from_raw(u16::MAX), None);
525    }
526
527    #[test]
528    fn classes() {
529        assert!(SyntaxKind::WHITESPACE.is_trivia());
530        assert!(SyntaxKind::THEOREM_KW.is_keyword());
531        assert!(SyntaxKind::AND_OP.is_operator());
532        assert!(SyntaxKind::MODULE.is_node());
533        assert!(!SyntaxKind::EOF.is_node());
534    }
535}