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}