Skip to main content

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;