oneyaml_syntax/event/mod.rs
1//! The public lossless event stream.
2//!
3//! The parser turns source text into a flat sequence of [`Event`]s. Two
4//! consumers read the *same* events: the tree builder, which keeps every
5//! byte, and the serde deserializer, which skips trivia and reads only the
6//! semantic events. [`check_contract`] validates every rule on this page
7//! except those listed under *Not machine-checked* below, and is run by the
8//! conformance harness on every stream, valid or not.
9//!
10//! **Uniqueness goal.** For error-free input, the rules below leave exactly one
11//! placement for every event, so one input has exactly one valid stream (up to
12//! the parse itself, which the conformance suite checks). Recovery streams are
13//! constrained by C6 but not unique: where to resynchronise is the parser's
14//! choice.
15//!
16//! # C1 — Tiling
17//!
18//! Every event carries a [`Span`] (a UTF-8 byte range into the source text).
19//! In stream order the spans **tile** the source: the first starts at `0`, each
20//! starts where the previous ended, the last ends at `source.len()`, and every
21//! boundary is a `char` boundary. Concatenating the covered slices reproduces
22//! the input byte for byte. Trivia is never zero-width.
23//!
24//! # C2 — Bytes agree with kinds
25//!
26//! | Event | Bytes |
27//! |-----------------------------------------|----------------------------------------------|
28//! | `StreamStart`, `StreamEnd`, `Warning` | always zero-width |
29//! | `DocumentStart`/`DocumentEnd` | `---` / `...` when explicit, else zero-width |
30//! | `Directive` | `%` … end of last parameter, one line |
31//! | `MappingStart`/`MappingEnd` (flow) | `{` / `}` |
32//! | `SequenceStart`/`SequenceEnd` (flow) | `[` / `]` |
33//! | block and [`CollectionStyle::FlowPair`] starts/ends | zero-width |
34//! | `Scalar` | the scalar's text, including quotes; see C5 |
35//! | `Alias` | `*name` |
36//! | `Error` | offending bytes on one line (may be empty) |
37//! | [`TriviaKind`] | as documented on each variant |
38//!
39//! Every **line break** in the source is covered either by a
40//! [`TriviaKind::LineBreak`] event or lies inside a `Scalar` span (multi-line
41//! flow scalars and block scalar content). No other event contains one.
42//!
43//! Payload meaning agrees with the covered bytes. Names, tags, directive
44//! parameters, and scalar values are *read from* those bytes by the
45//! accessors ([`Sourced::anchor`], [`Sourced::tag`], [`Sourced::alias_name`],
46//! [`Sourced::directive`], [`Sourced::value`]), so they agree by construction;
47//! what an event stores (property positions, a block header's chomping,
48//! indentation indicator, and span) must match the bytes it points at.
49//! A shorthand tag's suffix contains no `!` and no flow indicator (`ns-tag-char`,
50//! production 40), so its handle/suffix split is unique; anchor and alias names
51//! are `ns-anchor-char+` (production 102): printable, no space, tab, line
52//! break, byte order mark, or flow indicator.
53//!
54//! # C3 — Structure
55//!
56//! `StreamStart` is first, `StreamEnd` last. Documents nest in the stream;
57//! nodes (`Scalar`, `Alias`, `MappingStart`, `SequenceStart`) nest in documents
58//! and collections. A document holds **exactly one** node (an empty document
59//! holds a zero-width empty plain scalar), a mapping an even number of nodes
60//! (key, value, …), a [`CollectionStyle::FlowPair`] mapping exactly two.
61//! Directives appear only between documents, only before the first document or
62//! after one ended with `...` (productions 210-211), and must be followed by
63//! an explicit `---`. An implicit document start is allowed only for the first
64//! document or after a document ended with `...`.
65//!
66//! **Properties.** An anchor or tag is covered by a [`TriviaKind::Anchor`] /
67//! [`TriviaKind::Tag`] event, and its meaning is carried **only** by the
68//! [`Properties`] of the next node event ([`Event::properties`],
69//! [`Sourced::anchor`], [`Sourced::tag`]), whose property spans must equal the
70//! trivia spans. Consumers read meaning from the node event, never from
71//! trivia. Aliases carry no properties.
72//!
73//! # C4 — Placement: "hug the content"
74//!
75//! Zero-width structural events sit as close to content as possible, so that
76//! **no node's range begins or ends with trivia**:
77//!
78//! * **Starts late.** A zero-width start (implicit `DocumentStart`, block
79//! collection start, `FlowPair` start) sits immediately before the first byte
80//! of its first child: the next event is a semantic event or an
81//! anchor/tag/indicator/block-header trivia event, never whitespace, a line
82//! break, or a comment.
83//! * **Ends early.** A zero-width end (implicit `DocumentEnd`, block or
84//! `FlowPair` collection end) sits immediately after the last byte of its last
85//! child: the previous event is never trivia.
86//! * **Empty nodes** are zero-width plain scalars. Exactly one position is
87//! valid, the first of these that applies:
88//! 1. immediately after the node's **last property** (`a: !!null`, `- &x`);
89//! 2. immediately after its **introducing indicator**: `---` for a document,
90//! `-` for a block sequence entry, `?` for an explicit key, `:` for a
91//! value;
92//! 3. for a **value with no `:`** (`? a`, `{a, b: c}`, `[ ? a ]`),
93//! immediately after its key node's last event;
94//! 4. for an **empty key without `?`** (`: v`, `{ : v}`), immediately before
95//! its `:`.
96//!
97//! No other empty node exists in error-free input (an implicit document or
98//! a flow sequence entry is never empty without properties). A repair node
99//! (C6 R2) sits immediately after its `Error` instead.
100//!
101//! *Why:* every run of comments, blank lines, and indentation then lies
102//! *between* nodes at the outermost level it can, preceded by the complete set
103//! of collections it closes and followed by the complete set it opens. Each
104//! comment-attachment rule (document header vs. first-node leading comment,
105//! same-line trailing comment, collection footer vs. next sibling's leading
106//! comment, document footer) becomes a decision over one flat gap, using the
107//! columns of the closing and opening nodes, instead of hunting trivia at
108//! several nesting depths. Header rule 1 (comments before `---`) and rule 2/3
109//! (blank line before the first node) are directly visible because the
110//! implicit `DocumentStart` comes *after* leading comments.
111//!
112//! Warnings are ignored when judging placement.
113//!
114//! # C5 — Block scalars
115//!
116//! The header (`|`, `>-`, `|2+`, …) is a [`TriviaKind::BlockScalarHeader`]
117//! event; its meaning is carried by the scalar event as a [`BlockHeader`]
118//! ([`Event::block_header`]) whose span equals the trivia span. After the header come optional
119//! whitespace and comment, then the header line's `LineBreak`; the scalar span
120//! starts right after that break and covers the content lines, including
121//! their indentation and line breaks:
122//!
123//! * [`Chomping::Keep`]: through **all** trailing empty lines (no empty line
124//! may directly follow the span);
125//! * [`Chomping::Strip`] / [`Chomping::Clip`]: through the line break of the
126//! last non-empty line; trailing empty lines are trivia after the scalar.
127//!
128//! With content indentation `n`, an *empty line* is at most `n` spaces followed
129//! by a break (`l-empty`, production 70); a *content line* has at least `n`
130//! spaces followed by more text (at `n = 0`, a `---`/`...` marker is not
131//! content). The span never stops before a content line that follows it
132//! (after any empty lines), and never contains a less-indented non-empty
133//! line. All three break styles (`\n`, `\r\n`, `\r`) separate lines.
134//!
135//! **End of input.** The span ends at a line break, or at end of input on a
136//! content line. A final unterminated line of at most `n` spaces (e.g. the
137//! trailing space in `|+\n a\n `) is *not* part of the scalar: it is
138//! `Whitespace` trivia after it, whatever the chomping. A final unterminated
139//! line of more than `n` spaces is content.
140//!
141//! Trailing comment lines are always trivia after the scalar. A block scalar
142//! with no content is zero-width at the start of the line after the header
143//! (or at end of input).
144//!
145//! # C6 — Diagnostics and recovery
146//!
147//! [`EventKind::Warning`] is zero-width, carries a [`Severity::Warning`]
148//! diagnostic, and follows the event it concerns. [`EventKind::Error`] carries
149//! a [`Severity::Error`] diagnostic. Recovery obeys:
150//!
151//! * **R1 — Same structure.** Error streams satisfy every C1–C5 rule; consumers
152//! need no special cases for well-nesting.
153//! * **R2 — Repair by synthesis.** The parser completes the structure with
154//! zero-width events: a missing node becomes an empty plain scalar (carrying
155//! any pending properties) placed immediately after its `Error`; an
156//! unclosed collection gets a zero-width end (for flow collections, allowed
157//! only after an error inside it); a document gets an implicit end. An
158//! `Error` after a block scalar header **abandons** the header (e.g. a bad
159//! content line, suite 5LLU): `Skipped` trivia may follow, the repair is an
160//! empty plain scalar, and no block scalar may claim that header.
161//! * **R3 — Errors are not nodes.** An `Error` event never fills a node slot;
162//! it annotates the position where the problem was detected, before the
163//! synthesized events that repair it. The tree builder turns it plus the
164//! skipped bytes into a read-only error region.
165//! * **R4 — Line-granular skipping.** Bytes skipped during resynchronisation
166//! are [`TriviaKind::Skipped`] events (only after an error), one per line,
167//! with the line breaks as `LineBreak` trivia. `Error` and `Skipped` spans
168//! never contain a line break.
169//! * **R5 — Honest prefix.** The semantic events before the first `Error` are
170//! what the parser was sure of; a strict consumer stops at the first `Error`.
171//! Placement rule "ends early" does not apply to collections containing an error.
172//!
173//! # Not machine-checked
174//!
175//! [`check_contract`] validates structural consistency, not parse
176//! correctness. It does **not** check:
177//!
178//! * that an `Error` sits where the problem actually is (R3), or that a
179//! `Warning` follows the event it concerns (C6); only their widths,
180//! severities, and the placement of repairs are checked;
181//! * multi-line scalar values (folding, escapes) and double-quoted values;
182//! tag resolution (`Tag::resolved` vs `%TAG`); block scalar
183//! `content_indent` detection and the indentation of the parent node;
184//! * lexical classification that needs the grammar, e.g. that a plain
185//! scalar contains no `: ` or ` #`, or that a key is a legal implicit key.
186//!
187//! The conformance harness's tree comparison covers these.
188//!
189//! # Representation
190//!
191//! An [`Event`] is 48 bytes on 64-bit targets and owns no heap memory
192//! except a diagnostic. Everything that can be read from the source is
193//! read from it on demand, so events are cheap to produce, move, and
194//! store:
195//!
196//! * **Values are lazy.** A scalar event stores its style (and, for a block
197//! scalar, its header), not its value; [`Sourced::value`] decodes the
198//! covered bytes (folding, escapes, chomping) when asked, borrowing from
199//! the source whenever the value is a slice of it. The parser has
200//! already validated the bytes, so decoding a stream's own scalar
201//! against its own source always succeeds.
202//! * **Names are lazy.** Anchor, tag, alias, and directive text is sliced
203//! from the source by the accessors; a tag is resolved (`%TAG` prefix,
204//! `%XX` escapes) by [`Sourced::tag`].
205//! * **Positions are relative.** A node event stores its properties' and
206//! block header's positions as 32-bit offsets back from its own start;
207//! an input where such an offset exceeds `u32::MAX` (only possible past
208//! 4 GiB) falls back to a boxed absolute form, with the same meaning.
209//! The span is therefore private: [`Event::span`] reads it.
210//!
211//! # Reading names and values
212//!
213//! Reading needs the source text, and pairing an event with the wrong text
214//! would quietly read the wrong bytes. So `Event` itself has no public
215//! reader: every read goes through [`Sourced`], an event together with the
216//! source it was parsed from, and only the parser makes one. The pull
217//! parser ([`crate::parser::Events`]) yields `Sourced` events; the
218//! collected stream ([`EventList`]) keeps its source and hands out
219//! `Sourced` views of its events. A mismatched pair cannot be built
220//! (the tree builder and the deserializer read the same bytes).
221//! Values still borrow from the source.
222//!
223//! # Recursion
224//!
225//! The stream is flat: nesting is expressed by start/end pairs, never by nested
226//! values, so derived `Debug`/`PartialEq`/`Clone`/`Hash` cannot recurse on input.
227//! Streams are produced by [`crate::parser::events`] (pulled one
228//! event at a time) or collected by [`crate::parser::parse`].
229
230mod contract;
231mod node;
232mod sourced;
233
234use std::borrow::Cow;
235use std::marker::PhantomData;
236
237use oneyaml_core::{Diagnostic, Span};
238
239#[cfg(doc)]
240use oneyaml_core::Severity;
241
242pub use contract::{ContractError, Violation, check_contract, check_tiling};
243pub use node::NodeInfo;
244pub use sourced::{EventList, IntoSourced, Sourced, SourcedIter};
245
246/// One event of the lossless event stream.
247///
248/// `'a` is the lifetime of the source text the event was parsed from. The
249/// event itself holds no reference (see *Representation* in the module
250/// docs); names and values are read through [`Sourced`], which pairs it
251/// with that text ([`Sourced::value`], [`Sourced::tag`], …).
252#[derive(Clone, Debug, PartialEq, Eq, Hash)]
253pub struct Event<'a> {
254 kind: EventKind,
255 span: Span,
256 source: PhantomData<&'a str>,
257}
258
259impl<'a> Event<'a> {
260 /// Creates an event.
261 ///
262 /// A node event's [`NodeInfo`] stores positions relative to the start
263 /// of the span it was built for; build node events with
264 /// [`Event::scalar`], [`Event::mapping_start`], and
265 /// [`Event::sequence_start`], or with a `NodeInfo` made for this span.
266 #[must_use]
267 pub const fn new(kind: EventKind, span: Span) -> Self {
268 Self {
269 kind,
270 span,
271 source: PhantomData,
272 }
273 }
274
275 /// A scalar event covering `span`, with properties at absolute
276 /// positions and, for `Literal`/`Folded`, its header.
277 #[must_use]
278 pub fn scalar(
279 span: Span,
280 style: ScalarStyle,
281 props: Properties,
282 block: Option<BlockHeader>,
283 ) -> Self {
284 let info = NodeInfo::new(span.start, props, block);
285 Self::new(EventKind::Scalar { style, info }, span)
286 }
287
288 /// A mapping start event covering `span`, with properties at absolute
289 /// positions.
290 #[must_use]
291 pub fn mapping_start(span: Span, style: CollectionStyle, props: Properties) -> Self {
292 let info = NodeInfo::new(span.start, props, None);
293 Self::new(EventKind::MappingStart { style, info }, span)
294 }
295
296 /// A sequence start event covering `span`, with properties at absolute
297 /// positions.
298 #[must_use]
299 pub fn sequence_start(span: Span, style: CollectionStyle, props: Properties) -> Self {
300 let info = NodeInfo::new(span.start, props, None);
301 Self::new(EventKind::SequenceStart { style, info }, span)
302 }
303
304 /// What happened.
305 #[must_use]
306 pub const fn kind(&self) -> &EventKind {
307 &self.kind
308 }
309
310 /// The event's kind, consuming it (e.g. to take a diagnostic).
311 #[must_use]
312 pub fn into_kind(self) -> EventKind {
313 self.kind
314 }
315
316 /// The source bytes this event covers (see C1).
317 #[must_use]
318 pub const fn span(&self) -> Span {
319 self.span
320 }
321
322 /// The source text this event covers, or `None` if the span is out of
323 /// bounds or not on `char` boundaries for `source`. Crate-private: the
324 /// public reads go through [`Sourced`], which pairs an event with its
325 /// own source (see *Reading* in the module docs).
326 #[must_use]
327 pub(crate) fn source<'s>(&self, source: &'s str) -> Option<&'s str> {
328 source.get(self.span.start..self.span.end)
329 }
330
331 /// `true` for [`EventKind::Trivia`]: presentation-only bytes that a
332 /// meaning-only consumer (serde) skips.
333 #[must_use]
334 pub const fn is_trivia(&self) -> bool {
335 matches!(self.kind, EventKind::Trivia(_))
336 }
337
338 /// `true` for [`EventKind::Error`].
339 #[must_use]
340 pub const fn is_error(&self) -> bool {
341 matches!(self.kind, EventKind::Error(_))
342 }
343
344 /// `true` for [`EventKind::Warning`].
345 #[must_use]
346 pub const fn is_warning(&self) -> bool {
347 matches!(self.kind, EventKind::Warning(_))
348 }
349
350 /// The diagnostic of an `Error` or `Warning` event.
351 #[must_use]
352 pub fn diagnostic(&self) -> Option<&Diagnostic> {
353 match &self.kind {
354 EventKind::Error(d) | EventKind::Warning(d) => Some(d),
355 _ => None,
356 }
357 }
358
359 /// Replaces a node event's information (for the parser, which merges
360 /// properties into a collection start it already built).
361 pub(crate) fn set_info(&mut self, new: NodeInfo) {
362 if let EventKind::Scalar { info, .. }
363 | EventKind::MappingStart { info, .. }
364 | EventKind::SequenceStart { info, .. } = &mut self.kind
365 {
366 *info = new;
367 }
368 }
369
370 /// The node information of a `Scalar`, `MappingStart`, or
371 /// `SequenceStart` event.
372 #[must_use]
373 pub const fn node_info(&self) -> Option<&NodeInfo> {
374 match &self.kind {
375 EventKind::Scalar { info, .. }
376 | EventKind::MappingStart { info, .. }
377 | EventKind::SequenceStart { info, .. } => Some(info),
378 _ => None,
379 }
380 }
381
382 /// Where the node's properties are (C3); `None` for events that are not
383 /// `Scalar`, `MappingStart`, or `SequenceStart`.
384 #[must_use]
385 pub fn properties(&self) -> Option<Properties> {
386 self.node_info().map(|i| i.properties(self.span.start))
387 }
388
389 /// The node's anchor, read from `source`.
390 #[must_use]
391 pub(crate) fn anchor(&self, source: &'a str) -> Option<Anchor<'a>> {
392 crate::parser::anchor_at(source, self.properties()?.anchor?)
393 }
394
395 /// The node's tag, read and resolved from `source` (`%TAG` prefix and
396 /// `%XX` escapes, §6.9.1).
397 #[must_use]
398 pub(crate) fn tag(&self, source: &'a str) -> Option<Tag<'a>> {
399 self.tag_source(source)?.resolve()
400 }
401
402 /// The node's tag as written, not yet resolved.
403 #[must_use]
404 pub(crate) fn tag_source(&self, source: &'a str) -> Option<TagSource<'a>> {
405 let props = self.properties()?;
406 crate::parser::tag_source_at(source, props.tag?, props.tag_prefix)
407 }
408
409 /// A block scalar's header (C5).
410 #[must_use]
411 pub fn block_header(&self) -> Option<BlockHeader> {
412 match &self.kind {
413 EventKind::Scalar { info, .. } => info.block_header(self.span.start),
414 _ => None,
415 }
416 }
417
418 /// A scalar's value after escape processing, line folding, and
419 /// chomping, decoded from `source`. Borrowed from the source when the
420 /// value is a slice of it.
421 #[must_use]
422 pub(crate) fn value(&self, source: &'a str) -> Option<Cow<'a, str>> {
423 let EventKind::Scalar { style, .. } = self.kind else {
424 return None;
425 };
426 crate::parser::scalar_value(source, self.span, style, self.block_header())
427 }
428
429 /// An alias's anchor name, without `*`.
430 #[must_use]
431 pub(crate) fn alias_name(&self, source: &'a str) -> Option<&'a str> {
432 match self.kind {
433 EventKind::Alias => self.source(source)?.strip_prefix('*'),
434 _ => None,
435 }
436 }
437
438 /// A directive's meaning, read from `source`.
439 #[must_use]
440 pub(crate) fn directive(&self, source: &'a str) -> Option<DirectiveKind<'a>> {
441 match self.kind {
442 EventKind::Directive(_) => crate::parser::directive_at(source, self.span),
443 _ => None,
444 }
445 }
446}
447
448/// The kind of an [`Event`], with its payload.
449///
450/// Semantic events correspond one-to-one to the yaml-test-suite event tree
451/// (`+STR`, `+DOC`, `+MAP`, `+SEQ`, `=VAL`, `=ALI` and their ends). Values
452/// and names are not stored: [`Event`]'s accessors read them from the
453/// source. Struct-like variants are `#[non_exhaustive]`; build them with
454/// the constructor functions on this type and on [`Event`].
455#[non_exhaustive]
456#[derive(Clone, Debug, PartialEq, Eq, Hash)]
457pub enum EventKind {
458 /// Start of the stream; first event, zero-width at `0`.
459 StreamStart,
460 /// End of the stream; last event, zero-width at `source.len()`.
461 StreamEnd,
462 /// A directive (§6.8), from `%` to the end of its last parameter
463 /// ([`Sourced::directive`] reads its parameters).
464 Directive(Directive),
465 /// Start of a document (§9.1). Explicit: covers `---`; else zero-width.
466 #[non_exhaustive]
467 DocumentStart {
468 /// Whether the document began with `---`.
469 explicit: bool,
470 },
471 /// End of a document. Explicit: covers `...`; else zero-width.
472 #[non_exhaustive]
473 DocumentEnd {
474 /// Whether the document ended with `...`.
475 explicit: bool,
476 },
477 /// Start of a mapping. Flow: covers `{`; block and flow-pair: zero-width.
478 #[non_exhaustive]
479 MappingStart {
480 /// Layout.
481 style: CollectionStyle,
482 /// Where the node's properties are ([`Event::properties`]).
483 info: NodeInfo,
484 },
485 /// End of a mapping. Flow: covers `}`; block and flow-pair: zero-width.
486 MappingEnd,
487 /// Start of a sequence. Flow: covers `[`; block: zero-width.
488 #[non_exhaustive]
489 SequenceStart {
490 /// Layout ([`CollectionStyle::FlowPair`] is not valid here).
491 style: CollectionStyle,
492 /// Where the node's properties are ([`Event::properties`]).
493 info: NodeInfo,
494 },
495 /// End of a sequence. Flow: covers `]`; block: zero-width.
496 SequenceEnd,
497 /// A scalar node (see C5 for block scalars; [`Sourced::value`] decodes
498 /// its value).
499 #[non_exhaustive]
500 Scalar {
501 /// Presentation style.
502 style: ScalarStyle,
503 /// Properties and, for `Literal`/`Folded`, the header.
504 info: NodeInfo,
505 },
506 /// An alias node, covering `*name` ([`Sourced::alias_name`]).
507 Alias,
508 /// Presentation-only bytes; never zero-width.
509 Trivia(TriviaKind),
510 /// A warning (zero-width). The input is still valid.
511 Warning(Box<Diagnostic>),
512 /// A syntax error (see C6). Boxed so error-free events stay small.
513 Error(Box<Diagnostic>),
514}
515
516impl EventKind {
517 /// [`EventKind::DocumentStart`].
518 #[must_use]
519 pub const fn document_start(explicit: bool) -> Self {
520 Self::DocumentStart { explicit }
521 }
522
523 /// [`EventKind::DocumentEnd`].
524 #[must_use]
525 pub const fn document_end(explicit: bool) -> Self {
526 Self::DocumentEnd { explicit }
527 }
528
529 /// [`EventKind::MappingStart`] without properties.
530 #[must_use]
531 pub const fn mapping_start(style: CollectionStyle) -> Self {
532 Self::MappingStart {
533 style,
534 info: NodeInfo::none(),
535 }
536 }
537
538 /// [`EventKind::SequenceStart`] without properties.
539 #[must_use]
540 pub const fn sequence_start(style: CollectionStyle) -> Self {
541 Self::SequenceStart {
542 style,
543 info: NodeInfo::none(),
544 }
545 }
546
547 /// [`EventKind::Scalar`] without properties or header (a flow scalar).
548 #[must_use]
549 pub const fn scalar(style: ScalarStyle) -> Self {
550 Self::Scalar {
551 style,
552 info: NodeInfo::none(),
553 }
554 }
555
556 /// A plain [`EventKind::Scalar`] without properties.
557 #[must_use]
558 pub const fn plain() -> Self {
559 Self::scalar(ScalarStyle::Plain)
560 }
561}
562
563/// Layout of a collection.
564#[non_exhaustive]
565#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
566pub enum CollectionStyle {
567 /// Indentation-based layout (§8.2).
568 Block,
569 /// `{ }` / `[ ]` layout (§7.4).
570 Flow,
571 /// Mappings only: an implicit single-pair mapping written as an entry of a
572 /// flow sequence, e.g. `[ a: b ]` or `[ ? a : b ]` (§7.4.1, productions
573 /// 150 `ns-flow-pair` and 151 `ns-flow-pair-entry`). It has no brackets,
574 /// so its start and end are zero-width; its parent is always a flow
575 /// sequence; it holds exactly one key and one value.
576 FlowPair,
577}
578
579/// Presentation style of a scalar.
580#[non_exhaustive]
581#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
582pub enum ScalarStyle {
583 /// Unquoted.
584 Plain,
585 /// `'…'`.
586 SingleQuoted,
587 /// `"…"`.
588 DoubleQuoted,
589 /// `|` block scalar.
590 Literal,
591 /// `>` block scalar.
592 Folded,
593}
594
595/// Block scalar chomping (§8.1.1.2).
596#[non_exhaustive]
597#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
598pub enum Chomping {
599 /// `-`: final line break and trailing empty lines removed.
600 Strip,
601 /// No indicator: final line break kept, trailing empty lines removed.
602 Clip,
603 /// `+`: final line break and trailing empty lines kept.
604 Keep,
605}
606
607/// The meaning of a block scalar header, so no consumer re-parses it.
608#[non_exhaustive]
609#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
610pub struct BlockHeader {
611 /// Chomping indicator.
612 pub chomping: Chomping,
613 /// Explicit indentation indicator `1`–`9`, if written.
614 pub indent_indicator: Option<u8>,
615 /// Content indentation in spaces (explicit or auto-detected, §8.1.1.1).
616 pub content_indent: usize,
617 /// Span of the header text (equal to the header trivia event's span).
618 pub span: Span,
619}
620
621impl BlockHeader {
622 /// Creates a header payload.
623 #[must_use]
624 pub const fn new(
625 chomping: Chomping,
626 indent_indicator: Option<u8>,
627 content_indent: usize,
628 span: Span,
629 ) -> Self {
630 Self {
631 chomping,
632 indent_indicator,
633 content_indent,
634 span,
635 }
636 }
637}
638
639/// Where a node's properties (§6.9) are, as byte offsets into the source.
640/// With the source, [`Sourced::anchor`] and [`Sourced::tag`] read their
641/// meaning; this is the **only** source of it, the property trivia events
642/// carry bytes only (C3).
643#[non_exhaustive]
644#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
645pub struct Properties {
646 /// Start of `&name`, if the node has an anchor.
647 pub anchor: Option<usize>,
648 /// Start of the tag property, if the node has a tag.
649 pub tag: Option<usize>,
650 /// For a shorthand tag whose handle a `%TAG` directive declares: the
651 /// start of that directive's prefix. `None` for the default handles
652 /// `!` and `!!`, verbatim tags, and the non-specific tag `!`.
653 pub tag_prefix: Option<usize>,
654}
655
656impl Properties {
657 /// Creates properties.
658 #[must_use]
659 pub const fn new(anchor: Option<usize>, tag: Option<usize>, tag_prefix: Option<usize>) -> Self {
660 Self {
661 anchor,
662 tag,
663 tag_prefix,
664 }
665 }
666
667 /// No anchor and no tag.
668 #[must_use]
669 pub const fn none() -> Self {
670 Self::new(None, None, None)
671 }
672
673 /// `true` when there is neither an anchor nor a tag.
674 #[must_use]
675 pub const fn is_empty(&self) -> bool {
676 self.anchor.is_none() && self.tag.is_none()
677 }
678}
679
680/// An anchor property, read from the source by [`Sourced::anchor`].
681#[non_exhaustive]
682#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
683pub struct Anchor<'a> {
684 /// The anchor name, without `&`.
685 pub name: &'a str,
686 /// Span of `&name`.
687 pub span: Span,
688}
689
690impl<'a> Anchor<'a> {
691 /// Creates an anchor.
692 #[must_use]
693 pub const fn new(name: &'a str, span: Span) -> Self {
694 Self { name, span }
695 }
696}
697
698/// How a tag was written (§6.9.1).
699#[non_exhaustive]
700#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
701pub enum TagForm {
702 /// `!<uri>`.
703 Verbatim,
704 /// `!suffix`, `!!suffix`, or `!handle!suffix`.
705 Shorthand,
706 /// The lone non-specific tag `!`.
707 NonSpecific,
708}
709
710/// A tag property, read and resolved from the source by [`Sourced::tag`].
711#[non_exhaustive]
712#[derive(Clone, Debug, PartialEq, Eq, Hash)]
713pub struct Tag<'a> {
714 /// How the tag was written.
715 pub form: TagForm,
716 /// The handle as written (`!`, `!!`, `!e!`); empty for verbatim tags.
717 pub handle: &'a str,
718 /// The suffix as written; for verbatim tags, the text between `<` and `>`.
719 pub suffix: &'a str,
720 /// The full tag after `%TAG` expansion and URI unescaping (e.g.
721 /// `tag:yaml.org,2002:str`), or `!` for the non-specific tag.
722 pub resolved: Cow<'a, str>,
723 /// Span of the whole property.
724 pub span: Span,
725}
726
727impl<'a> Tag<'a> {
728 /// Creates a tag.
729 #[must_use]
730 pub const fn new(
731 form: TagForm,
732 handle: &'a str,
733 suffix: &'a str,
734 resolved: Cow<'a, str>,
735 span: Span,
736 ) -> Self {
737 Self {
738 form,
739 handle,
740 suffix,
741 resolved,
742 span,
743 }
744 }
745}
746
747/// A tag property as written, before it is resolved ([`Sourced::tag_source`],
748/// [`crate::tree::Node::tag_source`]).
749///
750/// Resolving builds the full tag text, whose `%TAG`
751/// prefix may be long. Two tags of one source with equal [`TagSource::key`]s
752/// resolve to the same text, so a consumer can resolve each distinct tag
753/// once ([`TagSource::resolve`]) and share the result; reading a
754/// `TagSource` costs only the property's own text.
755#[non_exhaustive]
756#[derive(Clone, Copy, Debug)]
757pub struct TagSource<'a> {
758 /// How the tag was written.
759 pub form: TagForm,
760 /// The handle as written (`!`, `!!`, `!e!`); empty for verbatim tags.
761 pub handle: &'a str,
762 /// The suffix as written; for verbatim tags, the text between `<` and `>`.
763 pub suffix: &'a str,
764 /// Span of the whole property (in the text it was read from).
765 pub span: Span,
766 /// The source text holding the property, and its span there.
767 src: &'a str,
768 at: Span,
769 /// Where the declaring `%TAG` prefix starts in `src`.
770 prefix: Option<usize>,
771}
772
773/// Identifies what a tag resolves to within one source: its form, handle,
774/// suffix, and the `%TAG` directive (by position) its handle names. Equal
775/// keys resolve to equal text ([`TagSource::key`]).
776///
777/// The directive is identified by the **address** of the source text
778/// holding it and its offset there, so a key is meaningful only while
779/// that text is alive and unchanged: compare keys of tags read from the
780/// same, living source (one event stream's text, or one syntax tree
781/// between edits). After the text is dropped (or a tree is edited), its
782/// address may be reused and a stale key could equal a new one. The
783/// borrow `'a` keeps the handle and suffix alive, not the directive's
784/// text.
785#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
786pub struct TagKey<'a> {
787 form: TagForm,
788 handle: &'a str,
789 suffix: &'a str,
790 /// The address of the source text and the prefix's offset in it.
791 prefix: Option<(usize, usize)>,
792}
793
794impl<'a> TagSource<'a> {
795 pub(crate) const fn new(
796 form: TagForm,
797 handle: &'a str,
798 suffix: &'a str,
799 span: Span,
800 src: &'a str,
801 prefix: Option<usize>,
802 ) -> Self {
803 Self {
804 form,
805 handle,
806 suffix,
807 span,
808 src,
809 at: span,
810 prefix,
811 }
812 }
813
814 /// What this tag resolves to, as a hashable key: O(1) to build, and
815 /// O(handle + suffix) to hash, whatever the `%TAG` prefix's length.
816 #[must_use]
817 pub fn key(&self) -> TagKey<'a> {
818 TagKey {
819 form: self.form,
820 handle: self.handle,
821 suffix: self.suffix,
822 prefix: self.prefix.map(|p| (self.src.as_ptr().addr(), p)),
823 }
824 }
825
826 /// The tag, resolved (`%TAG` prefix and `%XX` escapes, §6.9.1): what
827 /// [`Sourced::tag`] gives. O(prefix + suffix).
828 #[must_use]
829 pub fn resolve(&self) -> Option<Tag<'a>> {
830 crate::parser::resolve_tag(self)
831 }
832
833 /// When the handle names a `%TAG` directive: the key of that
834 /// directive's prefix, equal for every tag using it (to decode
835 /// [`TagSource::directive_prefix`] once and share it).
836 #[must_use]
837 pub fn prefix_key(&self) -> Option<TagKey<'a>> {
838 self.prefix.map(|p| TagKey {
839 form: TagForm::Shorthand,
840 handle: "",
841 suffix: "",
842 prefix: Some((self.src.as_ptr().addr(), p)),
843 })
844 }
845
846 /// When the handle names a `%TAG` directive: its prefix with the
847 /// `%XX` escapes decoded, as bytes (a character may continue in the
848 /// suffix). O(prefix).
849 #[must_use]
850 pub fn directive_prefix(&self) -> Option<Cow<'a, [u8]>> {
851 crate::parser::directive_prefix(self)
852 }
853
854 /// The prefix of a shorthand tag whose handle names no `%TAG`
855 /// directive: `!` for the primary handle, `tag:yaml.org,2002:` for the
856 /// secondary one (§6.8.2.2). `None` otherwise (a verbatim or
857 /// non-specific tag, or one with a [`TagSource::directive_prefix`]).
858 #[must_use]
859 pub fn default_prefix(&self) -> Option<&'static str> {
860 if self.form != TagForm::Shorthand || self.prefix.is_some() {
861 return None;
862 }
863 match self.handle {
864 "!" => Some("!"),
865 "!!" => Some("tag:yaml.org,2002:"),
866 _ => None,
867 }
868 }
869
870 /// The suffix (for a verbatim tag, its whole text) with the `%XX`
871 /// escapes decoded, as bytes (a character may begin in the prefix).
872 /// O(suffix). The resolved tag is the prefix
873 /// ([`TagSource::directive_prefix`] or [`TagSource::default_prefix`])
874 /// followed by these bytes; together they are UTF-8.
875 #[must_use]
876 pub fn decoded_suffix(&self) -> Cow<'a, [u8]> {
877 crate::parser::decoded_suffix(self)
878 }
879
880 pub(crate) const fn src(&self) -> &'a str {
881 self.src
882 }
883
884 /// The property's span in [`TagSource::src`].
885 pub(crate) const fn at(&self) -> Span {
886 self.at
887 }
888
889 pub(crate) const fn prefix(&self) -> Option<usize> {
890 self.prefix
891 }
892}
893
894/// Which directive an [`EventKind::Directive`] is (§6.8); its parameters
895/// are read by [`Sourced::directive`].
896#[non_exhaustive]
897#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
898pub enum Directive {
899 /// `%YAML`.
900 Yaml,
901 /// `%TAG`.
902 Tag,
903 /// Any other (reserved) directive.
904 Reserved,
905}
906
907/// The directives of §6.8, read from the source by [`Sourced::directive`].
908/// All text fields borrow from the directive's span.
909#[non_exhaustive]
910#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
911pub enum DirectiveKind<'a> {
912 /// `%YAML <version>`; the version as written. The version policy (warnings
913 /// for 1.1 and 1.3+, error for 2.x) is applied by the parser as
914 /// [`EventKind::Warning`]/[`EventKind::Error`] events, not encoded here.
915 #[non_exhaustive]
916 Yaml {
917 /// E.g. `1.2`.
918 version: &'a str,
919 },
920 /// `%TAG <handle> <prefix>`.
921 #[non_exhaustive]
922 Tag {
923 /// E.g. `!e!`.
924 handle: &'a str,
925 /// E.g. `tag:example.com,2000:`.
926 prefix: &'a str,
927 },
928 /// Any other `%NAME …` directive; ignored with a warning.
929 #[non_exhaustive]
930 Reserved {
931 /// The name, without `%`.
932 name: &'a str,
933 /// From the first byte of the first parameter to the last byte of the
934 /// last parameter, **including** the whitespace between parameters and
935 /// **excluding** the whitespace between the name and the first
936 /// parameter. Empty when there are no parameters. E.g. `%FOO bar baz`
937 /// has `params == "bar baz"`.
938 params: &'a str,
939 },
940}
941
942impl<'a> DirectiveKind<'a> {
943 /// [`DirectiveKind::Yaml`].
944 #[must_use]
945 pub const fn yaml(version: &'a str) -> Self {
946 Self::Yaml { version }
947 }
948
949 /// [`DirectiveKind::Tag`].
950 #[must_use]
951 pub const fn tag(handle: &'a str, prefix: &'a str) -> Self {
952 Self::Tag { handle, prefix }
953 }
954
955 /// [`DirectiveKind::Reserved`].
956 #[must_use]
957 pub const fn reserved(name: &'a str, params: &'a str) -> Self {
958 Self::Reserved { name, params }
959 }
960
961 /// Which directive this is.
962 #[must_use]
963 pub const fn directive(&self) -> Directive {
964 match self {
965 Self::Yaml { .. } => Directive::Yaml,
966 Self::Tag { .. } => Directive::Tag,
967 Self::Reserved { .. } => Directive::Reserved,
968 }
969 }
970}
971
972/// Kinds of presentation-only bytes.
973#[non_exhaustive]
974#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
975pub enum TriviaKind {
976 /// U+FEFF, between documents only.
977 ByteOrderMark,
978 /// A run of spaces and/or tabs.
979 Whitespace,
980 /// Exactly one line break: `\n`, `\r\n`, or `\r` (a `\r` is never split
981 /// from a following `\n`).
982 LineBreak,
983 /// `#` to the end of the line (excluding the break); preceded by
984 /// whitespace, a line break, a byte order mark, or the start of input.
985 Comment,
986 /// A structural indicator.
987 Indicator(Indicator),
988 /// The bytes `&name` of an anchor property (meaning: [`Properties`]).
989 Anchor,
990 /// The bytes of a tag property (meaning: [`Properties`]).
991 Tag,
992 /// A block scalar header, e.g. `|`, `>-`, `|2+` (meaning: [`BlockHeader`]).
993 BlockScalarHeader,
994 /// A `...` marker that closes no document (e.g. at the start of a stream).
995 DocumentEndMarker,
996 /// Bytes skipped during error recovery: one line at most, only after an
997 /// `Error` event (C6, R4).
998 Skipped,
999}
1000
1001/// Structural indicators carried as trivia.
1002#[non_exhaustive]
1003#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
1004pub enum Indicator {
1005 /// `-` block sequence entry; only directly inside a block sequence.
1006 SequenceEntry,
1007 /// `?` mapping key; only directly inside a mapping.
1008 MappingKey,
1009 /// `:` mapping value; only directly inside a mapping.
1010 MappingValue,
1011 /// `,` entry separator; only directly inside a flow sequence or flow
1012 /// mapping (a `FlowPair` ends before its `,`).
1013 FlowEntry,
1014}
1015
1016impl Indicator {
1017 /// The indicator's character.
1018 #[must_use]
1019 pub const fn as_str(self) -> &'static str {
1020 match self {
1021 Self::SequenceEntry => "-",
1022 Self::MappingKey => "?",
1023 Self::MappingValue => ":",
1024 Self::FlowEntry => ",",
1025 }
1026 }
1027}
1028
1029#[cfg(test)]
1030mod tests;