Skip to main content

oneyaml_syntax/tree/
kind.rs

1//! What each element of the syntax tree is.
2
3/// The kind of a syntax tree element: an interior **node** or a leaf
4/// **token** ([`SyntaxKind::is_token`]).
5///
6/// Tokens cover source bytes, and in document order they tile the source:
7/// every byte belongs to exactly one token. A token may be
8/// zero-width only when it is the text of an empty scalar
9/// ([`SyntaxKind::PlainScalar`]) or the text of an [`SyntaxKind::Error`]
10/// that points at a position ([`SyntaxKind::ErrorText`]). Nodes cover the
11/// bytes of their tokens; a node's span runs from its first token to its
12/// last.
13///
14/// Stored as one byte per element.
15#[non_exhaustive]
16#[repr(u8)]
17#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
18pub enum SyntaxKind {
19    // ------------------------------------------------------------ nodes
20    /// The whole input (`l-yaml-stream`, production 211); always the root.
21    /// Holds documents and the bytes between them: byte order marks,
22    /// comments, blank lines, stray `...` markers.
23    Stream,
24    /// One document (productions 206-210): its directives, its `---` and
25    /// `...` markers when written, the trivia between them and the root,
26    /// and the root node. Trivia after an implicitly ended document belongs
27    /// to the [`SyntaxKind::Stream`] (event contract C4, "ends early").
28    Document,
29    /// A block mapping (production 187): its properties, then keys, values,
30    /// `?`/`:` indicators and the trivia between them, flat.
31    BlockMapping,
32    /// A flow mapping `{ … }` (production 140).
33    FlowMapping,
34    /// A single-pair mapping inside a flow sequence, `[ a: b ]`
35    /// (productions 150-151).
36    FlowPair,
37    /// A block sequence (production 183): `-` indicators, entries, and the
38    /// trivia between them, flat.
39    BlockSequence,
40    /// A flow sequence `[ … ]` (production 137).
41    FlowSequence,
42    /// A scalar node: its properties (and block scalar header), then
43    /// exactly one scalar text token, always its last child.
44    Scalar,
45    /// An alias node: exactly one [`SyntaxKind::AliasName`] token.
46    Alias,
47    /// A syntax error (event contract C6): exactly one
48    /// [`SyntaxKind::ErrorText`] token. Read-only for the edit layer; the
49    /// bytes skipped while resynchronising follow it as
50    /// [`SyntaxKind::Skipped`] tokens.
51    Error,
52
53    // ------------------------------------------------------------ tokens
54    /// A plain scalar's text (may be zero-width: an empty node).
55    PlainScalar,
56    /// A single-quoted scalar's text, quotes included.
57    SingleQuotedScalar,
58    /// A double-quoted scalar's text, quotes included.
59    DoubleQuotedScalar,
60    /// A literal block scalar's content lines (header excluded, C5).
61    LiteralScalar,
62    /// A folded block scalar's content lines (header excluded, C5).
63    FoldedScalar,
64    /// `*name`.
65    AliasName,
66    /// A `%YAML` directive.
67    YamlDirective,
68    /// A `%TAG` directive.
69    TagDirective,
70    /// A reserved directive.
71    ReservedDirective,
72    /// `---` of an explicit document start.
73    DocumentStartMarker,
74    /// `...` ending a document.
75    DocumentEndMarker,
76    /// `...` that ends no document (e.g. at the start of a stream).
77    StrayDocumentEndMarker,
78    /// `{`.
79    FlowMappingOpen,
80    /// `}`.
81    FlowMappingClose,
82    /// `[`.
83    FlowSequenceOpen,
84    /// `]`.
85    FlowSequenceClose,
86    /// U+FEFF between documents.
87    ByteOrderMark,
88    /// A run of spaces and/or tabs.
89    Whitespace,
90    /// One line break (`\n`, `\r\n`, or `\r`).
91    LineBreak,
92    /// `#` to the end of the line.
93    Comment,
94    /// `-` block sequence entry indicator.
95    SequenceEntry,
96    /// `?` mapping key indicator.
97    MappingKey,
98    /// `:` mapping value indicator.
99    MappingValue,
100    /// `,` flow entry separator.
101    FlowEntry,
102    /// `&name` anchor property.
103    Anchor,
104    /// A tag property.
105    Tag,
106    /// A block scalar header (`|`, `>-`, `|2+`, …).
107    BlockScalarHeader,
108    /// The offending bytes of an [`SyntaxKind::Error`] (may be zero-width).
109    ErrorText,
110    /// One line of bytes skipped while resynchronising after an error.
111    Skipped,
112}
113
114impl SyntaxKind {
115    /// `true` for leaf tokens, `false` for interior nodes.
116    #[must_use]
117    pub const fn is_token(self) -> bool {
118        (self as u8) >= (Self::PlainScalar as u8)
119    }
120
121    /// `true` for presentation-only tokens that carry no meaning: white
122    /// space, line breaks, comments, and byte order marks.
123    #[must_use]
124    pub const fn is_trivia(self) -> bool {
125        matches!(
126            self,
127            Self::Whitespace | Self::LineBreak | Self::Comment | Self::ByteOrderMark
128        )
129    }
130
131    /// `true` for the node kinds that hold a YAML node's content: mappings,
132    /// sequences, scalars, and aliases.
133    #[must_use]
134    pub const fn is_yaml_node(self) -> bool {
135        matches!(
136            self,
137            Self::BlockMapping
138                | Self::FlowMapping
139                | Self::FlowPair
140                | Self::BlockSequence
141                | Self::FlowSequence
142                | Self::Scalar
143                | Self::Alias
144        )
145    }
146}
147
148#[cfg(test)]
149mod tests {
150    use super::SyntaxKind;
151
152    #[test]
153    fn nodes_and_tokens() {
154        for k in [
155            SyntaxKind::Stream,
156            SyntaxKind::Document,
157            SyntaxKind::BlockMapping,
158            SyntaxKind::FlowMapping,
159            SyntaxKind::FlowPair,
160            SyntaxKind::BlockSequence,
161            SyntaxKind::FlowSequence,
162            SyntaxKind::Scalar,
163            SyntaxKind::Alias,
164            SyntaxKind::Error,
165        ] {
166            assert!(!k.is_token(), "{k:?}");
167            assert!(!k.is_trivia(), "{k:?}");
168        }
169        for k in [
170            SyntaxKind::PlainScalar,
171            SyntaxKind::Skipped,
172            SyntaxKind::Comment,
173        ] {
174            assert!(k.is_token(), "{k:?}");
175        }
176        assert!(SyntaxKind::Comment.is_trivia());
177        assert!(!SyntaxKind::Anchor.is_trivia());
178        assert!(SyntaxKind::Alias.is_yaml_node());
179        assert!(!SyntaxKind::Document.is_yaml_node());
180        assert_eq!(core::mem::size_of::<SyntaxKind>(), 1);
181    }
182}