granit_parser/

parser.rs

//! Home to the YAML Parser.
//!
//! The parser takes input from the [`crate::scanner::Scanner`], performs final checks for YAML
//! compliance, and emits a stream of YAML events. This stream can for instance be used to create
//! YAML objects.

use crate::{
    error::{ErrorKind, ScanError},
    input::{str::StrInput, BorrowedInput},
    scanner::{Marker, QueuedToken, QueuedTokenType, ScalarStyle, Scanner, Span},
    BufferedInput, FallibleBufferedInput, Options,
};

#[cfg(feature = "comments")]
use crate::scanner::Placement;
#[cfg(feature = "comments")]
use alloc::collections::VecDeque;
use alloc::{
    borrow::Cow,
    collections::{BTreeMap, BTreeSet},
    string::String,
    vec::Vec,
};
use core::{
    convert::Infallible,
    fmt::{self, Display},
};

#[derive(Clone, Copy, PartialEq, Debug, Eq)]
enum State {
    StreamStart,
    ImplicitDocumentStart,
    DocumentStart,
    DocumentContent,
    DocumentEnd,
    BlockNode,
    BlockNodeOrIndentlessSequence,
    FlowNode,
    BlockSequenceFirstEntry,
    BlockSequenceEntry,
    IndentlessSequenceEntry,
    IndentlessSequenceEntryNode,
    BlockMappingFirstKey,
    BlockMappingKey,
    #[cfg(feature = "comments")]
    BlockMappingKeyNode,
    BlockMappingValue,
    #[cfg(feature = "comments")]
    BlockMappingValueNode,
    FlowSequenceFirstEntry,
    FlowSequenceEntry,
    FlowSequenceEntryMappingKey,
    FlowSequenceEntryMappingValue,
    #[cfg(feature = "comments")]
    FlowSequenceEntryMappingValueNode,
    FlowSequenceEntryMappingEnd,
    FlowMappingFirstKey,
    FlowMappingKey,
    #[cfg(feature = "comments")]
    FlowMappingKeyNode,
    FlowMappingValue,
    #[cfg(feature = "comments")]
    FlowMappingValueNode,
    FlowMappingEmptyValue,
    #[cfg(feature = "comments")]
    BlockSequenceEntryNode,
    End,
}

/// YAML version declared by a `%YAML` directive.
#[derive(Copy, Clone, PartialEq, Debug, Eq, Hash)]
pub struct YamlVersion {
    /// Major version number.
    pub major: u32,
    /// Minor version number.
    pub minor: u32,
}

impl YamlVersion {
    /// Create a YAML version value.
    #[must_use]
    pub const fn new(major: u32, minor: u32) -> Self {
        Self { major, minor }
    }
}

/// An event generated by the YAML parser.
///
/// Events are used in the low-level event-based API (push parser). The API entrypoint is the
/// [`EventReceiver`] trait.
#[non_exhaustive]
#[derive(Clone, PartialEq, Debug, Eq)]
pub enum Event<'input> {
    /// Event generated at the very beginning of parsing.
    StreamStart,
    /// Last event that will be generated by the parser. Signals EOF.
    StreamEnd,
    /// The start of a YAML document.
    ///
    DocumentStart(
        /// Whether this is an explicit document start marker (`---`).
        ///
        /// When `false`, the document start is implicit.
        bool,
        /// YAML version declared by a preceding `%YAML` directive, if any.
        Option<YamlVersion>,
    ),
    /// The end of a YAML document.
    ///
    /// This event is emitted for both explicit document end markers (`...`) and implicit document
    /// ends.
    DocumentEnd,
    /// A resolved YAML alias.
    ///
    /// The companion [`Span`] covers the complete `*name` token, preserving the original name
    /// through its source range. With [`Options::emit_anchor_events`], [`Self::Anchor`] connects
    /// the target ID to its definition's name and source range.
    Alias(
        /// The anchor ID the alias refers to.
        usize,
    ),
    /// Metadata for an anchor definition on the immediately preceding node in its parser's stream.
    ///
    /// Emitted only when [`Options::emit_anchor_events`] is `true`, immediately after the
    /// anchored [`Self::Scalar`], [`Self::SequenceStart`], or [`Self::MappingStart`], before any
    /// collection children. This is presentation metadata, not an additional YAML node.
    /// The companion [`Span`] covers the complete `&name` token, whose source position precedes
    /// the node content. Comments between properties and content can precede the node event.
    /// Emitting the node first ensures that a failure before its event is emitted cannot leave
    /// anchor metadata without an associated node event, even during document recovery.
    ///
    /// This adjacency guarantee applies to an individual [`Parser`]. See [`crate::ParserStack`]
    /// for ordering when sources are interleaved.
    ///
    /// Repeated names receive distinct IDs; aliases refer to the most recent preceding
    /// definition in the same document. IDs match those on node and [`Self::Alias`] events,
    /// including when [`Parser::set_anchor_offset`] is used.
    Anchor(
        /// The assigned internal anchor ID.
        usize,
        /// The original anchor name, without the leading `&`.
        Cow<'input, str>,
    ),
    /// An alias without a preceding anchor definition in its document.
    ///
    /// Emitted only when [`Options::emit_unresolved_aliases`] is `true`. The companion [`Span`]
    /// covers the complete alias token, including `*`. This event occupies a node position but
    /// represents an invalid reference; a later anchor definition does not resolve it retroactively.
    UnresolvedAlias(
        /// The original alias name, without the leading `*`.
        Cow<'input, str>,
    ),
    /// A YAML source comment.
    ///
    /// Comments are presentation metadata, not YAML data nodes. The payload is the raw text
    /// exactly after `#`, excluding only the line break. The placement is a best-effort hint for
    /// correlating the comment with nearby YAML presentation. The companion parser [`Span`] covers
    /// the whole source comment, including `#` and excluding the line break.
    #[cfg(feature = "comments")]
    Comment(
        /// Raw comment payload exactly after `#`, excluding only the line break.
        Cow<'input, str>,
        /// Best-effort placement relative to nearby YAML content.
        Placement,
    ),
    /// A YAML scalar value.
    Scalar(
        /// The scalar value after YAML escape processing.
        Cow<'input, str>,
        /// The source notation used for the scalar.
        ScalarStyle,
        /// The anchor ID defined on this scalar, or `0` if it has no anchor.
        usize,
        /// The resolved tag attached to this scalar, if any.
        Option<Cow<'input, Tag>>,
    ),
    /// The start of a YAML sequence (array).
    SequenceStart(
        /// The notation style used for the sequence.
        StructureStyle,
        /// The anchor ID defined on this sequence, or `0` if it has no anchor.
        usize,
        /// The resolved tag attached to this sequence, if any.
        Option<Cow<'input, Tag>>,
    ),
    /// The end of a YAML sequence (array).
    SequenceEnd,
    /// The start of a YAML mapping (object, hash).
    MappingStart(
        /// The notation style used for the mapping (Flow or Block).
        StructureStyle,
        /// The anchor ID defined on this mapping, or `0` if it has no anchor.
        usize,
        /// The resolved tag attached to this mapping, if any.
        Option<Cow<'input, Tag>>,
    ),
    /// The end of a YAML mapping (object, hash).
    MappingEnd,
}

/// The notation style used for a YAML sequence or mapping.
///
/// [`StructureStyle::Block`] means block notation:
///
/// ```yaml
/// items:
///   - milk
///   - bread
/// mapping:
///   name: Ada
///   active: true
/// ```
///
/// [`StructureStyle::Flow`] means flow notation:
///
/// ```yaml
/// items: [milk, bread]
/// mapping: {name: Ada, active: true}
/// ```
#[derive(Clone, Copy, PartialEq, Debug, Eq, Hash, PartialOrd, Ord)]
pub enum StructureStyle {
    /// Block notation, such as `- item` sequences and `key: value` mappings.
    Block,
    /// Flow notation, such as `[item]` sequences and `{key: value}` mappings.
    Flow,
}

/// A YAML tag.
#[derive(Clone, PartialEq, Debug, Eq, Ord, PartialOrd, Hash)]
pub struct Tag {
    /// Resolved tag handle or prefix.
    ///
    /// Examples include `tag:yaml.org,2002:` for core-schema tags and `!` for local tags.
    handle: Cow<'static, str>,
    /// Tag suffix following the resolved handle or prefix.
    suffix: Cow<'static, str>,
    /// Tag handle as written in the source before `%TAG` directive resolution.
    ///
    /// For example, with `%TAG !e! tag:example.com,2000:`, a source tag `!e!keep` is resolved
    /// as `handle = "tag:example.com,2000:"` and `suffix = "keep"`, while
    /// `original_handle = "!e!"`.
    original_handle: Cow<'static, str>,
}

const YAML_CORE_SCHEMA_PREFIX: &str = "tag:yaml.org,2002:";

// YAML 1.2.2 defines Core Schema tags by reference:
// - §10.3.1 says Core Schema uses the same tags as YAML's JSON Schema.
// - §10.2.1 adds null/bool/int/float to the Failsafe Schema.
// - §10.1.1 defines the Failsafe Schema tags map/seq/str.
// Therefore the YAML 1.2.2 Core Schema tag suffixes are:
// bool, float, int, map, null, seq, and str.
const YAML_CORE_SCHEMA_SUFFIXES: [&str; 7] = ["bool", "float", "int", "map", "null", "seq", "str"];

fn known_yaml_core_schema_suffix(suffix: &str) -> Option<&str> {
    YAML_CORE_SCHEMA_SUFFIXES
        .contains(&suffix)
        .then_some(suffix)
}

fn known_yaml_core_schema_suffix_from_split(
    handle_tail: &str,
    suffix: &str,
) -> Option<&'static str> {
    YAML_CORE_SCHEMA_SUFFIXES.iter().copied().find(|candidate| {
        candidate
            .strip_prefix(handle_tail)
            .is_some_and(|candidate_tail| candidate_tail == suffix)
    })
}

/// Retain common tag components without allocating, and reuse owned scanner strings otherwise.
fn own_tag_component(component: Cow<'_, str>) -> Cow<'static, str> {
    let known = match component.as_ref() {
        "" => "",
        "!" => "!",
        "!!" => "!!",
        "tag:yaml.org,2002:" => YAML_CORE_SCHEMA_PREFIX,
        "bool" => "bool",
        "float" => "float",
        "int" => "int",
        "map" => "map",
        "null" => "null",
        "seq" => "seq",
        "str" => "str",
        _ => return Cow::Owned(component.into_owned()),
    };
    Cow::Borrowed(known)
}

impl Tag {
    /// Create a tag from resolved parts.
    ///
    /// This is mainly useful for tests and consumers constructing parser-compatible tags by hand.
    /// When the original source handle matters, use [`Self::with_original_handle`].
    #[must_use]
    pub fn new(handle: impl Into<String>, suffix: impl Into<String>) -> Self {
        let handle = handle.into();
        Self {
            original_handle: Cow::Owned(handle.clone()),
            handle: Cow::Owned(handle),
            suffix: Cow::Owned(suffix.into()),
        }
    }

    /// Create a tag from resolved parts and the handle as written in the source.
    #[must_use]
    pub fn with_original_handle(
        handle: impl Into<String>,
        suffix: impl Into<String>,
        original_handle: impl Into<String>,
    ) -> Self {
        Self {
            handle: Cow::Owned(handle.into()),
            suffix: Cow::Owned(suffix.into()),
            original_handle: Cow::Owned(original_handle.into()),
        }
    }

    /// Return the resolved tag handle or prefix.
    #[must_use]
    pub fn handle(&self) -> &str {
        &self.handle
    }

    /// Return the suffix following the resolved tag handle or prefix.
    #[must_use]
    pub fn suffix(&self) -> &str {
        &self.suffix
    }

    /// Return the tag handle as written before `%TAG` directive resolution.
    #[must_use]
    pub fn original_handle(&self) -> &str {
        &self.original_handle
    }

    /// Return the resolved YAML core-schema suffix for this tag, if it is a known core tag.
    ///
    /// The tag is matched by its resolved URI, not by the source handle spelling. For example,
    /// `!!int`, `!<tag:yaml.org,2002:int>`, and a `%TAG` split such as
    /// `%TAG !m! tag:yaml.org,2002:i` followed by `!m!nt` all return `Some("int")`.
    ///
    /// Authored tag parts are left unchanged; use [`Self::parts`], [`Self::original_parts`], or
    /// [`Self::original`] to inspect those spellings.
    #[must_use]
    pub fn core_suffix(&self) -> Option<&str> {
        // The handle ends at or before the namespace boundary. The remaining namespace
        // prefix and the complete type name are both contained in `suffix`.
        if let Some(remaining_prefix) = YAML_CORE_SCHEMA_PREFIX.strip_prefix(self.handle.as_ref()) {
            let suffix = self.suffix.strip_prefix(remaining_prefix)?;
            return known_yaml_core_schema_suffix(suffix);
        }

        // The handle extends beyond the namespace boundary, so the type name is split
        // between the end of `handle` and `suffix`. Compare against the seven fixed names
        // directly instead of assembling an allocated String.
        let handle_tail = self.handle.strip_prefix(YAML_CORE_SCHEMA_PREFIX)?;
        known_yaml_core_schema_suffix_from_split(handle_tail, &self.suffix)
    }

    /// Return the type name this tag resolves to within `prefix`, or `None` outside it.
    ///
    /// Like [`Self::core_suffix`], the tag is matched by its resolved `handle ++ suffix` URI,
    /// not the source spelling, so `!!omap`, `!<tag:yaml.org,2002:omap>`, and a `%TAG` split
    /// such as `%TAG !o! tag:yaml.org,2002:o` then `!o!map` all resolve to `Some("omap")` for
    /// the `tag:yaml.org,2002:` prefix — but the name is not limited to the seven core types.
    ///
    /// Borrows from `self`; allocates only when the handle extends past `prefix`.
    #[must_use]
    pub fn suffix_in_namespace(&self, prefix: &str) -> Option<Cow<'_, str>> {
        if let Some(handle_tail) = self.handle.strip_prefix(prefix) {
            // Handle spans the whole prefix; the name is its tail plus the suffix (the tail
            // is empty unless a `%TAG` split pushed part of the name into the handle).
            return Some(if handle_tail.is_empty() {
                Cow::Borrowed(self.suffix.as_ref())
            } else {
                let mut name = String::with_capacity(handle_tail.len() + self.suffix.len());
                name.push_str(handle_tail);
                name.push_str(&self.suffix);
                Cow::Owned(name)
            });
        }

        // Handle stops inside the prefix; the suffix supplies the rest of the prefix
        // and then the name.
        prefix
            .strip_prefix(self.handle.as_ref())
            .and_then(|prefix_tail| self.suffix.strip_prefix(prefix_tail))
            .map(Cow::Borrowed)
    }

    /// Returns whether the tag is a YAML tag from the core schema (`!!str`, `!!int`, ...).
    ///
    /// The YAML specification specifies [a list of
    /// tags](https://yaml.org/spec/1.2.2/#103-core-schema) for the Core Schema. This function uses
    /// the resolved tag URI, so it is independent of how the tag was split between handle and
    /// suffix.
    ///
    /// # Return
    /// Returns `true` if the resolved tag is a known YAML 1.2.2 Core Schema tag.
    #[must_use]
    pub fn is_yaml_core_schema(&self) -> bool {
        self.core_suffix().is_some()
    }

    /// Return true for a YAML core-schema tag with the given suffix.
    ///
    /// For example, this matches core-schema tags such as `!!str`, `!!int`, `!!float`, `!!bool`,
    /// `!!null`, `!!map`, or `!!seq` after tag resolution.
    #[must_use]
    pub fn is_yaml_core_schema_tag(&self, suffix: &str) -> bool {
        self.core_suffix()
            .is_some_and(|core_suffix| core_suffix == suffix)
    }

    /// Return true for a tag outside the YAML 1.2.2 Core Schema tag set.
    ///
    /// This checks the resolved tag URI, not just the tag handle spelling. For example,
    /// `tag:yaml.org,2002:timestamp` is in the YAML tag namespace, but it is not a YAML 1.2.2
    /// Core Schema tag.
    #[must_use]
    pub fn is_custom(&self) -> bool {
        !self.is_yaml_core_schema()
    }

    /// Return the tag as `(handle, suffix)`.
    #[must_use]
    pub fn parts(&self) -> (&str, &str) {
        (&self.handle, &self.suffix)
    }

    /// Return the tag as `(original_handle, suffix)` using the handle from the source token.
    ///
    /// This is useful when a consumer needs author spelling such as `!e!keep` instead of the
    /// resolved URI tag `tag:example.com,2000:keep`.
    #[must_use]
    pub fn original_parts(&self) -> (&str, &str) {
        (&self.original_handle, &self.suffix)
    }

    /// Return the tag spelling reconstructed from the source handle and suffix.
    ///
    /// For ordinary shorthand tags this returns the author-facing spelling, such as `!e!keep` or
    /// `!!str`. For verbatim tags this returns a normalized verbatim spelling such as
    /// `!<tag:example.com,2000:thing>`, not necessarily the byte-exact source token.
    #[must_use]
    pub fn original(&self) -> String {
        if self.original_handle.is_empty() && self.suffix != "!" {
            let mut tag = String::with_capacity(self.suffix.len() + 3);
            tag.push_str("!<");
            tag.push_str(&self.suffix);
            tag.push('>');
            return tag;
        }

        let mut tag = String::with_capacity(self.original_handle.len() + self.suffix.len());
        tag.push_str(&self.original_handle);
        tag.push_str(&self.suffix);
        tag
    }
}

impl Display for Tag {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        if self.handle == "!" {
            write!(f, "!{}", self.suffix)
        } else {
            write!(f, "{}{}", self.handle, self.suffix)
        }
    }
}

impl<'input> Event<'input> {
    /// Return the anchor ID defined by this event, if any.
    ///
    /// Returns `Some(id)` when this event defines an anchor on a scalar, sequence, or mapping
    /// node, or describes that definition with [`Self::Anchor`]. The reserved ID `0` returns
    /// `None`. Returns `None` for all other events, including resolved and unresolved aliases
    /// (which reference anchors rather than defining them; use [`Self::alias_id`] to obtain a
    /// resolved target anchor ID).
    /// To count anchored nodes once, also require [`Self::is_node`], since [`Self::Anchor`]
    /// repeats the node's ID.
    #[must_use]
    pub fn anchor_id(&self) -> Option<usize> {
        match self {
            Self::Scalar(_, _, anchor_id, _)
            | Self::SequenceStart(_, anchor_id, _)
            | Self::MappingStart(_, anchor_id, _)
            | Self::Anchor(anchor_id, _)
                if *anchor_id != 0 =>
            {
                Some(*anchor_id)
            }
            _ => None,
        }
    }

    /// Return the target anchor ID if this event is a resolved alias.
    ///
    /// Returns `None` for unresolved aliases and non-alias events. Use [`Self::is_alias`] to
    /// recognize either kind of alias, or match [`Self::UnresolvedAlias`] to obtain its name.
    #[must_use]
    pub fn alias_id(&self) -> Option<usize> {
        match self {
            Self::Alias(anchor_id) => Some(*anchor_id),
            _ => None,
        }
    }

    /// Return whether this event is a resolved or unresolved alias.
    #[must_use]
    pub fn is_alias(&self) -> bool {
        matches!(self, Self::Alias(_) | Self::UnresolvedAlias(_))
    }

    /// Return the resolved tag carried by this node event, if any.
    #[must_use]
    pub fn tag(&self) -> Option<&Tag> {
        match self {
            Self::Scalar(_, _, _, tag)
            | Self::SequenceStart(_, _, tag)
            | Self::MappingStart(_, _, tag) => tag.as_deref(),
            _ => None,
        }
    }

    /// Return the scalar value and style, if this event is a scalar.
    #[must_use]
    pub fn scalar(&self) -> Option<(&str, ScalarStyle)> {
        match self {
            Self::Scalar(value, style, _, _) => Some((value.as_ref(), *style)),
            _ => None,
        }
    }

    /// Return whether this event represents a YAML node (value).
    ///
    /// Returns `true` for scalars, collection starts, and resolved or unresolved aliases, all of
    /// which occupy a node position. Returns `false` for structural events such as `StreamStart`,
    /// `DocumentStart`, collection ends, and presentation metadata such as [`Self::Anchor`].
    #[must_use]
    pub fn is_node(&self) -> bool {
        matches!(
            self,
            Self::Alias(_)
                | Self::UnresolvedAlias(_)
                | Self::Scalar(..)
                | Self::SequenceStart(..)
                | Self::MappingStart(..)
        )
    }

    /// Create an empty scalar.
    fn empty_scalar() -> Self {
        // a null scalar
        Event::Scalar("~".into(), ScalarStyle::Plain, 0, None)
    }

    /// Create an empty scalar with the given node properties.
    fn empty_scalar_with_anchor(anchor: usize, tag: Option<Cow<'input, Tag>>) -> Self {
        let value = if tag.is_some() {
            Cow::default()
        } else {
            "~".into()
        };

        Event::Scalar(value, ScalarStyle::Plain, anchor, tag)
    }
}

/// Anchor metadata retained until its node event has been returned, including through comments.
#[derive(Debug)]
struct PendingAnchor<'input> {
    id: usize,
    name: Cow<'input, str>,
    span: Span,
    node_emitted: bool,
}

/// A YAML parser.
#[derive(Debug)]
#[allow(clippy::struct_excessive_bools)] // Independent parsing policies and state flags.
pub struct Parser<'input, T: BorrowedInput<'input>> {
    /// The underlying scanner from which we pull tokens.
    scanner: Scanner<'input, T>,
    /// Whether unknown anchors produce unresolved alias nodes instead of terminal errors.
    emit_unresolved_aliases: bool,
    /// Whether anchor definition metadata is emitted after the associated node event.
    emit_anchor_events: bool,
    /// The anchor token waiting for its node, or ready to emit immediately after that node.
    pending_anchor: Option<PendingAnchor<'input>>,
    /// Maximum number of comments retained while resolving an ambiguous collection entry.
    #[cfg(feature = "comments")]
    max_buffered_comment_events: usize,
    /// Maximum number of simultaneously open block collections.
    block_nesting_limit: usize,
    /// Number of block collections currently open in the parser state machine.
    block_level: usize,
    /// The stack of _previous_ states we were in.
    ///
    /// States are pushed in the context of subobjects to this stack. The top-most element is the
    /// state in which to come back to when exiting the current state.
    states: Vec<State>,
    /// The state in which we currently are.
    state: State,
    /// The next token from the scanner.
    token: Option<QueuedToken<'input>>,
    /// The next YAML event to emit.
    current: Option<(Event<'input>, Span)>,
    /// The next parser error to emit after it has been observed by `peek`.
    current_error: Option<ScanError>,
    /// A scanner error discovered while ordering events that must be emitted first.
    ///
    /// Unlike `current_error`, this has not been exposed through `peek`. It is consumed by
    /// `next_event_impl` after already-buffered events so `peek`, iteration, and `load` all retain
    /// the same ordering.
    #[cfg(feature = "comments")]
    deferred_error: Option<ScanError>,
    /// YAML events buffered by parser states that need to emit an earlier synthetic node first.
    #[cfg(feature = "comments")]
    queued_events: VecDeque<(Event<'input>, Span)>,
    /// Retained storage for collecting and ordering comments between syntax events.
    #[cfg(feature = "comments")]
    comment_scratch: Vec<(Event<'input>, Span)>,

    /// Pending indentation hint to be attached to the next emitted event span.
    ///
    /// This is used to communicate indentation for block mapping keys. It is set when consuming a
    /// `TokenType::Key` in block style, and is applied to the next emitted node event (the key
    /// itself).
    pending_key_indent: Option<usize>,
    /// Pending anchor ID to attach to a node after an intervening comment.
    /// `Some(0)` retains an anchor property when the anchor offset is zero.
    #[cfg(feature = "comments")]
    pending_node_anchor_id: Option<usize>,
    /// Pending tag to attach to a node after an intervening comment.
    #[cfg(feature = "comments")]
    pending_node_tag: Option<Cow<'input, Tag>>,
    /// Pending explicit tag token start and raw length after an intervening comment.
    #[cfg(feature = "comments")]
    pending_node_tag_span: Option<(Marker, u32)>,
    /// Pending end marker of the last node-property token before an intervening comment.
    #[cfg(feature = "comments")]
    pending_node_property_end: Option<Marker>,
    /// Pending empty scalar span captured before an intervening comment.
    pending_empty_scalar_span: Option<Span>,
    /// End marker of the most recently produced non-metadata event.
    ///
    /// Synthetic syntax events use this marker, so presentation metadata must not affect it.
    last_non_comment_event_end: Option<Marker>,
    /// Pending YAML version captured before comments preceding an explicit document start.
    #[cfg(feature = "comments")]
    pending_document_version: Option<YamlVersion>,
    /// Whether document directives were already initialized before comments preceding `---`.
    #[cfg(feature = "comments")]
    pending_document_directives: bool,
    /// `%TAG` handles already seen before comments preceding an explicit document start.
    #[cfg(feature = "comments")]
    pending_document_tag_handles: BTreeSet<Cow<'input, str>>,
    /// Anchors that have been encountered in the YAML document.
    anchors: BTreeMap<Cow<'input, str>, usize>,
    /// Next ID available for an anchor.
    ///
    /// Every anchor is given a unique ID. We use an incrementing ID and this is both the ID to
    /// return for the next anchor and the count of anchor IDs emitted.
    anchor_id_count: usize,
    /// The tag directives (`%TAG`) the parser has encountered.
    ///
    /// Key is the handle, and value is the prefix.
    tags: BTreeMap<Cow<'input, str>, Cow<'input, str>>,
    /// Whether we have emitted a terminal iterator result.
    ///
    /// Terminal means either [`Event::StreamEnd`] or a [`ScanError`]. Emitted means that it has
    /// been returned from [`Self::next_event`] or [`Self::next`]. If the terminal result is stored
    /// in [`Self::current`], [`Self::current_error`], or internal comment buffers, this is set to
    /// `false`.
    stream_end_emitted: bool,
    /// Whether parsing stopped on an error, including an error observed only through `peek`.
    failed: bool,
    /// Whether the current document has ended without starting the next one yet.
    at_document_end: bool,
    /// Make tags global across all documents.
    keep_tags: bool,
}

/// Trait to be implemented in order to use the low-level parsing API.
///
/// The low-level parsing API is event-based (a push parser), calling [`EventReceiver::on_event`]
/// for each YAML [`Event`] that occurs.
/// The [`EventReceiver`] trait only receives events. In order to receive both events and their
/// location in the source, use [`SpannedEventReceiver`]. Note that [`EventReceiver`]s implement
/// [`SpannedEventReceiver`] automatically.
/// With the `comments` feature, non-spanned receivers receive `Event::Comment(text, placement)` like any
/// other event, but without source location. Spanned receivers receive the same comment event plus
/// the comment [`Span`] in [`SpannedEventReceiver::on_event`]. For comments, that span covers the
/// whole source comment, including `#` and excluding the line break. When parsing from an input
/// with byte offsets, such as [`Parser::new_from_str`], [`Span::slice`] returns that source
/// comment text.
///
/// # Event hierarchy
/// The event stream starts with an [`Event::StreamStart`] event followed by an
/// [`Event::DocumentStart`] event. If the YAML document starts with a mapping (an object), an
/// [`Event::MappingStart`] event is emitted. If it starts with a sequence (an array), an
/// [`Event::SequenceStart`] event is emitted. Otherwise, an [`Event::Scalar`] event is emitted.
///
/// In a mapping, key-values are sent as consecutive data events. Comments can appear in the raw
/// event stream between a key and its value; they are presentation metadata, not YAML data nodes.
/// Consumers building YAML data trees should ignore `Event::Comment` and [`Event::Anchor`].
/// With [`Options::emit_anchor_events`], anchor metadata immediately follows its scalar or
/// collection-start event and carries the same ID plus the original name and anchor-token span.
/// Any key/value alternation shortcut applies only after filtering out comments and other
/// presentation metadata. After that
/// filtering, the first event after an [`Event::MappingStart`] will be the key, and the following
/// event will be its value. If the mapping contains no sub-mapping or sub-sequence, then even events
/// (starting from 0) will always be keys and odd ones will always be values. The mapping ends when
/// an [`Event::MappingEnd`] event is received.
///
/// In a sequence, values are sent consecutively until the [`Event::SequenceEnd`] event.
///
/// If a value is a sub-mapping or a sub-sequence, an [`Event::MappingStart`] or
/// [`Event::SequenceStart`] event will be sent respectively. Following events until the associated
/// [`Event::MappingEnd`] or [`Event::SequenceEnd`] (beware of nested mappings or sequences) will
/// be part of the value and not another key-value pair or element in the sequence.
///
/// For instance, the following YAML:
/// ```yaml
/// a: b
/// c:
///   d: e
/// f:
///   - g
///   - h
/// ```
/// will emit (indented and commented for visibility):
/// ```text
/// StreamStart, DocumentStart, MappingStart,
///   Scalar("a", ..), Scalar("b", ..)
///   Scalar("c", ..), MappingStart, Scalar("d", ..), Scalar("e", ..), MappingEnd,
///   Scalar("f", ..), SequenceStart, Scalar("g", ..), Scalar("h", ..), SequenceEnd,
/// MappingEnd, DocumentEnd, StreamEnd
/// ```
///
/// # Example
/// ```
/// # use granit_parser::{Event, EventReceiver, Parser};
/// #
/// /// Sink of events. Collects them into an array.
/// struct EventSink<'input> {
///     events: Vec<Event<'input>>,
/// }
///
/// /// Implement `on_event`, pushing into `self.events`.
/// impl<'input> EventReceiver<'input> for EventSink<'input> {
///     fn on_event(&mut self, ev: Event<'input>) {
///         self.events.push(ev);
///     }
/// }
///
/// /// Load events from a YAML string.
/// fn str_to_events(yaml: &str) -> Vec<Event<'_>> {
///     let mut sink = EventSink { events: Vec::new() };
///     let mut parser = Parser::new_from_str(yaml);
///     // Load events using our sink as the receiver.
///     parser.load(&mut sink, true).unwrap();
///     sink.events
/// }
/// ```
pub trait EventReceiver<'input> {
    /// Handler called for each YAML event that is emitted by the parser.
    fn on_event(&mut self, ev: Event<'input>);
}

/// Trait to be implemented for using the low-level parsing API.
///
/// Functionally similar to [`EventReceiver`], but receives a [`Span`] as well as the event.
/// With the `comments` feature, an `Event::Comment` span is the source range of the whole comment.
pub trait SpannedEventReceiver<'input> {
    /// Handler called for each event that occurs.
    fn on_event(&mut self, ev: Event<'input>, span: Span);
}

impl<'input, R: EventReceiver<'input>> SpannedEventReceiver<'input> for R {
    fn on_event(&mut self, ev: Event<'input>, _span: Span) {
        self.on_event(ev);
    }
}

/// Trait to be implemented for fallible event handling without source spans.
///
/// This is the fallible counterpart to [`EventReceiver`]. Use it with [`Parser::try_load`] when
/// event handling may need to stop parsing by returning an application error.
pub trait TryEventReceiver<'input> {
    /// Error returned by this receiver.
    type Error;

    /// Handler called for each YAML event that is emitted by the parser.
    ///
    /// Returning an error stops [`Parser::try_load`] immediately.
    ///
    /// # Errors
    /// Returns `Self::Error` when the receiver wants to stop parsing.
    fn on_event(&mut self, ev: Event<'input>) -> Result<(), Self::Error>;
}

/// Trait to be implemented for fallible event handling with source spans.
///
/// This is the fallible counterpart to [`SpannedEventReceiver`]. Use it with
/// [`Parser::try_load`] when event handling may need to stop parsing by returning an application
/// error.
pub trait TrySpannedEventReceiver<'input> {
    /// Error returned by this receiver.
    type Error;

    /// Handler called for each event that occurs.
    ///
    /// Returning an error stops [`Parser::try_load`] immediately.
    ///
    /// # Errors
    /// Returns `Self::Error` when the receiver wants to stop parsing.
    fn on_event(&mut self, ev: Event<'input>, span: Span) -> Result<(), Self::Error>;
}

impl<'input, R: TryEventReceiver<'input>> TrySpannedEventReceiver<'input> for R {
    type Error = R::Error;

    fn on_event(&mut self, ev: Event<'input>, _span: Span) -> Result<(), Self::Error> {
        TryEventReceiver::on_event(self, ev)
    }
}

/// Error returned by [`Parser::try_load`] and [`ParserTrait::try_load`].
#[derive(Clone, PartialEq, Debug, Eq)]
pub enum TryLoadError<E> {
    /// Scanning or parsing failed.
    Scan(
        /// The scanner or parser error.
        ScanError,
    ),
    /// The receiver returned an application error.
    Receiver(
        /// The error returned by the receiver.
        E,
    ),
}

impl<E> TryLoadError<E> {
    #[cold]
    fn scan(error: ScanError) -> Self {
        Self::Scan(error)
    }

    #[cold]
    fn receiver(error: E) -> Self {
        Self::Receiver(error)
    }
}

impl<E> From<ScanError> for TryLoadError<E> {
    #[cold]
    fn from(error: ScanError) -> Self {
        Self::scan(error)
    }
}

impl<E: Display> Display for TryLoadError<E> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Scan(error) => write!(f, "parser error: {error}"),
            Self::Receiver(error) => write!(f, "receiver error: {error}"),
        }
    }
}

impl<E> core::error::Error for TryLoadError<E>
where
    E: core::error::Error + 'static,
{
    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
        match self {
            Self::Scan(error) => Some(error),
            Self::Receiver(error) => Some(error),
        }
    }
}

fn try_emit<'input, R>(
    recv: &mut R,
    ev: Event<'input>,
    span: Span,
) -> Result<(), TryLoadError<R::Error>>
where
    R: TrySpannedEventReceiver<'input>,
{
    recv.on_event(ev, span).map_err(TryLoadError::receiver)
}

struct InfallibleSpannedReceiver<'receiver, R>(&'receiver mut R);

impl<'input, R: SpannedEventReceiver<'input>> TrySpannedEventReceiver<'input>
    for InfallibleSpannedReceiver<'_, R>
{
    type Error = Infallible;

    fn on_event(&mut self, ev: Event<'input>, span: Span) -> Result<(), Self::Error> {
        self.0.on_event(ev, span);
        Ok(())
    }
}

fn into_scan_result(result: Result<(), TryLoadError<Infallible>>) -> Result<(), ScanError> {
    match result {
        Ok(()) => Ok(()),
        Err(TryLoadError::Scan(error)) => error.into_result(),
        Err(TryLoadError::Receiver(error)) => match error {},
    }
}

/// A convenience alias for a parser event result.
pub type ParseResult<'input> = Result<(Event<'input>, Span), ScanError>;

/// Trait extracted from `Parser` to support mocking and alternative implementations.
pub trait ParserTrait<'input> {
    /// Try to load the next event and return it without consuming it from `self`.
    fn peek(&mut self) -> Option<Result<&(Event<'input>, Span), ScanError>>;

    /// Try to load the next event and return it, consuming it from `self`.
    fn next_event(&mut self) -> Option<ParseResult<'input>>;

    /// Load the YAML from the stream in `self`, pushing events into `recv`.
    ///
    /// Use this method when event handling is infallible. If receiver code can return an
    /// application error and should stop parsing, use [`ParserTrait::try_load`] instead. If the
    /// caller should directly control when the next event is read, use [`ParserTrait::next_event`]
    /// or [`Parser`]'s [`core::iter::Iterator`] implementation.
    ///
    /// After a scan error, the parser is exhausted: [`ParserTrait::peek`] and
    /// [`ParserTrait::next_event`] return [`None`], and further calls to `load` or
    /// [`ParserTrait::try_load`] return `Ok(())` without emitting events.
    ///
    /// # Errors
    /// Returns `ScanError` when scanning or parsing the stream fails.
    fn load<R: SpannedEventReceiver<'input>>(
        &mut self,
        recv: &mut R,
        multi: bool,
    ) -> Result<(), ScanError>;

    /// Load the YAML from the stream in `self`, stopping if `recv` returns an error.
    ///
    /// If `multi` is set to `true`, the parser will allow parsing of multiple YAML documents
    /// inside the stream.
    ///
    /// If the receiver returns an error, the parser is left positioned immediately after the event
    /// that caused the receiver error. Callers should treat the parser as partially consumed.
    ///
    /// After a scan error, the parser is exhausted: [`ParserTrait::peek`] and
    /// [`ParserTrait::next_event`] return [`None`], and further calls to `try_load` or
    /// [`ParserTrait::load`] return `Ok(())` without emitting events.
    ///
    /// # Errors
    /// Returns [`TryLoadError::Scan`] when scanning or parsing the stream fails. Returns
    /// [`TryLoadError::Receiver`] when `recv` returns an error.
    fn try_load<R: TrySpannedEventReceiver<'input>>(
        &mut self,
        recv: &mut R,
        multi: bool,
    ) -> Result<(), TryLoadError<R::Error>> {
        while let Some(res) = self.next_event() {
            let (ev, span) = res?;
            let is_doc_end = matches!(ev, Event::DocumentEnd);
            let is_stream_end = matches!(ev, Event::StreamEnd);

            try_emit(recv, ev, span)?;

            if is_stream_end {
                break;
            }
            if !multi && is_doc_end {
                break;
            }
        }

        Ok(())
    }
}

impl<'input> Parser<'input, StrInput<'input>> {
    /// Create a parser over a borrowed string slice.
    ///
    /// Every emitted event span has UTF-8 byte offsets into `value`:
    /// [`Span::byte_range`] returns `Some(start..end)`, with ordered, in-bounds UTF-8
    /// boundaries. This includes zero-length spans for implicit events and end-of-input.
    /// [`Span::slice`] returns `Some` when given the same, unchanged source string.
    ///
    /// This guarantee applies to spans as emitted, before callers modify their markers.
    /// Byte offsets remain optional in [`Span`] because other inputs, such as
    /// [`Self::new_from_iter`], do not provide them. Missing offsets must not be replaced
    /// with zero or with [`Marker::index`], which counts characters rather than bytes.
    #[must_use]
    pub fn new_from_str(value: &'input str) -> Self {
        Self::new_from_str_with_options(value, Options::default())
    }

    /// Create a parser over a borrowed string slice with configurable behavior and resource
    /// limits.
    ///
    /// The byte-offset guarantee of [`Self::new_from_str`] also applies with custom options.
    #[must_use]
    pub fn new_from_str_with_options(value: &'input str, options: Options) -> Self {
        Parser::with_options(StrInput::new(value), options)
    }
}

impl<T> Parser<'static, BufferedInput<T>>
where
    T: Iterator<Item = char>,
{
    /// Create a parser over an iterator of characters.
    #[must_use]
    pub fn new_from_iter(iter: T) -> Self {
        Self::new_from_iter_with_options(iter, Options::default())
    }

    /// Create a parser over an iterator of characters with configurable behavior and resource
    /// limits.
    #[must_use]
    pub fn new_from_iter_with_options(iter: T, options: Options) -> Self {
        Parser::with_options(BufferedInput::new(iter), options)
    }
}

impl<T> Parser<'static, FallibleBufferedInput<T>>
where
    T: Iterator<Item = Result<char, ErrorKind>>,
{
    /// Create a parser over a fallible iterator of characters.
    ///
    /// The iterator's `None` return value means clean end-of-input. An `Err` item reports a
    /// terminal source failure and is returned by the parser as a [`ScanError`] carrying the same
    /// [`ErrorKind`]. The iterator is not polled again after its first error.
    #[must_use]
    pub fn new_from_fallible_iter(iter: T) -> Self {
        Self::new_from_fallible_iter_with_options(iter, Options::default())
    }

    /// Create a parser over a fallible iterator of characters with configurable behavior and
    /// resource limits.
    ///
    /// The iterator's `None` return value means clean end-of-input. An `Err` item reports a
    /// terminal source failure and is returned by the parser as a [`ScanError`] carrying the same
    /// [`ErrorKind`]. The iterator is not polled again after its first error.
    #[must_use]
    pub fn new_from_fallible_iter_with_options(iter: T, options: Options) -> Self {
        Parser::with_options(FallibleBufferedInput::new(iter), options)
    }
}

impl<'input, T: BorrowedInput<'input>> Parser<'input, T> {
    /// Return the next anchor ID that will be assigned by this parser.
    #[must_use]
    pub fn anchor_offset(&self) -> usize {
        self.anchor_id_count
    }

    /// Set the next anchor ID that will be assigned by this parser.
    pub fn set_anchor_offset(&mut self, offset: usize) {
        self.anchor_id_count = offset;
    }

    /// Create a parser over a custom input source.
    #[must_use]
    pub fn new(src: T) -> Self {
        Self::with_options(src, Options::default())
    }

    /// Create a parser over a custom input source with configurable behavior and resource limits.
    ///
    /// Use [`crate::options!`] to construct `options` without depending on exhaustive struct
    /// literal syntax.
    /// Without the `comments` feature, comment capture and emission are compiled out of both
    /// the parser and its scanner. YAML comments are still skipped and validated.
    #[must_use]
    pub fn with_options(src: T, options: Options) -> Self {
        #[cfg(feature = "comments")]
        let max_buffered_comment_events = options.max_buffered_comment_events;
        let block_nesting_limit = options.block_nesting_limit;
        let emit_unresolved_aliases = options.emit_unresolved_aliases;
        let emit_anchor_events = options.emit_anchor_events;
        let scanner = Scanner::with_options(src, options);

        Parser {
            scanner,
            emit_unresolved_aliases,
            emit_anchor_events,
            pending_anchor: None,
            #[cfg(feature = "comments")]
            max_buffered_comment_events,
            block_nesting_limit,
            block_level: 0,
            states: Vec::new(),
            state: State::StreamStart,
            token: None,
            current: None,
            current_error: None,
            #[cfg(feature = "comments")]
            deferred_error: None,
            #[cfg(feature = "comments")]
            queued_events: VecDeque::new(),
            #[cfg(feature = "comments")]
            comment_scratch: Vec::new(),

            pending_key_indent: None,
            #[cfg(feature = "comments")]
            pending_node_anchor_id: None,
            #[cfg(feature = "comments")]
            pending_node_tag: None,
            #[cfg(feature = "comments")]
            pending_node_tag_span: None,
            #[cfg(feature = "comments")]
            pending_node_property_end: None,
            pending_empty_scalar_span: None,
            last_non_comment_event_end: None,
            #[cfg(feature = "comments")]
            pending_document_version: None,
            #[cfg(feature = "comments")]
            pending_document_directives: false,
            #[cfg(feature = "comments")]
            pending_document_tag_handles: BTreeSet::new(),

            anchors: BTreeMap::new(),
            // valid anchor_id starts from 1
            anchor_id_count: 1,
            tags: BTreeMap::new(),
            stream_end_emitted: false,
            failed: false,
            at_document_end: false,
            keep_tags: false,
        }
    }

    /// Configure whether tag directives remain active across document boundaries.
    ///
    /// This behavior is non-standard as per the YAML specification but can be encountered in the
    /// wild. Passing `true` enables this non-standard extension and allows the parser to accept
    /// input from [test
    /// QLJ7](https://github.com/yaml/yaml-test-suite/blob/ccfa74e56afb53da960847ff6e6976c0a0825709/src/QLJ7.yaml)
    /// of the yaml-test-suite:
    ///
    /// ```yaml
    /// %TAG !prefix! tag:example.com,2011:
    /// --- !prefix!A
    /// a: b
    /// --- !prefix!B
    /// c: d
    /// --- !prefix!C
    /// e: f
    /// ```
    ///
    /// With `keep_tags` set to `false`, the above YAML is rejected. As per the specification, tags
    /// only apply to the document immediately following them. This would error on `!prefix!B`.
    ///
    /// With `keep_tags` set to `true`, the above YAML is accepted by the parser.
    #[must_use]
    pub fn keep_tags(mut self, value: bool) -> Self {
        self.keep_tags = value;
        self
    }

    /// Try to load the next event and return it without consuming it from `self`.
    ///
    /// Any subsequent call to [`Parser::peek`] will return the same value, until a call to
    /// [`Iterator::next`], [`Parser::load`], or [`Self::proceed_next_document`].
    /// If the buffered value is a [`ScanError`], [`Parser::next_event`] returns that error once
    /// and then the parser is exhausted.
    ///
    /// # Errors
    /// Returns `ScanError` when loading the next event fails.
    pub fn peek(&mut self) -> Option<Result<&(Event<'input>, Span), ScanError>> {
        ParserTrait::peek(self)
    }

    /// Try to load the next event and return it, consuming it from `self`.
    ///
    /// After this returns a [`ScanError`], subsequent calls return [`None`] unless
    /// [`Self::proceed_next_document`] is called to recover at a document boundary.
    ///
    /// # Errors
    /// Returns `ScanError` when loading the next event fails.
    pub fn next_event(&mut self) -> Option<ParseResult<'input>> {
        ParserTrait::next_event(self)
    }

    /// Abandon the current document and resume at the next document boundary.
    ///
    /// This can be called after an error from iteration, [`Self::peek`], or [`Self::load`], or
    /// during successful parsing to skip the remainder of a document. Before parsing starts it
    /// skips the first document. Immediately after [`Event::DocumentEnd`] it leaves the next
    /// document ready to read. Repeated calls skip successive documents.
    ///
    /// Returns `true` when another document remains, including an empty or malformed document,
    /// and `false` at clean EOF. This looks past inter-document comments and end markers without
    /// consuming the next document's events. Comments inspected by this lookahead are buffered
    /// for subsequent reads; with comment emission enabled, the configured comment-buffer limit
    /// applies. Syntax errors encountered in the next document remain available to normal parsing.
    ///
    /// Read subsequent events using the usual parser methods. They start with the next
    /// [`Event::DocumentStart`] (possibly preceded by comments), or [`Event::StreamEnd`] if no
    /// document remains. An already consumed stream end stays exhausted. This method does not
    /// emit another [`Event::StreamStart`].
    ///
    /// After a syntax error, recovery scans forward from the scanner's current position to a
    /// separated `---` or valid `...` at column zero, or EOF. An explicit end marker also permits
    /// a following implicit document and its directive prefix. Indented markers, inline markers,
    /// and scalar text such as `---suffix` are not synchronization points. Input is never rewound;
    /// event spans retain their original source positions.
    /// If a directive prefix fails before its opening `---`, that document's body is skipped too.
    ///
    /// Open collections, buffered events/comments, and anchor definitions of an abandoned
    /// document are discarded. No synthetic collection ends, document end, or error node are
    /// emitted for it: consumers building a tree must abandon or mark their own partial nodes.
    /// Anchor IDs remain unique across documents. Directives are reset as at a normal document
    /// boundary, including the [`Self::keep_tags`] policy.
    ///
    /// Skipped syntax errors are suppressed. Recovery does not repair content within a document,
    /// preserve its anchors for another document, or validate the next document in advance.
    /// Ordinary parsing still stops at the first error unless this method is explicitly called.
    /// Scanning moves forward with work proportional to the skipped input; no diagnostic list
    /// is accumulated. Cancellation can be supplied through a fallible input source.
    ///
    /// # Example
    /// ```
    /// use granit_parser::{Event, Parser};
    /// # fn main() -> Result<(), granit_parser::ScanError> {
    /// let mut parser = Parser::new_from_str("broken: [1, 2\n---\nhealthy: true\n");
    /// let error = parser.by_ref().find_map(Result::err).unwrap();
    /// assert!(parser.next().is_none());
    /// // Record the diagnostic and abandon any open nodes in the consumer's partial tree.
    /// assert!(parser.proceed_next_document()?);
    /// assert!(matches!(parser.next().unwrap()?.0, Event::DocumentStart(true, _)));
    /// let rest = parser.collect::<Result<Vec<_>, _>>()?;
    /// assert!(rest.iter().any(|(event, _)| event.scalar().is_some_and(|(v, _)| v == "healthy")));
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Errors
    /// Returns a source failure (including I/O, decoding, or cancellation errors supplied by the
    /// input). Source failures cannot be recovered and leave the parser exhausted.
    /// With comment emission enabled, also returns `ErrorKind::TooManyComments` if looking ahead
    /// would exceed the comment-buffer limit; parsing then stays exhausted until recovery is
    /// requested again.
    pub fn proceed_next_document(&mut self) -> Result<bool, ScanError> {
        // A consumed StreamEnd stays exhausted. A terminal error still needs recovery below.
        if self.stream_end_emitted && !self.failed {
            return Ok(false);
        }

        self.skip_document()?;
        let result = self.next_document_exists();
        match result {
            Ok(false) => {
                // Stay between documents so repeated calls preserve unread trailing comments
                // as well as StreamEnd instead of consuming them in the skip loop.
                self.at_document_end = true;
            }
            Err(_) => {
                self.current = None;
                self.current_error = None;
                #[cfg(feature = "comments")]
                {
                    self.queued_events.clear();
                    self.comment_scratch.clear();
                    self.deferred_error = None;
                }
                self.failed = true;
                self.stream_end_emitted = true;
            }
            Ok(true) => {}
        }
        result
    }

    fn skip_document(&mut self) -> Result<(), ScanError> {
        loop {
            if !self.failed {
                if self.at_document_end {
                    // The boundary was already reached, possibly by peek(). Discard its cached
                    // end event and let another proceed call skip the following document.
                    if matches!(self.current, Some((Event::DocumentEnd, _))) {
                        self.current = None;
                    }
                    self.at_document_end = false;
                    return Ok(());
                }
                // While the grammar state is valid, consume events through the current document.
                // If parsing fails, next_event_impl records the failure and we synchronize below.
                loop {
                    match self.next_event_impl() {
                        Ok((Event::DocumentEnd, _)) => {
                            self.at_document_end = false;
                            return Ok(());
                        }
                        Ok(event @ (Event::StreamEnd, _)) => {
                            // Leave EOF available for the caller's next read, just like peek().
                            self.current = Some(event);
                            return Ok(());
                        }
                        Ok(_) => {}
                        Err(_) => break,
                    }
                }
            }

            // A directive belongs to the document whose opening marker follows it. Abandon
            // that body as well, rather than accepting it after silently dropping its header.
            let failed_header = matches!(
                self.state,
                State::ImplicitDocumentStart | State::DocumentStart
            ) && self.scanner.in_directive_prefix();
            // Discard the failed grammar state and seek a boundary, retaining any marker that
            // lookahead already consumed. Source failures propagate instead of becoming EOF.
            self.recover_document()?;
            if !failed_header || !matches!(self.peek_token()?.1, QueuedTokenType::DocumentStart) {
                return Ok(());
            }
            // This opening marker belongs to the failed header. Loop to skip its body too.
        }
    }

    /// Probe only the next document's prefix, retaining comments and any syntax error for readers.
    fn next_document_exists(&mut self) -> Result<bool, ScanError> {
        if matches!(self.current, Some((Event::StreamEnd, _))) {
            return Ok(false);
        }

        #[cfg(feature = "comments")]
        if self.has_pending_document_directives() {
            // A header paused at a comment already establishes document presence. Leave EOF
            // or an invalid end marker for normal parsing, but retain terminal source failures.
            self.scanner.check_source_error()?;
            return Ok(true);
        }

        loop {
            let token = match self.peek_token() {
                Ok(token) => token,
                Err(error) => {
                    // Source failures can carry any ErrorKind. Consult the scanner's source
                    // latch rather than classifying the error by its kind.
                    self.scanner.check_source_error()?;
                    #[cfg(feature = "comments")]
                    {
                        self.deferred_error = Some(error);
                    }
                    #[cfg(not(feature = "comments"))]
                    {
                        self.current_error = Some(error);
                        self.failed = true;
                    }
                    return Ok(true);
                }
            };
            match token.1 {
                QueuedTokenType::StreamEnd => return Ok(false),
                QueuedTokenType::DocumentEnd => self.skip(),
                #[cfg(feature = "comments")]
                QueuedTokenType::Comment(_) => {
                    let mark = token.0.start;
                    if self.queued_events.len() >= self.max_buffered_comment_events {
                        return Err(ScanError::from_kind(mark, ErrorKind::TooManyComments));
                    }
                    let comment = self
                        .next_comment_event()?
                        .expect("comment token disappeared after peek");
                    self.queued_events.push_back(comment);
                }
                _ => return Ok(true),
            }
        }
    }

    fn recover_document(&mut self) -> Result<(), ScanError> {
        let result = self.scanner.proceed_next_document(self.token.take());
        self.current = None;
        self.current_error = None;
        self.pending_anchor = None;
        if let Err(error) = result {
            self.stream_end_emitted = true;
            return Err(error);
        }

        self.states.clear();
        self.state = State::ImplicitDocumentStart;
        self.block_level = 0;
        self.pending_key_indent = None;
        self.pending_empty_scalar_span = None;
        self.last_non_comment_event_end = None;
        #[cfg(feature = "comments")]
        {
            self.deferred_error = None;
            self.queued_events.clear();
            self.comment_scratch.clear();
            self.pending_node_anchor_id = None;
            self.pending_node_tag = None;
            self.pending_node_tag_span = None;
            self.pending_node_property_end = None;
            self.pending_document_version = None;
            self.pending_document_directives = false;
            self.pending_document_tag_handles.clear();
        }
        self.anchors.clear();
        self.clear_document_tags();
        self.failed = false;
        self.at_document_end = false;
        self.stream_end_emitted = false;
        Ok(())
    }

    /// Implementation function for [`Self::next_event`] without the `Option`.
    ///
    /// [`Self::next_event`] should conform to the expectations of an [`Iterator`] and return an
    /// option. This burdens the parser code. This function is used internally when an option is
    /// undesirable.
    fn next_event_impl<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        let result = self.next_event_inner();
        if result.is_err() {
            self.failed = true;
        }
        result
    }

    fn next_event_inner<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        let event = match self.current.take() {
            None if self
                .pending_anchor
                .as_ref()
                .is_some_and(|anchor| anchor.node_emitted) =>
            {
                let anchor = self
                    .pending_anchor
                    .take()
                    .expect("anchor metadata is ready");
                Ok((Event::Anchor(anchor.id, anchor.name), anchor.span))
            }
            None => {
                #[cfg(feature = "comments")]
                {
                    if let Some(event) = self.queued_events.pop_front() {
                        Ok(self.apply_pending_key_indent(event))
                    } else if let Some(error) = self.deferred_error.take() {
                        return Err(error);
                    } else if self.state == State::End {
                        self.parse()
                    } else if let Some(comment) = self.maybe_next_comment_event()? {
                        Ok(comment)
                    } else {
                        self.parse()
                    }
                }
                #[cfg(not(feature = "comments"))]
                {
                    self.parse()
                }
            }
            Some(v) => Ok(v),
        }?;

        // A node can be buffered behind comments. Wait until that exact node reaches the public
        // event stream before emitting its metadata, ahead of any further comments or children.
        if let Some(anchor) = &mut self.pending_anchor {
            anchor.node_emitted |= matches!(
                &event.0,
                Event::Scalar(_, _, id, _)
                    | Event::SequenceStart(_, id, _)
                    | Event::MappingStart(_, id, _)
                    if *id == anchor.id
            );
        }

        Ok(self.remember_non_comment_event_end(event))
    }

    /// Load the next event for [`ParserTrait::try_load`], exhausting the parser on a scan error.
    ///
    /// A scan error can interrupt a state transition, so the state machine must never run again
    /// afterwards. [`ParserTrait::next_event`] latches this itself; `try_load` bypasses it to
    /// avoid the `Option` wrapper and needs the same latch.
    fn next_event_for_load<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        let result = self.next_event_impl();
        if result.is_err() {
            self.stream_end_emitted = true;
        }
        result
    }

    fn apply_pending_key_indent<'a>(&mut self, (ev, span): (Event<'a>, Span)) -> (Event<'a>, Span) {
        if ev.is_node() {
            if let Some(indent) = self.pending_key_indent.take() {
                return (ev, span.with_indent(Some(indent)));
            }
        }

        (ev, span)
    }

    fn remember_non_comment_event_end<'a>(
        &mut self,
        (event, span): (Event<'a>, Span),
    ) -> (Event<'a>, Span) {
        if matches!(event, Event::Anchor(..)) {
            return (event, span);
        }
        #[cfg(feature = "comments")]
        if matches!(event, Event::Comment(..)) {
            return (event, span);
        }
        self.last_non_comment_event_end = Some(span.end);
        if matches!(event, Event::DocumentStart(..) | Event::DocumentEnd) {
            self.at_document_end = matches!(event, Event::DocumentEnd);
        }
        (event, span)
    }

    /// Peek at the next token from the scanner.
    fn peek_token(&mut self) -> Result<&QueuedToken<'_>, ScanError> {
        #[cfg(feature = "comments")]
        if let Some(error) = &self.deferred_error {
            return Err(error.clone());
        }

        match self.token {
            None => {
                self.token = Some(self.scan_next_token()?);
                Ok(self.token.as_ref().unwrap())
            }
            Some(ref tok) => Ok(tok),
        }
    }

    /// Extract and return the next token from the scanner.
    ///
    /// This function does _not_ make use of `self.token`.
    fn scan_next_token(&mut self) -> Result<QueuedToken<'input>, ScanError> {
        match self.scanner.next_queued_token()? {
            None => unreachable!("scanner ended before the parser consumed its stream-end token"),
            Some(tok) => Ok(tok),
        }
    }

    #[cfg(feature = "comments")]
    #[inline]
    fn maybe_next_comment_event<'a>(&mut self) -> Result<Option<(Event<'a>, Span)>, ScanError>
    where
        'input: 'a,
    {
        if self.scanner.comments_possible() {
            self.next_comment_event()
        } else {
            Ok(None)
        }
    }

    #[cfg(feature = "comments")]
    fn next_comment_event<'a>(&mut self) -> Result<Option<(Event<'a>, Span)>, ScanError>
    where
        'input: 'a,
    {
        let is_comment = {
            let token = self.peek_token()?;
            matches!(token.1, QueuedTokenType::Comment(_))
        };

        if !is_comment {
            return Ok(None);
        }

        let QueuedToken(span, token) = self.fetch_token();
        match token {
            QueuedTokenType::Comment(comment) => {
                let placement = self.refined_comment_placement(span, comment.placement());
                Ok(Some((Event::Comment(comment.into_text(), placement), span)))
            }
            _ => unreachable!("comment token disappeared after peek"),
        }
    }

    #[cfg(feature = "comments")]
    #[inline]
    fn next_comment_events(&mut self) -> Result<Vec<(Event<'input>, Span)>, ScanError> {
        if !self.scanner.comments_possible() {
            return Ok(Vec::new());
        }

        debug_assert_eq!(self.comment_scratch.len(), 0);
        loop {
            match self
                .peek_token()
                .map(|token| matches!(token.1, QueuedTokenType::Comment(_)))
            {
                Ok(true) => {}
                Err(error) if self.comment_scratch.is_empty() => return Err(error),
                Err(error) => {
                    debug_assert!(self.deferred_error.is_none());
                    self.deferred_error = Some(error);
                    return Ok(core::mem::take(&mut self.comment_scratch));
                }
                Ok(_) => {
                    // Keep the allocation when this position has no comments.
                    return Ok(if self.comment_scratch.is_empty() {
                        Vec::new()
                    } else {
                        core::mem::take(&mut self.comment_scratch)
                    });
                }
            }

            if self.comment_scratch.len() >= self.max_buffered_comment_events {
                self.comment_scratch.clear();
                return Err(ScanError::from_kind(
                    self.peek_token()?.0.start,
                    ErrorKind::TooManyComments,
                ));
            }

            let comment = match self.next_comment_event() {
                Ok(comment) => comment.expect("comment token disappeared after peek"),
                Err(error) => {
                    self.comment_scratch.clear();
                    return Err(error);
                }
            };
            self.comment_scratch.push(comment);
            if self.deferred_error.is_some() {
                return Ok(core::mem::take(&mut self.comment_scratch));
            }
        }
    }

    #[cfg(feature = "comments")]
    fn queue_tail_and_return_first(
        &mut self,
        mut events: Vec<(Event<'input>, Span)>,
    ) -> (Event<'input>, Span) {
        let first = {
            let mut drained = events.drain(..);
            let first = drained
                .next()
                .expect("event queue must contain at least one event");
            self.queued_events.extend(drained);
            first
        };
        self.comment_scratch = events;
        first
    }

    #[cfg(feature = "comments")]
    fn queue_event_by_span(
        &mut self,
        mut comments: Vec<(Event<'input>, Span)>,
        event: (Event<'input>, Span),
    ) -> (Event<'input>, Span) {
        let insert_at = comments
            .iter()
            .position(|(_, comment_span)| {
                comment_span.start.index() >= event.1.start.index()
                    && comment_span.end.index() >= event.1.end.index()
            })
            .unwrap_or(comments.len());
        comments.insert(insert_at, event);
        self.queue_tail_and_return_first(comments)
    }

    #[cfg(feature = "comments")]
    fn queue_two_events_by_span(
        &mut self,
        mut comments: Vec<(Event<'input>, Span)>,
        first: (Event<'input>, Span),
        second: (Event<'input>, Span),
    ) -> (Event<'input>, Span) {
        let insert_at = comments
            .iter()
            .position(|(_, comment_span)| {
                comment_span.start.index() >= first.1.start.index()
                    && comment_span.end.index() >= first.1.end.index()
            })
            .unwrap_or(comments.len());
        comments.reserve(2);
        comments.insert(insert_at, first);
        comments.insert(insert_at + 1, second);
        self.queue_tail_and_return_first(comments)
    }

    #[cfg(feature = "comments")]
    fn refined_comment_placement(&mut self, span: Span, placement: Placement) -> Placement {
        if placement == Placement::Right {
            return Placement::Right;
        }

        let next = match self.peek_token() {
            Ok(next) => next,
            Err(error) => {
                debug_assert!(self.deferred_error.is_none());
                self.deferred_error = Some(error);
                return placement;
            }
        };
        if matches!(next.1, QueuedTokenType::StreamEnd) {
            return Placement::Last;
        }

        if next.0.start.line() == span.end.line() + 1 {
            Placement::Above
        } else {
            Placement::Free
        }
    }

    /// Take the token buffered by [`Self::peek_token`].
    ///
    /// # Panics
    /// Panics if no token has been buffered.
    #[track_caller]
    fn fetch_token<'a>(&mut self) -> QueuedToken<'a>
    where
        'input: 'a,
    {
        self.token
            .take()
            .expect("fetch_token needs to be preceded by peek_token")
    }

    /// Skip the next token from the scanner.
    fn skip(&mut self) {
        self.token = None;
    }
    /// Pops the top-most state and make it the current state.
    ///
    /// # Panics
    /// Panics if the state stack is empty.
    #[track_caller]
    fn pop_state(&mut self) {
        self.state = self.states.pop().unwrap();
    }
    /// Push a new state atop the state stack.
    fn push_state(&mut self, state: State) {
        self.states.push(state);
    }

    fn start_block_collection(&mut self, mark: Marker) -> Result<(), ScanError> {
        if self.block_level >= self.block_nesting_limit {
            return Err(ScanError::from_kind(
                mark,
                ErrorKind::RecursionLimitExceeded,
            ));
        }
        self.block_level += 1;
        Ok(())
    }

    fn end_block_collection(&mut self) {
        debug_assert!(self.block_level > 0);
        self.block_level -= 1;
    }

    fn defer_parse_node<'a>(
        &mut self,
        node_state: State,
        return_state: State,
        block: bool,
        indentless_sequence: bool,
    ) -> ParseResult<'a>
    where
        'input: 'a,
    {
        self.push_state(return_state);
        self.state = node_state;
        #[cfg(feature = "comments")]
        if let Some(comment) = self.maybe_next_comment_event()? {
            return Ok(comment);
        }
        self.parse_node(block, indentless_sequence)
    }

    fn parse<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        if self.state == State::End {
            return Ok((Event::StreamEnd, Span::empty(self.scanner.mark())));
        }
        let event = self.state_machine()?;
        Ok(self.apply_pending_key_indent(event))
    }

    /// Load the YAML from the stream in `self`, pushing events into `recv`.
    ///
    /// The contents of the stream are parsed and the corresponding events are sent into the
    /// receiver. For detailed explanations about how events work, see [`EventReceiver`].
    ///
    /// If `multi` is set to `true`, the parser will allow parsing of multiple YAML documents
    /// inside the stream.
    ///
    /// Use this method when event handling is infallible. If receiver code can return an
    /// application error and should stop parsing, use [`Parser::try_load`] instead. If the caller
    /// should directly control when the next event is read, use [`Parser`]'s
    /// [`core::iter::Iterator`] implementation.
    ///
    /// Note that any [`EventReceiver`] is also a [`SpannedEventReceiver`], so implementing the
    /// former is enough to call this function.
    ///
    /// After a scan error, the parser is exhausted: [`Parser::peek`] and [`Parser::next_event`]
    /// return [`None`], and further calls to `load` or [`Parser::try_load`] return `Ok(())`
    /// without emitting events.
    ///
    /// # Example
    /// ```
    /// # use granit_parser::{Event, EventReceiver, Parser};
    /// # fn main() -> Result<(), granit_parser::ScanError> {
    /// struct EventSink<'input> {
    ///     events: Vec<Event<'input>>,
    /// }
    ///
    /// impl<'input> EventReceiver<'input> for EventSink<'input> {
    ///     fn on_event(&mut self, ev: Event<'input>) {
    ///         self.events.push(ev);
    ///     }
    /// }
    ///
    /// let mut parser = Parser::new_from_str("a: 1\n");
    /// let mut sink = EventSink { events: Vec::new() };
    ///
    /// parser.load(&mut sink, false)?;
    ///
    /// assert!(sink
    ///     .events
    ///     .iter()
    ///     .any(|ev| matches!(ev, Event::Scalar(value, ..) if value == "a")));
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Errors
    /// Returns `ScanError` when loading fails.
    pub fn load<R: SpannedEventReceiver<'input>>(
        &mut self,
        recv: &mut R,
        multi: bool,
    ) -> Result<(), ScanError> {
        ParserTrait::load(self, recv, multi)
    }

    /// Load the YAML from the stream in `self`, pushing events into `recv`.
    ///
    /// This is the fallible counterpart to [`Parser::load`]. If `recv` returns an error, parsing
    /// stops immediately and that error is returned as [`TryLoadError::Receiver`].
    ///
    /// If `multi` is set to `true`, the parser will allow parsing of multiple YAML documents
    /// inside the stream.
    ///
    /// If the receiver returns an error, the parser is left positioned immediately after the event
    /// that caused the receiver error. Callers should treat the parser as partially consumed.
    ///
    /// After a scan error, the parser is exhausted: [`Parser::peek`] and [`Parser::next_event`]
    /// return [`None`], and further calls to `try_load` or [`Parser::load`] return `Ok(())`
    /// without emitting events.
    ///
    /// # Example
    /// ```
    /// # use granit_parser::{Event, Parser, TryEventReceiver, TryLoadError};
    /// #[derive(Debug, PartialEq, Eq)]
    /// enum ValidationError {
    ///     ForbiddenScalar,
    /// }
    ///
    /// struct Validator;
    ///
    /// impl<'input> TryEventReceiver<'input> for Validator {
    ///     type Error = ValidationError;
    ///
    ///     fn on_event(&mut self, ev: Event<'input>) -> Result<(), Self::Error> {
    ///         if matches!(ev, Event::Scalar(value, ..) if value.as_ref() == "bad") {
    ///             Err(ValidationError::ForbiddenScalar)
    ///         } else {
    ///             Ok(())
    ///         }
    ///     }
    /// }
    ///
    /// let mut parser = Parser::new_from_str("value: bad\n");
    /// let mut validator = Validator;
    ///
    /// let err = parser.try_load(&mut validator, false).unwrap_err();
    ///
    /// assert_eq!(err, TryLoadError::Receiver(ValidationError::ForbiddenScalar));
    /// ```
    ///
    /// # Errors
    /// Returns [`TryLoadError::Scan`] when scanning or parsing the stream fails. Returns
    /// [`TryLoadError::Receiver`] when `recv` returns an error.
    pub fn try_load<R: TrySpannedEventReceiver<'input>>(
        &mut self,
        recv: &mut R,
        multi: bool,
    ) -> Result<(), TryLoadError<R::Error>> {
        ParserTrait::try_load(self, recv, multi)
    }

    fn state_machine<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        debug_print!("\n\x1B[;33mParser state: {:?} \x1B[;0m", self.state);

        match self.state {
            State::StreamStart => self.stream_start(),

            State::ImplicitDocumentStart => self.document_start(true),
            State::DocumentStart => self.document_start(false),
            State::DocumentContent => self.document_content(),
            State::DocumentEnd => self.document_end(),

            State::BlockNode => self.parse_node(true, false),
            State::BlockNodeOrIndentlessSequence => self.parse_node(true, true),
            State::FlowNode => self.parse_node(false, false),
            State::BlockMappingFirstKey => self.block_mapping_key(true),
            State::BlockMappingKey => self.block_mapping_key(false),
            #[cfg(feature = "comments")]
            State::BlockMappingKeyNode => self.block_mapping_key_node(),
            State::BlockMappingValue => self.block_mapping_value(),
            #[cfg(feature = "comments")]
            State::BlockMappingValueNode => self.block_mapping_value_node(),

            State::BlockSequenceFirstEntry => self.block_sequence_entry(true),
            State::BlockSequenceEntry => self.block_sequence_entry(false),
            #[cfg(feature = "comments")]
            State::BlockSequenceEntryNode => self.block_sequence_entry_node(),

            State::FlowSequenceFirstEntry => self.flow_sequence_entry(true),
            State::FlowSequenceEntry => self.flow_sequence_entry(false),

            State::FlowMappingFirstKey => self.flow_mapping_key(true),
            State::FlowMappingKey => self.flow_mapping_key(false),
            #[cfg(feature = "comments")]
            State::FlowMappingKeyNode => self.flow_mapping_key_node(),
            State::FlowMappingValue => self.flow_mapping_value(false),
            #[cfg(feature = "comments")]
            State::FlowMappingValueNode => self.flow_mapping_value_node(),

            State::IndentlessSequenceEntry => self.indentless_sequence_entry(),
            State::IndentlessSequenceEntryNode => self.indentless_sequence_entry_node(),

            State::FlowSequenceEntryMappingKey => self.flow_sequence_entry_mapping_key(),
            State::FlowSequenceEntryMappingValue => self.flow_sequence_entry_mapping_value(),
            #[cfg(feature = "comments")]
            State::FlowSequenceEntryMappingValueNode => {
                self.flow_sequence_entry_mapping_value_node()
            }
            State::FlowSequenceEntryMappingEnd => self.flow_sequence_entry_mapping_end(),
            State::FlowMappingEmptyValue => self.flow_mapping_value(true),

            State::End => unreachable!("end state is handled before state-machine dispatch"),
        }
    }

    fn stream_start<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        match *self.peek_token()? {
            QueuedToken(span, QueuedTokenType::StreamStart) => {
                self.state = State::ImplicitDocumentStart;
                self.skip();
                Ok((Event::StreamStart, span))
            }
            QueuedToken(span, _) => Err(ScanError::from_kind(
                span.start,
                ErrorKind::ExpectedStreamStart,
            )),
        }
    }

    #[cfg(feature = "comments")]
    fn has_pending_document_directives(&self) -> bool {
        self.pending_document_directives
            || self.pending_document_version.is_some()
            || !self.pending_document_tag_handles.is_empty()
    }

    fn document_start<'a>(&mut self, implicit: bool) -> ParseResult<'a>
    where
        'input: 'a,
    {
        // Resume a document start paused to emit comments before handling markers that are only
        // ignorable between documents. In particular, `...` is invalid while `---` is still
        // required after directives and must not be consumed by the loop below.
        #[cfg(feature = "comments")]
        if self.has_pending_document_directives() {
            return self.explicit_document_start();
        }

        while let QueuedTokenType::DocumentEnd = self.peek_token()?.1 {
            self.skip();
        }

        // Anchors are scoped to a single document.
        self.anchors.clear();

        // Skipping a leading document-end marker can expose a comment that the normal
        // `next_event_impl` pre-dispatch check could not see yet. Emit it before deciding whether
        // another document starts; presentation-only comments must not create an implicit document.
        #[cfg(feature = "comments")]
        if let Some(comment) = self.maybe_next_comment_event()? {
            return Ok(comment);
        }

        match *self.peek_token()? {
            QueuedToken(span, QueuedTokenType::StreamEnd) => {
                self.state = State::End;
                self.skip();
                Ok((Event::StreamEnd, span))
            }
            QueuedToken(
                _,
                QueuedTokenType::VersionDirective(..)
                | QueuedTokenType::TagDirective(..)
                | QueuedTokenType::ReservedDirective(..)
                | QueuedTokenType::DocumentStart,
            ) => {
                // explicit document
                self.explicit_document_start()
            }
            QueuedToken(span, _) if implicit => {
                self.parser_process_directives(None, false, BTreeSet::new())?;
                self.push_state(State::DocumentEnd);
                self.state = State::BlockNode;
                Ok((Event::DocumentStart(false, None), span))
            }
            _ => {
                // explicit document
                self.explicit_document_start()
            }
        }
    }

    fn parser_process_directives(
        &mut self,
        mut version: Option<YamlVersion>,
        continuing: bool,
        mut document_tag_handles: BTreeSet<Cow<'input, str>>,
    ) -> Result<(Option<YamlVersion>, BTreeSet<Cow<'input, str>>), ScanError> {
        // Keep retained handles on the parser so any early error, including scanner errors,
        // leaves them available for document recovery. Comment pauses continue the same header.
        if !continuing && !self.keep_tags {
            self.tags.clear();
        }

        loop {
            let is_directive = matches!(
                self.peek_token()?.1,
                QueuedTokenType::VersionDirective(..)
                    | QueuedTokenType::TagDirective(..)
                    | QueuedTokenType::ReservedDirective(..)
            );
            if !is_directive {
                break;
            }

            let QueuedToken(span, token) = self.fetch_token();
            match token {
                QueuedTokenType::VersionDirective(major, minor) => {
                    if version.is_some() {
                        return Err(ScanError::from_kind(
                            span.start,
                            ErrorKind::DuplicateVersionDirective,
                        ));
                    }
                    if major != 1 {
                        return Err(ScanError::from_kind(
                            span.start,
                            ErrorKind::UnsupportedYamlMajorVersion,
                        ));
                    }
                    version = Some(YamlVersion::new(major, minor));
                }
                QueuedTokenType::TagDirective(handle, prefix) => {
                    if !document_tag_handles.insert(handle.clone()) {
                        return Err(ScanError::from_kind(
                            span.start,
                            ErrorKind::DuplicateTagDirective,
                        ));
                    }
                    self.tags.insert(handle, prefix);
                }
                QueuedTokenType::ReservedDirective(_, _) => {
                    // Reserved directives are ignored
                }
                _ => unreachable!("non-directive token passed the directive guard"),
            }
        }

        Ok((version, document_tag_handles))
    }

    fn explicit_document_start<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        #[cfg(feature = "comments")]
        let version = {
            let pending_version = self.pending_document_version.take();
            let continuing_directives = core::mem::take(&mut self.pending_document_directives);
            let pending_tag_handles = core::mem::take(&mut self.pending_document_tag_handles);
            let (version, document_tag_handles) = self.parser_process_directives(
                pending_version,
                continuing_directives,
                pending_tag_handles,
            )?;
            if let Some(comment) = self.maybe_next_comment_event()? {
                self.pending_document_version = version;
                self.pending_document_directives = true;
                self.pending_document_tag_handles = document_tag_handles;
                return Ok(comment);
            }
            version
        };
        #[cfg(not(feature = "comments"))]
        let (version, _) = self.parser_process_directives(None, false, BTreeSet::new())?;
        match *self.peek_token()? {
            QueuedToken(mark, QueuedTokenType::DocumentStart) => {
                self.push_state(State::DocumentEnd);
                self.state = State::DocumentContent;
                self.skip();
                Ok((Event::DocumentStart(true, version), mark))
            }
            QueuedToken(span, _) => Err(ScanError::from_kind(
                span.start,
                ErrorKind::ExpectedDocumentStart,
            )),
        }
    }

    fn document_content<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        if let QueuedToken(
            mark,
            QueuedTokenType::VersionDirective(..)
            | QueuedTokenType::TagDirective(..)
            | QueuedTokenType::ReservedDirective(..)
            | QueuedTokenType::DocumentStart
            | QueuedTokenType::DocumentEnd
            | QueuedTokenType::StreamEnd,
        ) = *self.peek_token()?
        {
            self.pop_state();
            let span = self
                .last_non_comment_event_end
                .map_or_else(|| Span::empty(mark.start), Span::empty);
            Ok((Event::empty_scalar(), span))
        } else {
            self.state = State::BlockNode;
            self.parse_node(true, false)
        }
    }

    fn document_end<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        let mut explicit_end = false;
        let span: Span = match *self.peek_token()? {
            QueuedToken(span, QueuedTokenType::DocumentEnd) => {
                explicit_end = true;
                self.skip();
                span
            }
            QueuedToken(span, _) => self
                .last_non_comment_event_end
                .map_or_else(|| Span::empty(span.start), Span::empty),
        };

        self.clear_document_tags();
        if explicit_end {
            self.state = State::ImplicitDocumentStart;
        } else {
            if let QueuedToken(
                span,
                QueuedTokenType::VersionDirective(..)
                | QueuedTokenType::TagDirective(..)
                | QueuedTokenType::ReservedDirective(..),
            ) = *self.peek_token()?
            {
                return Err(ScanError::from_kind(
                    span.start,
                    ErrorKind::MissingDocumentEndBeforeDirective,
                ));
            }
            self.state = State::DocumentStart;
        }

        Ok((Event::DocumentEnd, span))
    }

    fn clear_document_tags(&mut self) {
        if self.keep_tags {
            // Default handles never persist, even with the non-standard keep_tags policy.
            self.tags.remove("!!");
            self.tags.remove("!");
        } else {
            self.tags.clear();
        }
    }

    fn register_anchor(&mut self, name: Cow<'input, str>, mark: &Span) -> Result<usize, ScanError> {
        // YAML permits anchor names to be reused. Aliases resolve to the most recent definition.
        let new_id = self.anchor_id_count;
        self.anchor_id_count = self
            .anchor_id_count
            .checked_add(1)
            .ok_or_else(|| ScanError::from_kind(mark.start, ErrorKind::AnchorCountOverflow))?;
        if self.emit_anchor_events {
            debug_assert!(self.pending_anchor.is_none());
            self.pending_anchor = Some(PendingAnchor {
                id: new_id,
                name: name.clone(),
                span: *mark,
                node_emitted: false,
            });
        }
        self.anchors.insert(name, new_id);
        Ok(new_id)
    }

    #[cfg(feature = "comments")]
    fn save_pending_node_properties(
        &mut self,
        anchor_id: Option<usize>,
        tag: Option<Cow<'input, Tag>>,
        tag_span: Option<(Marker, u32)>,
        property_end: Option<Marker>,
    ) {
        self.pending_node_anchor_id = anchor_id;
        self.pending_node_tag = tag;
        self.pending_node_tag_span = tag_span;
        self.pending_node_property_end = property_end;
    }

    fn attach_tag_span(
        event: Event<'_>,
        span: Span,
        tag_span: Option<(Marker, u32)>,
    ) -> (Event<'_>, Span) {
        (event, span.with_tag_span(tag_span))
    }

    #[allow(clippy::too_many_lines)]
    fn parse_node<'a>(&mut self, block: bool, indentless_sequence: bool) -> ParseResult<'a>
    where
        'input: 'a,
    {
        #[cfg(feature = "comments")]
        if let Some(comment) = self.maybe_next_comment_event()? {
            return Ok(comment);
        }

        #[cfg(feature = "comments")]
        let (mut anchor_id, mut tag, mut tag_span, mut property_end) = (
            self.pending_node_anchor_id.take(),
            self.pending_node_tag.take(),
            self.pending_node_tag_span.take(),
            self.pending_node_property_end.take(),
        );
        #[cfg(not(feature = "comments"))]
        let (mut anchor_id, mut tag, mut tag_span, mut property_end) = (None, None, None, None);
        match *self.peek_token()? {
            QueuedToken(_, QueuedTokenType::Alias(_)) if anchor_id.is_none() && tag.is_none() => {
                self.pop_state();
                let QueuedToken(span, QueuedTokenType::Alias(name)) = self.fetch_token() else {
                    unreachable!("alias token disappeared after peek")
                };
                return match self.anchors.get(&*name) {
                    None if self.emit_unresolved_aliases => {
                        Ok((Event::UnresolvedAlias(name), span))
                    }
                    None => Err(ScanError::from_kind(span.start, ErrorKind::UnknownAnchor)),
                    Some(id) => Ok((Event::Alias(*id), span)),
                };
            }
            QueuedToken(_, QueuedTokenType::Anchor(_)) if anchor_id.is_none() => {
                let QueuedToken(span, QueuedTokenType::Anchor(name)) = self.fetch_token() else {
                    unreachable!("anchor token disappeared after peek")
                };
                anchor_id = Some(self.register_anchor(name, &span)?);
                property_end = Some(span.end);
                if tag.is_none() && matches!(self.peek_token()?.1, QueuedTokenType::Tag(..)) {
                    let QueuedToken(tag_mark, QueuedTokenType::Tag(handle, suffix)) =
                        self.fetch_token()
                    else {
                        unreachable!("tag token disappeared after peek")
                    };
                    tag_span = Some((tag_mark.start, u32::try_from(tag_mark.len()).unwrap_or(0)));
                    tag = Some(self.resolve_tag(tag_mark, handle, suffix)?);
                    property_end = Some(tag_mark.end);
                }
                #[cfg(feature = "comments")]
                if let Some(comment) = self.maybe_next_comment_event()? {
                    self.save_pending_node_properties(anchor_id, tag, tag_span, property_end);
                    return Ok(comment);
                }
            }
            QueuedToken(mark, QueuedTokenType::Tag(..)) if tag.is_none() => {
                let QueuedTokenType::Tag(handle, suffix) = self.fetch_token().1 else {
                    unreachable!("tag token disappeared after peek")
                };
                tag_span = Some((mark.start, u32::try_from(mark.len()).unwrap_or(0)));
                property_end = Some(mark.end);
                tag = Some(self.resolve_tag(mark, handle, suffix)?);
                if anchor_id.is_none() {
                    if let QueuedTokenType::Anchor(_) = &self.peek_token()?.1 {
                        let QueuedToken(mark, QueuedTokenType::Anchor(name)) = self.fetch_token()
                        else {
                            unreachable!("anchor token disappeared after peek")
                        };
                        anchor_id = Some(self.register_anchor(name, &mark)?);
                        property_end = Some(mark.end);
                    }
                }
                #[cfg(feature = "comments")]
                if let Some(comment) = self.maybe_next_comment_event()? {
                    self.save_pending_node_properties(anchor_id, tag, tag_span, property_end);
                    return Ok(comment);
                }
            }
            _ => {}
        }
        let has_anchor = anchor_id.is_some();
        let anchor_id = anchor_id.unwrap_or(0);
        match *self.peek_token()? {
            QueuedToken(mark, QueuedTokenType::BlockEntry) if indentless_sequence => {
                self.start_block_collection(mark.start)?;
                self.skip();
                let start = (
                    Event::SequenceStart(StructureStyle::Block, anchor_id, tag),
                    mark.with_tag_span(tag_span),
                );
                #[cfg(feature = "comments")]
                {
                    let comments = match self.next_comment_events() {
                        Ok(comments) => comments,
                        Err(error) if !matches!(error.kind(), ErrorKind::TooManyComments) => {
                            // `StrInput` can prove that a source has no comments and skips this
                            // lookahead, while streaming inputs must probe for one. If that probe
                            // discovers a later scanner error, the input backend must not determine
                            // whether this already-recognized sequence start is emitted first.
                            debug_assert!(self.deferred_error.is_none());
                            self.deferred_error = Some(error);
                            self.pending_empty_scalar_span = Some(mark);
                            self.state = State::IndentlessSequenceEntryNode;
                            return Ok(start);
                        }
                        Err(error) => return Err(error),
                    };
                    if comments.is_empty() {
                        self.pending_empty_scalar_span = Some(mark);
                        self.state = State::IndentlessSequenceEntryNode;
                        Ok(start)
                    } else if let Ok(QueuedToken(
                        _,
                        QueuedTokenType::BlockEntry
                        | QueuedTokenType::Key
                        | QueuedTokenType::Value
                        | QueuedTokenType::BlockEnd,
                    )) = self.peek_token()
                    {
                        self.state = State::IndentlessSequenceEntry;
                        Ok(self.queue_two_events_by_span(
                            comments,
                            start,
                            (Event::empty_scalar(), mark),
                        ))
                    } else {
                        self.pending_empty_scalar_span = Some(mark);
                        self.state = State::IndentlessSequenceEntryNode;
                        Ok(self.queue_event_by_span(comments, start))
                    }
                }
                #[cfg(not(feature = "comments"))]
                {
                    self.pending_empty_scalar_span = Some(mark);
                    self.state = State::IndentlessSequenceEntryNode;
                    Ok(start)
                }
            }
            QueuedToken(_, QueuedTokenType::Scalar(..)) => {
                self.pop_state();
                let QueuedToken(mark, QueuedTokenType::Scalar(style, v)) = self.fetch_token()
                else {
                    unreachable!("scalar token disappeared after peek")
                };
                Ok(Self::attach_tag_span(
                    Event::Scalar(v, style, anchor_id, tag),
                    mark,
                    tag_span,
                ))
            }
            QueuedToken(mark, QueuedTokenType::FlowSequenceStart) => {
                self.state = State::FlowSequenceFirstEntry;
                self.skip();
                Ok(Self::attach_tag_span(
                    Event::SequenceStart(StructureStyle::Flow, anchor_id, tag),
                    mark,
                    tag_span,
                ))
            }
            QueuedToken(mark, QueuedTokenType::FlowMappingStart) => {
                self.state = State::FlowMappingFirstKey;
                self.skip();
                Ok(Self::attach_tag_span(
                    Event::MappingStart(StructureStyle::Flow, anchor_id, tag),
                    mark,
                    tag_span,
                ))
            }
            QueuedToken(mark, QueuedTokenType::BlockSequenceStart) if block => {
                self.start_block_collection(mark.start)?;
                self.state = State::BlockSequenceFirstEntry;
                self.skip();
                Ok(Self::attach_tag_span(
                    Event::SequenceStart(StructureStyle::Block, anchor_id, tag),
                    mark,
                    tag_span,
                ))
            }
            QueuedToken(mark, QueuedTokenType::BlockMappingStart) if block => {
                self.start_block_collection(mark.start)?;
                self.state = State::BlockMappingFirstKey;
                self.skip();
                Ok(Self::attach_tag_span(
                    Event::MappingStart(StructureStyle::Block, anchor_id, tag),
                    mark,
                    tag_span,
                ))
            }
            // ex 7.2, an empty scalar can follow a secondary tag
            QueuedToken(mark, _) if tag.is_some() || has_anchor => {
                self.pop_state();
                let span = property_end.map_or_else(|| Span::empty(mark.start), Span::empty);
                Ok(Self::attach_tag_span(
                    Event::empty_scalar_with_anchor(anchor_id, tag),
                    span,
                    tag_span,
                ))
            }
            QueuedToken(span, _) => {
                let kind = match self.state {
                    State::FlowSequenceFirstEntry | State::FlowSequenceEntry => {
                        ErrorKind::UnexpectedEofFlowSequence
                    }
                    State::FlowMappingFirstKey
                    | State::FlowMappingKey
                    | State::FlowMappingValue
                    | State::FlowMappingEmptyValue => ErrorKind::UnexpectedEofFlowMapping,
                    State::FlowSequenceEntryMappingKey
                    | State::FlowSequenceEntryMappingValue
                    | State::FlowSequenceEntryMappingEnd
                    | State::FlowNode => ErrorKind::UnexpectedEofImplicitFlowMapping,
                    State::BlockSequenceFirstEntry
                    | State::BlockSequenceEntry
                    | State::BlockNode => ErrorKind::UnexpectedEofBlockSequence,
                    State::BlockMappingFirstKey
                    | State::BlockMappingKey
                    | State::BlockMappingValue
                    | State::BlockNodeOrIndentlessSequence => ErrorKind::UnexpectedEofBlockMapping,
                    _ => ErrorKind::ExpectedNodeContent,
                };
                Err(ScanError::from_kind(span.start, kind))
            }
        }
    }

    fn block_mapping_key<'a>(&mut self, _first: bool) -> ParseResult<'a>
    where
        'input: 'a,
    {
        match *self.peek_token()? {
            QueuedToken(_, QueuedTokenType::Key) => {
                // Indentation is only meaningful for block mapping keys.
                if let QueuedToken(key_span, QueuedTokenType::Key) = *self.peek_token()? {
                    self.pending_key_indent = Some(key_span.start.col());
                }
                self.skip();
                #[cfg(feature = "comments")]
                if let Some(comment) = self.maybe_next_comment_event()? {
                    self.state = State::BlockMappingKeyNode;
                    return Ok(comment);
                }
                self.block_mapping_key_node()
            }
            // A missing block-mapping key before `:` is represented as an empty scalar.
            QueuedToken(mark, QueuedTokenType::Value) => {
                self.state = State::BlockMappingValue;
                Ok((Event::empty_scalar(), Span::empty(mark.start)))
            }
            QueuedToken(mark, QueuedTokenType::BlockEnd) => {
                self.end_block_collection();
                self.pop_state();
                self.skip();
                Ok((Event::MappingEnd, mark))
            }
            QueuedToken(span, _) => Err(ScanError::from_kind(
                span.start,
                ErrorKind::ExpectedBlockMappingKey,
            )),
        }
    }

    fn block_mapping_key_node<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        if let QueuedToken(
            mark,
            QueuedTokenType::Key | QueuedTokenType::Value | QueuedTokenType::BlockEnd,
        ) = *self.peek_token()?
        {
            self.state = State::BlockMappingValue;
            Ok((Event::empty_scalar(), Span::empty(mark.start)))
        } else {
            self.defer_parse_node(
                State::BlockNodeOrIndentlessSequence,
                State::BlockMappingValue,
                true,
                true,
            )
        }
    }

    fn block_mapping_value<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        match *self.peek_token()? {
            QueuedToken(mark, QueuedTokenType::Value) => {
                self.skip();
                #[cfg(feature = "comments")]
                {
                    let comments = self.next_comment_events()?;
                    if !comments.is_empty() {
                        if let Ok(QueuedToken(
                            _,
                            QueuedTokenType::Key
                            | QueuedTokenType::Value
                            | QueuedTokenType::BlockEnd,
                        )) = self.peek_token()
                        {
                            self.state = State::BlockMappingKey;
                            return Ok(
                                self.queue_event_by_span(comments, (Event::empty_scalar(), mark))
                            );
                        }
                        self.pending_empty_scalar_span = Some(mark);
                        self.state = State::BlockMappingValueNode;
                        return Ok(self.queue_tail_and_return_first(comments));
                    }
                }
                self.block_mapping_value_node_with_empty_span(mark)
            }
            QueuedToken(mark, _) => {
                self.state = State::BlockMappingKey;
                Ok((Event::empty_scalar(), Span::empty(mark.start)))
            }
        }
    }

    #[cfg(feature = "comments")]
    fn block_mapping_value_node<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        // Peek before taking the span so that a scanner error leaves this state intact.
        self.peek_token()?;
        let Some(mark) = self.pending_empty_scalar_span.take() else {
            unreachable!(
                "block mapping value-node state entered without a pending empty-scalar span"
            )
        };
        self.block_mapping_value_node_with_empty_span(mark)
    }

    fn block_mapping_value_node_with_empty_span<'a>(&mut self, mark: Span) -> ParseResult<'a>
    where
        'input: 'a,
    {
        if let QueuedToken(
            _,
            QueuedTokenType::Key | QueuedTokenType::Value | QueuedTokenType::BlockEnd,
        ) = *self.peek_token()?
        {
            self.state = State::BlockMappingKey;
            Ok((Event::empty_scalar(), mark))
        } else {
            self.defer_parse_node(
                State::BlockNodeOrIndentlessSequence,
                State::BlockMappingKey,
                true,
                true,
            )
        }
    }

    fn flow_mapping_key<'a>(&mut self, first: bool) -> ParseResult<'a>
    where
        'input: 'a,
    {
        let span: Span =
            if let QueuedToken(mark, QueuedTokenType::FlowMappingEnd) = *self.peek_token()? {
                mark
            } else {
                if !first {
                    match *self.peek_token()? {
                        QueuedToken(_, QueuedTokenType::FlowEntry) => {
                            self.skip();
                            #[cfg(feature = "comments")]
                            if let Some(comment) = self.maybe_next_comment_event()? {
                                self.state = State::FlowMappingFirstKey;
                                return Ok(comment);
                            }
                        }
                        QueuedToken(span, _) => {
                            return Err(ScanError::from_kind(
                                span.start,
                                ErrorKind::ExpectedFlowMappingSeparator,
                            ))
                        }
                    }
                }

                match *self.peek_token()? {
                    QueuedToken(_, QueuedTokenType::Key) => {
                        self.skip();
                        #[cfg(feature = "comments")]
                        if let Some(comment) = self.maybe_next_comment_event()? {
                            self.state = State::FlowMappingKeyNode;
                            return Ok(comment);
                        }
                        return self.flow_mapping_key_node();
                    }
                    QueuedToken(marker, QueuedTokenType::Value) => {
                        self.state = State::FlowMappingValue;
                        return Ok((Event::empty_scalar(), Span::empty(marker.start)));
                    }
                    QueuedToken(_, QueuedTokenType::FlowMappingEnd) => (),
                    _ => {
                        return self.defer_parse_node(
                            State::FlowNode,
                            State::FlowMappingEmptyValue,
                            false,
                            false,
                        );
                    }
                }

                self.peek_token()?.0
            };

        self.pop_state();
        self.skip();
        Ok((Event::MappingEnd, span))
    }

    fn flow_mapping_key_node<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        if let QueuedToken(
            mark,
            QueuedTokenType::Value | QueuedTokenType::FlowEntry | QueuedTokenType::FlowMappingEnd,
        ) = *self.peek_token()?
        {
            self.state = State::FlowMappingValue;
            Ok((Event::empty_scalar(), Span::empty(mark.start)))
        } else {
            self.defer_parse_node(State::FlowNode, State::FlowMappingValue, false, false)
        }
    }

    fn flow_mapping_value<'a>(&mut self, empty: bool) -> ParseResult<'a>
    where
        'input: 'a,
    {
        let span: Span = {
            if empty {
                let QueuedToken(mark, _) = *self.peek_token()?;
                self.state = State::FlowMappingKey;
                return Ok((Event::empty_scalar(), Span::empty(mark.start)));
            }
            match *self.peek_token()? {
                QueuedToken(span, QueuedTokenType::Value) => {
                    self.skip();
                    #[cfg(feature = "comments")]
                    {
                        let comments = self.next_comment_events()?;
                        if comments.is_empty() {
                            return self.flow_mapping_value_node_with_empty_span(span);
                        }
                        if let Ok(QueuedToken(
                            _,
                            QueuedTokenType::FlowEntry | QueuedTokenType::FlowMappingEnd,
                        )) = self.peek_token()
                        {
                            self.state = State::FlowMappingKey;
                            return Ok(
                                self.queue_event_by_span(comments, (Event::empty_scalar(), span))
                            );
                        }

                        self.pending_empty_scalar_span = Some(span);
                        self.state = State::FlowMappingValueNode;
                        return Ok(self.queue_tail_and_return_first(comments));
                    }
                    #[cfg(not(feature = "comments"))]
                    return self.flow_mapping_value_node_with_empty_span(span);
                }
                QueuedToken(marker, _) => Span::empty(marker.start),
            }
        };

        self.state = State::FlowMappingKey;
        Ok((Event::empty_scalar(), span))
    }

    #[cfg(feature = "comments")]
    fn flow_mapping_value_node<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        // Peek before taking the span so that a scanner error leaves this state intact.
        self.peek_token()?;
        let Some(mark) = self.pending_empty_scalar_span.take() else {
            unreachable!(
                "flow mapping value-node state entered without a pending empty-scalar span"
            )
        };
        self.flow_mapping_value_node_with_empty_span(mark)
    }

    fn flow_mapping_value_node_with_empty_span<'a>(&mut self, mark: Span) -> ParseResult<'a>
    where
        'input: 'a,
    {
        match self.peek_token()?.1 {
            QueuedTokenType::FlowEntry | QueuedTokenType::FlowMappingEnd => {
                self.state = State::FlowMappingKey;
                Ok((Event::empty_scalar(), mark))
            }
            _ => self.defer_parse_node(State::FlowNode, State::FlowMappingKey, false, false),
        }
    }

    fn flow_sequence_entry<'a>(&mut self, first: bool) -> ParseResult<'a>
    where
        'input: 'a,
    {
        match *self.peek_token()? {
            QueuedToken(mark, QueuedTokenType::FlowSequenceEnd) => {
                self.pop_state();
                self.skip();
                return Ok((Event::SequenceEnd, mark));
            }
            QueuedToken(_, QueuedTokenType::FlowEntry) if !first => {
                self.skip();
                #[cfg(feature = "comments")]
                if let Some(comment) = self.maybe_next_comment_event()? {
                    self.state = State::FlowSequenceFirstEntry;
                    return Ok(comment);
                }
            }
            QueuedToken(span, _) if !first => {
                return Err(ScanError::from_kind(
                    span.start,
                    ErrorKind::ExpectedFlowSequenceSeparator,
                ));
            }
            _ => { /* next */ }
        }
        match *self.peek_token()? {
            QueuedToken(mark, QueuedTokenType::FlowSequenceEnd) => {
                self.pop_state();
                self.skip();
                Ok((Event::SequenceEnd, mark))
            }
            QueuedToken(mark, QueuedTokenType::Key) => {
                self.state = State::FlowSequenceEntryMappingKey;
                self.skip();
                Ok((Event::MappingStart(StructureStyle::Flow, 0, None), mark))
            }
            _ => self.defer_parse_node(State::FlowNode, State::FlowSequenceEntry, false, false),
        }
    }

    fn indentless_sequence_entry<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        match *self.peek_token()? {
            QueuedToken(mark, QueuedTokenType::BlockEntry) => {
                self.skip();
                #[cfg(feature = "comments")]
                {
                    let comments = self.next_comment_events()?;
                    if !comments.is_empty() {
                        if let Ok(QueuedToken(
                            _,
                            QueuedTokenType::BlockEntry
                            | QueuedTokenType::Key
                            | QueuedTokenType::Value
                            | QueuedTokenType::BlockEnd,
                        )) = self.peek_token()
                        {
                            self.state = State::IndentlessSequenceEntry;
                            return Ok(
                                self.queue_event_by_span(comments, (Event::empty_scalar(), mark))
                            );
                        }
                        self.pending_empty_scalar_span = Some(mark);
                        self.state = State::IndentlessSequenceEntryNode;
                        return Ok(self.queue_tail_and_return_first(comments));
                    }
                }
                self.indentless_sequence_entry_node_with_empty_span(mark)
            }
            QueuedToken(mark, _) => {
                self.end_block_collection();
                self.pop_state();
                // The token that ends an indentless sequence belongs to the enclosing mapping
                // (`? key`, `key:`, block end); the end event is empty, at that token's start.
                Ok((Event::SequenceEnd, Span::empty(mark.start)))
            }
        }
    }

    fn indentless_sequence_entry_node<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        // Peek before taking the span so that a scanner error leaves this state intact.
        self.peek_token()?;
        let Some(mark) = self.pending_empty_scalar_span.take() else {
            unreachable!(
                "indentless sequence entry-node state entered without a pending empty-scalar span"
            )
        };
        self.indentless_sequence_entry_node_with_empty_span(mark)
    }

    fn indentless_sequence_entry_node_with_empty_span<'a>(&mut self, mark: Span) -> ParseResult<'a>
    where
        'input: 'a,
    {
        if let QueuedToken(
            _,
            QueuedTokenType::BlockEntry
            | QueuedTokenType::Key
            | QueuedTokenType::Value
            | QueuedTokenType::BlockEnd,
        ) = *self.peek_token()?
        {
            self.state = State::IndentlessSequenceEntry;
            Ok((Event::empty_scalar(), mark))
        } else {
            self.defer_parse_node(
                State::BlockNode,
                State::IndentlessSequenceEntry,
                true,
                false,
            )
        }
    }

    fn block_sequence_entry<'a>(&mut self, _first: bool) -> ParseResult<'a>
    where
        'input: 'a,
    {
        match *self.peek_token()? {
            QueuedToken(mark, QueuedTokenType::BlockEnd) => {
                self.end_block_collection();
                self.pop_state();
                self.skip();
                Ok((Event::SequenceEnd, mark))
            }
            QueuedToken(mark, QueuedTokenType::BlockEntry) => {
                self.skip();
                #[cfg(feature = "comments")]
                {
                    let comments = self.next_comment_events()?;
                    if !comments.is_empty() {
                        if let Ok(QueuedToken(
                            _,
                            QueuedTokenType::BlockEntry | QueuedTokenType::BlockEnd,
                        )) = self.peek_token()
                        {
                            self.state = State::BlockSequenceEntry;
                            return Ok(
                                self.queue_event_by_span(comments, (Event::empty_scalar(), mark))
                            );
                        }
                        self.pending_empty_scalar_span = Some(mark);
                        self.state = State::BlockSequenceEntryNode;
                        return Ok(self.queue_tail_and_return_first(comments));
                    }
                }
                self.block_sequence_entry_node_with_empty_span(mark)
            }
            QueuedToken(span, _) => Err(ScanError::from_kind(
                span.start,
                ErrorKind::ExpectedBlockSequenceEntry,
            )),
        }
    }

    #[cfg(feature = "comments")]
    fn block_sequence_entry_node<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        // Peek before taking the span so that a scanner error leaves this state intact.
        self.peek_token()?;
        let Some(mark) = self.pending_empty_scalar_span.take() else {
            unreachable!(
                "block sequence entry-node state entered without a pending empty-scalar span"
            )
        };
        self.block_sequence_entry_node_with_empty_span(mark)
    }

    fn block_sequence_entry_node_with_empty_span<'a>(&mut self, mark: Span) -> ParseResult<'a>
    where
        'input: 'a,
    {
        if let QueuedToken(_, QueuedTokenType::BlockEntry | QueuedTokenType::BlockEnd) =
            *self.peek_token()?
        {
            self.state = State::BlockSequenceEntry;
            Ok((Event::empty_scalar(), mark))
        } else {
            self.defer_parse_node(State::BlockNode, State::BlockSequenceEntry, true, false)
        }
    }

    fn flow_sequence_entry_mapping_key<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        if let QueuedToken(mark, QueuedTokenType::FlowEntry | QueuedTokenType::FlowSequenceEnd) =
            *self.peek_token()?
        {
            self.state = State::FlowSequenceEntryMappingValue;
            Ok((Event::empty_scalar(), Span::empty(mark.start)))
        } else {
            self.defer_parse_node(
                State::FlowNode,
                State::FlowSequenceEntryMappingValue,
                false,
                false,
            )
        }
    }

    fn flow_sequence_entry_mapping_value<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        match *self.peek_token()? {
            QueuedToken(_, QueuedTokenType::Value) => {
                self.skip();
                #[cfg(feature = "comments")]
                if let Some(comment) = self.maybe_next_comment_event()? {
                    self.state = State::FlowSequenceEntryMappingValueNode;
                    return Ok(comment);
                }
                self.flow_sequence_entry_mapping_value_node()
            }
            QueuedToken(mark, _) => {
                self.state = State::FlowSequenceEntryMappingEnd;
                Ok((Event::empty_scalar(), Span::empty(mark.start)))
            }
        }
    }

    fn flow_sequence_entry_mapping_value_node<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        let QueuedToken(span, ref tok) = *self.peek_token()?;
        if matches!(
            tok,
            QueuedTokenType::FlowEntry | QueuedTokenType::FlowSequenceEnd
        ) {
            self.state = State::FlowSequenceEntryMappingEnd;
            Ok((Event::empty_scalar(), Span::empty(span.start)))
        } else {
            self.defer_parse_node(
                State::FlowNode,
                State::FlowSequenceEntryMappingEnd,
                false,
                false,
            )
        }
    }

    #[allow(clippy::unnecessary_wraps)]
    fn flow_sequence_entry_mapping_end<'a>(&mut self) -> ParseResult<'a>
    where
        'input: 'a,
    {
        self.state = State::FlowSequenceEntry;
        let QueuedToken(span, _) = *self.peek_token()?;
        Ok((Event::MappingEnd, Span::empty(span.start)))
    }

    /// Resolve a tag from the handle and the suffix.
    fn resolve_tag(
        &self,
        span: Span,
        handle: Cow<'input, str>,
        suffix: Cow<'input, str>,
    ) -> Result<Cow<'input, Tag>, ScanError> {
        let original_handle = own_tag_component(handle);
        let suffix = own_tag_component(suffix);
        let handle = if original_handle.is_empty() && suffix == "!" {
            // Bare "!" is a non-specific tag, not a primary handle to expand with %TAG.
            Cow::Borrowed("")
        } else if let Some(prefix) = self.tags.get(original_handle.as_ref()) {
            // Explicit directives also override the default "!!" prefix.
            own_tag_component(Cow::Borrowed(prefix.as_ref()))
        } else if original_handle == "!!" {
            Cow::Borrowed(YAML_CORE_SCHEMA_PREFIX)
        } else {
            // An undeclared named handle cannot be treated as a local tag.
            if original_handle.len() >= 2
                && original_handle.starts_with('!')
                && original_handle.ends_with('!')
            {
                return Err(ScanError::from_kind(
                    span.start,
                    ErrorKind::UndeclaredTagHandle,
                ));
            }
            original_handle.clone()
        };
        Ok(Cow::Owned(Tag {
            handle,
            suffix,
            original_handle,
        }))
    }
}

impl<'input, T: BorrowedInput<'input>> ParserTrait<'input> for Parser<'input, T> {
    fn peek(&mut self) -> Option<Result<&(Event<'input>, Span), ScanError>> {
        if let Some(ref x) = self.current {
            Some(Ok(x))
        } else if let Some(error) = &self.current_error {
            Some(Err(error.clone()))
        } else {
            if self.stream_end_emitted {
                return None;
            }
            match self.next_event_impl() {
                Ok(token) => self.current = Some(token),
                Err(error) => {
                    self.current_error = Some(error.clone());
                    return Some(Err(error));
                }
            }
            self.current.as_ref().map(Ok)
        }
    }

    fn next_event(&mut self) -> Option<ParseResult<'input>> {
        if let Some(error) = self.current_error.take() {
            self.stream_end_emitted = true;
            return Some(Err(error));
        }

        if self.stream_end_emitted {
            return None;
        }

        let tok = self.next_event_impl();
        if matches!(tok, Ok((Event::StreamEnd, _)) | Err(_)) {
            self.stream_end_emitted = true;
        }
        Some(tok)
    }

    fn load<R: SpannedEventReceiver<'input>>(
        &mut self,
        recv: &mut R,
        multi: bool,
    ) -> Result<(), ScanError> {
        let mut recv = InfallibleSpannedReceiver(recv);
        into_scan_result(ParserTrait::try_load(self, &mut recv, multi))
    }

    fn try_load<R: TrySpannedEventReceiver<'input>>(
        &mut self,
        recv: &mut R,
        multi: bool,
    ) -> Result<(), TryLoadError<R::Error>> {
        let stream_start_buffered = matches!(self.current.as_ref(), Some((Event::StreamStart, _)));
        if !self.scanner.stream_started() || stream_start_buffered {
            let (ev, span) = self.next_event_for_load()?;
            if ev != Event::StreamStart {
                self.stream_end_emitted = true;
                return Err(TryLoadError::scan(ScanError::from_kind(
                    span.start,
                    ErrorKind::ExpectedStreamStart,
                )));
            }
            try_emit(recv, ev, span)?;
        }

        let has_buffered_result = self.current.is_some() || self.current_error.is_some();
        #[cfg(feature = "comments")]
        let has_buffered_result =
            has_buffered_result || self.deferred_error.is_some() || !self.queued_events.is_empty();
        if self.state == State::End && !has_buffered_result {
            // The parser already completed the stream, so emit the terminal event again and stop.
            // Only success reaches `State::End`. The scanner's own stream-end flag is not a
            // substitute: it is also set when an error is raised at the end of the stream, such as
            // `ExpectedDocumentStart` for a directive-only document, and `StreamEnd` must not be
            // re-emitted after such an error.
            try_emit(recv, Event::StreamEnd, Span::empty(self.scanner.mark()))?;
            self.stream_end_emitted = true;
            return Ok(());
        }
        if self.stream_end_emitted && self.current_error.is_none() {
            // Only a scan error reaches this point with the latch set: a clean end of stream was
            // handled above. The error may have interrupted a state transition, so the state
            // machine must not run again. Mirror the fused iterator, which returns `None` here.
            return Ok(());
        }

        loop {
            let (ev, span) = if let Some(error) = self.current_error.take() {
                self.stream_end_emitted = true;
                return Err(TryLoadError::scan(error));
            } else {
                self.next_event_for_load()?
            };
            let is_doc_end = matches!(ev, Event::DocumentEnd);
            let is_stream_end = matches!(ev, Event::StreamEnd);

            try_emit(recv, ev, span)?;

            if is_stream_end {
                self.stream_end_emitted = true;
                return Ok(());
            }
            if !multi && is_doc_end {
                return Ok(());
            }
        }
    }
}

impl<'input, T: BorrowedInput<'input>> Iterator for Parser<'input, T> {
    type Item = Result<(Event<'input>, Span), ScanError>;

    fn next(&mut self) -> Option<Self::Item> {
        self.next_event()
    }
}

impl<'input, T: BorrowedInput<'input>> core::iter::FusedIterator for Parser<'input, T> {}

#[cfg(test)]
mod test {
    #[cfg(feature = "error_messages")]
    use alloc::string::String;
    use alloc::{borrow::Cow, format, string::ToString, vec, vec::Vec};
    #[cfg(feature = "error_messages")]
    use core::{error::Error as _, fmt};

    #[cfg(feature = "error_messages")]
    use crate::error::{ErrorKind, ScanError};
    use crate::scanner::{Marker, ScalarStyle, Span};

    use super::{
        Event, EventReceiver, Parser, State, StructureStyle, Tag, TryEventReceiver, TryLoadError,
        TrySpannedEventReceiver, YamlVersion,
    };

    #[derive(Default)]
    struct CollectingSink<'input> {
        events: Vec<Event<'input>>,
    }

    impl<'input> EventReceiver<'input> for CollectingSink<'input> {
        fn on_event(&mut self, ev: Event<'input>) {
            self.events.push(ev);
        }
    }

    #[cfg(feature = "error_messages")]
    fn first_error_info(input: &str) -> String {
        for event in Parser::new_from_str(input) {
            if let Err(err) = event {
                return err.info();
            }
        }
        panic!("expected parser error")
    }

    fn first_tagged_scalar_tag(input: &str) -> Tag {
        Parser::new_from_str(input)
            .find_map(|event| match event.expect("input should parse").0 {
                Event::Scalar(_, _, _, Some(tag)) => Some(tag.into_owned()),
                _ => None,
            })
            .expect("expected tagged scalar")
    }

    #[cfg(feature = "comments")]
    #[test]
    fn deferred_parse_node_can_emit_comment_before_flow_node() {
        let mut parser = Parser::new_from_str("---\n# deferred\nvalue\n");
        assert_eq!(parser.stream_start().unwrap().0, Event::StreamStart);
        assert_eq!(
            parser.document_start(true).unwrap().0,
            Event::DocumentStart(true, None)
        );

        let (event, _) = parser
            .defer_parse_node(State::FlowNode, State::FlowMappingKey, false, false)
            .unwrap();

        assert!(matches!(event, Event::Comment(text, _) if text == " deferred"));
        assert_eq!(parser.state, State::FlowNode);
    }

    #[cfg(feature = "comments")]
    #[test]
    fn queued_node_event_gets_pending_key_indent() {
        let mut parser = Parser::new_from_str("");
        let span = Span::empty(Marker::new(0, 1, 0));

        parser.pending_key_indent = Some(3);
        parser
            .queued_events
            .push_back((Event::SequenceStart(StructureStyle::Block, 0, None), span));

        let (event, span) = parser.next_event_impl().unwrap();

        assert!(matches!(
            event,
            Event::SequenceStart(StructureStyle::Block, 0, None)
        ));
        assert_eq!(span.indent, Some(3));
        assert_eq!(parser.pending_key_indent, None);
    }

    #[test]
    fn state_machine_handles_deferred_flow_node_states() {
        let mut parser = Parser::new_from_str("value\n");
        assert_eq!(parser.stream_start().unwrap().0, Event::StreamStart);
        assert_eq!(
            parser.document_start(true).unwrap().0,
            Event::DocumentStart(false, None)
        );
        parser.state = State::FlowNode;
        parser.push_state(State::End);

        let (event, _) = parser.state_machine().unwrap();

        assert!(matches!(event, Event::Scalar(value, ..) if value == "value"));
    }

    #[cfg(feature = "comments")]
    #[test]
    fn state_machine_handles_deferred_flow_mapping_value_node() {
        let mut parser = Parser::new_from_str("value\n");
        assert_eq!(parser.stream_start().unwrap().0, Event::StreamStart);
        assert_eq!(
            parser.document_start(true).unwrap().0,
            Event::DocumentStart(false, None)
        );
        parser.state = State::FlowSequenceEntryMappingValueNode;

        let (event, _) = parser.state_machine().unwrap();

        assert!(matches!(event, Event::Scalar(value, ..) if value == "value"));
    }

    #[test]
    fn display_resolved_core_tag_without_extra_bang() {
        let tag = Tag::with_original_handle("tag:yaml.org,2002:", "str", "!!");

        assert_eq!(tag.to_string(), "tag:yaml.org,2002:str");
    }

    #[test]
    fn tag_helpers_distinguish_core_and_local_tags() {
        let core = Tag::with_original_handle("tag:yaml.org,2002:", "int", "!!");
        let local = Tag::new("!", "thing");
        let non_specific = Tag::with_original_handle("", "!", "");
        let verbatim = Tag::with_original_handle("", "tag:example.com,2000:thing", "");
        let unknown_yaml_org = Tag::with_original_handle("", "tag:yaml.org,2002:application", "");

        assert_eq!(core.core_suffix(), Some("int"));
        assert!(core.is_yaml_core_schema());
        assert!(core.is_yaml_core_schema_tag("int"));
        assert!(!core.is_yaml_core_schema_tag("str"));
        assert!(!core.is_custom());
        assert_eq!(core.parts(), ("tag:yaml.org,2002:", "int"));
        assert_eq!(core.original_parts(), ("!!", "int"));
        assert_eq!(core.original(), "!!int");

        assert_eq!(local.core_suffix(), None);
        assert!(!local.is_yaml_core_schema());
        assert!(!local.is_yaml_core_schema_tag("thing"));
        assert!(local.is_custom());
        assert_eq!(local.parts(), ("!", "thing"));
        assert_eq!(local.original_parts(), ("!", "thing"));
        assert_eq!(local.original(), "!thing");
        assert_eq!(local.to_string(), "!thing");

        assert_eq!(non_specific.parts(), ("", "!"));
        assert_eq!(non_specific.original_parts(), ("", "!"));
        assert_eq!(non_specific.original(), "!");

        assert_eq!(verbatim.parts(), ("", "tag:example.com,2000:thing"));
        assert_eq!(
            verbatim.original_parts(),
            ("", "tag:example.com,2000:thing")
        );
        assert_eq!(verbatim.original(), "!<tag:example.com,2000:thing>");

        assert_eq!(unknown_yaml_org.core_suffix(), None);
        assert!(!unknown_yaml_org.is_yaml_core_schema());
        assert!(unknown_yaml_org.is_custom());
    }

    #[test]
    fn core_suffix_uses_resolved_tag_uri_for_common_spellings() {
        let cases = [
            ("shorthand", "v: !!int 1\n", ("tag:yaml.org,2002:", "int")),
            (
                "verbatim",
                "v: !<tag:yaml.org,2002:int> 1\n",
                ("", "tag:yaml.org,2002:int"),
            ),
            (
                "full prefix",
                "%TAG !e! tag:yaml.org,2002:\n---\nv: !e!int 1\n",
                ("tag:yaml.org,2002:", "int"),
            ),
            (
                "mid-split",
                "%TAG !m! tag:yaml.org,2002:i\n---\nv: !m!nt 1\n",
                ("tag:yaml.org,2002:i", "nt"),
            ),
        ];

        for (label, input, expected_parts) in cases {
            let tag = first_tagged_scalar_tag(input);

            assert_eq!(tag.parts(), expected_parts, "{label}");
            assert_eq!(tag.core_suffix(), Some("int"), "{label}");
            assert!(tag.is_yaml_core_schema(), "{label}");
            assert!(tag.is_yaml_core_schema_tag("int"), "{label}");
            assert!(!tag.is_yaml_core_schema_tag("str"), "{label}");
            assert!(!tag.is_custom(), "{label}");
        }
    }

    #[test]
    fn core_suffix_rejects_non_core_yaml_org_tags() {
        let cases = [
            "binary",
            "merge",
            "omap",
            "pairs",
            "set",
            "timestamp",
            "value",
            "yaml",
        ];

        for suffix in cases {
            let tag = Tag::with_original_handle("tag:yaml.org,2002:", suffix, "!!");

            assert_eq!(tag.core_suffix(), None, "{suffix}");
            assert!(!tag.is_yaml_core_schema(), "{suffix}");
            assert!(tag.is_custom(), "{suffix}");
        }
    }

    #[test]
    fn core_suffix_rejects_non_core_tags() {
        let cases = [
            ("local", "v: !local 1\n"),
            ("verbatim custom", "v: !<tag:example.com,2000:int> 1\n"),
            (
                "custom directive",
                "%TAG !e! tag:example.com,2000:\n---\nv: !e!int 1\n",
            ),
            (
                "overridden secondary handle",
                "%TAG !! tag:example.com,2000:app/\n---\nv: !!int 1\n",
            ),
        ];

        for (label, input) in cases {
            let tag = first_tagged_scalar_tag(input);

            assert_eq!(tag.core_suffix(), None, "{label}");
            assert!(!tag.is_yaml_core_schema(), "{label}");
            assert!(!tag.is_yaml_core_schema_tag("int"), "{label}");
            assert!(tag.is_custom(), "{label}");
        }
    }

    #[test]
    fn suffix_in_namespace_resolves_across_spellings() {
        const NS: &str = "tag:yaml.org,2002:";

        // Every spelling of `tag:yaml.org,2002:omap` resolves to the same name, even though
        // `omap` is not a Core Schema type (so `core_suffix` reports `None`). `mid_split` cuts
        // the URI after the namespace prefix (handle longer than `NS`); `inside_split` cuts it
        // before the prefix ends (handle a non-empty prefix of `NS`), exercising both branches.
        let shorthand = Tag::with_original_handle(NS, "omap", "!!");
        let verbatim = Tag::with_original_handle("", "tag:yaml.org,2002:omap", "");
        let mid_split = Tag::with_original_handle("tag:yaml.org,2002:o", "map", "!o!");
        let inside_split = Tag::with_original_handle("tag:yaml.org,", "2002:omap", "!y!");
        for tag in [&shorthand, &verbatim, &mid_split, &inside_split] {
            assert_eq!(tag.suffix_in_namespace(NS).as_deref(), Some("omap"));
            assert_eq!(tag.core_suffix(), None);
        }

        // Borrow whenever the resolved name is a contiguous slice of `handle` or `suffix`;
        // allocate only when a split lands inside the name itself (handle extends past `NS`).
        assert!(matches!(
            shorthand.suffix_in_namespace(NS),
            Some(Cow::Borrowed(_))
        ));
        assert!(matches!(
            verbatim.suffix_in_namespace(NS),
            Some(Cow::Borrowed(_))
        ));
        assert!(matches!(
            inside_split.suffix_in_namespace(NS),
            Some(Cow::Borrowed(_))
        ));
        assert!(matches!(
            mid_split.suffix_in_namespace(NS),
            Some(Cow::Owned(_))
        ));

        // The non-core `merge` type resolves the same way; core types still flow through
        // `core_suffix`.
        let merge = Tag::with_original_handle(NS, "merge", "!!");
        assert_eq!(merge.suffix_in_namespace(NS).as_deref(), Some("merge"));
        assert_eq!(merge.core_suffix(), None);
        assert_eq!(
            Tag::new(NS, "int").suffix_in_namespace(NS).as_deref(),
            Some("int")
        );

        // Tags outside the namespace do not resolve into it.
        assert_eq!(Tag::new("!", "omap").suffix_in_namespace(NS), None);
        assert_eq!(
            Tag::with_original_handle("", "tag:example.com,2000:omap", "").suffix_in_namespace(NS),
            None
        );
    }

    #[test]
    fn attach_tag_span_preserves_node_span() {
        let event = Event::Scalar("value".into(), ScalarStyle::Plain, 0, None);
        let span = Span::new(Marker::new(6, 1, 6), Marker::new(11, 1, 11));
        let tag_start = Marker::new(0, 1, 0);

        let (attached_event, attached_span) =
            Parser::<crate::input::str::StrInput<'_>>::attach_tag_span(
                event.clone(),
                span,
                Some((tag_start, 4)),
            );

        assert_eq!(attached_event, event);
        assert_eq!(attached_span.start, span.start);
        assert_eq!(attached_span.end, span.end);
        assert_eq!(attached_span.tag_start(), Some(tag_start));
        assert_eq!(
            attached_span.tag_span(),
            Some(Span::new(tag_start, Marker::new(4, 1, 4)))
        );
    }

    #[test]
    fn event_inspection_helpers_report_node_metadata() {
        let tag = Tag::new("!", "thing");
        let scalar = Event::Scalar(
            "value".into(),
            ScalarStyle::DoubleQuoted,
            7,
            Some(Cow::Borrowed(&tag)),
        );
        let sequence =
            Event::SequenceStart(StructureStyle::Block, 8, Some(Cow::Owned(tag.clone())));
        let mapping = Event::MappingStart(StructureStyle::Block, 9, Some(Cow::Borrowed(&tag)));

        assert_eq!(scalar.anchor_id(), Some(7));
        assert_eq!(scalar.alias_id(), None);
        assert_eq!(scalar.tag(), Some(&tag));
        assert_eq!(scalar.scalar(), Some(("value", ScalarStyle::DoubleQuoted)));
        assert!(scalar.is_node());

        assert_eq!(sequence.anchor_id(), Some(8));
        assert_eq!(sequence.alias_id(), None);
        assert_eq!(sequence.tag(), Some(&tag));
        assert_eq!(sequence.scalar(), None);
        assert!(sequence.is_node());

        assert_eq!(mapping.anchor_id(), Some(9));
        assert_eq!(mapping.alias_id(), None);
        assert_eq!(mapping.tag(), Some(&tag));
        assert_eq!(mapping.scalar(), None);
        assert!(mapping.is_node());

        let alias = Event::Alias(10);
        assert_eq!(alias.anchor_id(), None);
        assert_eq!(alias.alias_id(), Some(10));
        assert_eq!(alias.tag(), None);
        assert_eq!(alias.scalar(), None);
        assert!(alias.is_node());

        let unanchored_scalar = Event::Scalar("x".into(), ScalarStyle::Plain, 0, None);
        assert_eq!(unanchored_scalar.anchor_id(), None);
        assert_eq!(unanchored_scalar.alias_id(), None);

        let stream_start = Event::StreamStart;
        assert_eq!(stream_start.anchor_id(), None);
        assert_eq!(stream_start.alias_id(), None);
        assert_eq!(stream_start.tag(), None);
        assert_eq!(stream_start.scalar(), None);
        assert!(!stream_start.is_node());
    }

    #[test]
    fn test_peek_eq_parse() {
        let s = "
a0 bb: val
a1: &x
    b1: 4
    b2: d
a2: 4
a3: [1, 2, 3]
a4:
    - [a1, a2]
    - 2
a5: *x
";
        let mut p = Parser::new_from_str(s);
        loop {
            let event_peek = p.peek().unwrap().unwrap().clone();
            let event = p.next_event().unwrap().unwrap();
            assert_eq!(event, event_peek);
            if event.0 == Event::StreamEnd {
                break;
            }
        }
    }

    #[test]
    fn test_repeated_peek_returns_buffered_event() {
        let mut parser = Parser::new_from_str("key: value\n");

        let first_peek = parser.peek().unwrap().unwrap().clone();
        let second_peek = parser.peek().unwrap().unwrap().clone();
        let next = parser.next_event().unwrap().unwrap();

        assert_eq!(first_peek, second_peek);
        assert_eq!(first_peek, next);
    }

    #[cfg(feature = "error_messages")]
    #[test]
    fn test_peek_surfaces_scan_error_without_consuming_stream_end_state() {
        let mut parser = Parser::new_from_str("a: [1, 2");

        loop {
            match parser.peek() {
                Some(Ok(_)) => {
                    parser.next_event().unwrap().unwrap();
                }
                Some(Err(error)) => {
                    assert_eq!(error.info(), "unclosed bracket '['");
                    break;
                }
                None => panic!("expected parse error"),
            }
        }
    }

    #[test]
    fn test_iterator_terminates_after_scan_error() {
        let parser = Parser::new_from_str("foo:\n  bar\ninvalid\n");
        let mut errors = 0usize;
        let mut events = 0usize;

        for item in parser {
            events += 1;
            if item.is_err() {
                errors += 1;
            }
            assert!(
                events < 1000,
                "parser iterator did not terminate after a scan error"
            );
        }

        assert_eq!(errors, 1);
    }

    #[cfg(feature = "error_messages")]
    #[test]
    fn test_iterator_terminates_after_node_property_error() {
        let parser = Parser::new_from_str("- *nope\n- 2\n");
        let mut errors = 0usize;
        let mut saw_later_node = false;
        let mut events = 0usize;

        for item in parser {
            events += 1;
            match item {
                Ok((Event::Scalar(value, ..), _)) if value == "2" => saw_later_node = true,
                Ok(_) => {}
                Err(error) => {
                    assert_eq!(error.info(), "while parsing node, found unknown anchor");
                    errors += 1;
                }
            }
            assert!(
                events < 1000,
                "parser iterator did not terminate after a node-property error"
            );
        }

        assert_eq!(errors, 1);
        assert!(!saw_later_node, "parser resumed after the alias error");
    }

    #[test]
    fn test_peeked_scan_error_is_returned_once_by_next_event() {
        let mut parser = Parser::new_from_str("a: [1, 2");

        let first_error = loop {
            match parser.peek() {
                Some(Ok(_)) => {
                    parser.next_event().unwrap().unwrap();
                }
                Some(Err(error)) => break error,
                None => panic!("expected parse error"),
            }
        };
        let Some(Err(second_error)) = parser.peek() else {
            panic!("expected cached parse error");
        };

        assert_eq!(first_error, second_error);
        assert_eq!(parser.next_event().unwrap().unwrap_err(), first_error);
        assert!(parser.next_event().is_none());
        assert!(parser.peek().is_none());
    }

    #[cfg(feature = "error_messages")]
    #[test]
    fn test_peeked_node_property_error_is_stable_and_terminal() {
        let mut parser = Parser::new_from_str("a: *nope\nb: 2\n");

        for _ in 0..4 {
            parser.next_event().unwrap().unwrap();
        }

        let Some(Err(first_error)) = parser.peek() else {
            panic!("expected unknown alias error");
        };
        let Some(Err(second_error)) = parser.peek() else {
            panic!("expected cached unknown alias error");
        };

        assert_eq!(first_error, second_error);
        assert_eq!(
            first_error.info(),
            "while parsing node, found unknown anchor"
        );
        assert_eq!(parser.next_event().unwrap().unwrap_err(), first_error);
        assert!(parser.next_event().is_none());
        assert!(parser.peek().is_none());
    }

    #[test]
    fn test_peek_and_next_return_none_after_stream_end() {
        let mut parser = Parser::new_from_str("");

        assert!(matches!(
            parser.next_event().unwrap().unwrap().0,
            Event::StreamStart
        ));
        assert!(matches!(
            parser.next_event().unwrap().unwrap().0,
            Event::StreamEnd
        ));
        assert!(parser.next_event().is_none());
        assert!(parser.peek().is_none());
    }

    #[test]
    fn test_load_after_stream_already_ended_emits_stream_end() {
        let mut parser = Parser::new_from_str("");
        while parser.next_event().is_some() {}

        let mut sink = CollectingSink::default();
        parser.load(&mut sink, true).unwrap();

        assert_eq!(sink.events, vec![Event::StreamEnd]);
    }

    #[test]
    fn test_load_full_stream_fuses_iterator_after_stream_end() {
        let mut parser = Parser::new_from_str("a: 1\n");
        let mut sink = CollectingSink::default();

        parser.load(&mut sink, true).unwrap();

        assert!(matches!(sink.events.last(), Some(Event::StreamEnd)));
        assert!(parser.next_event().is_none());
        assert!(parser.peek().is_none());
    }

    #[test]
    fn test_load_after_peek_delivers_buffered_document_end_before_stream_end() {
        let mut parser = Parser::new_from_str("a");
        for _ in 0..3 {
            parser.next_event().unwrap().unwrap();
        }

        assert_eq!(parser.peek().unwrap().unwrap().0, Event::DocumentEnd);

        let mut sink = CollectingSink::default();
        parser.load(&mut sink, true).unwrap();

        assert_eq!(sink.events, vec![Event::DocumentEnd, Event::StreamEnd]);
        assert!(parser.next_event().is_none());
    }

    #[test]
    fn test_load_visits_nested_collection_events() {
        let mut parser = Parser::new_from_str("root:\n  - item: value\n  - [a, b]\n");
        let mut sink = CollectingSink::default();

        parser.load(&mut sink, true).unwrap();

        assert_eq!(
            sink.events,
            vec![
                Event::StreamStart,
                Event::DocumentStart(false, None),
                Event::MappingStart(StructureStyle::Block, 0, None),
                Event::Scalar("root".into(), ScalarStyle::Plain, 0, None),
                Event::SequenceStart(StructureStyle::Block, 0, None),
                Event::MappingStart(StructureStyle::Block, 0, None),
                Event::Scalar("item".into(), ScalarStyle::Plain, 0, None),
                Event::Scalar("value".into(), ScalarStyle::Plain, 0, None),
                Event::MappingEnd,
                Event::SequenceStart(StructureStyle::Flow, 0, None),
                Event::Scalar("a".into(), ScalarStyle::Plain, 0, None),
                Event::Scalar("b".into(), ScalarStyle::Plain, 0, None),
                Event::SequenceEnd,
                Event::SequenceEnd,
                Event::MappingEnd,
                Event::DocumentEnd,
                Event::StreamEnd,
            ]
        );
    }

    #[derive(Clone, Debug, PartialEq, Eq)]
    enum ValidationError {
        ForbiddenValue,
    }

    #[cfg(feature = "error_messages")]
    #[derive(Debug)]
    struct ReceiverFailure;

    #[cfg(feature = "error_messages")]
    impl fmt::Display for ReceiverFailure {
        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
            write!(f, "receiver failed")
        }
    }

    #[cfg(feature = "error_messages")]
    impl core::error::Error for ReceiverFailure {}

    struct FailingSink<'input> {
        events: Vec<Event<'input>>,
    }

    impl<'input> TryEventReceiver<'input> for FailingSink<'input> {
        type Error = ValidationError;

        fn on_event(&mut self, ev: Event<'input>) -> Result<(), Self::Error> {
            let should_fail = matches!(&ev, Event::Scalar(value, ..) if value.as_ref() == "bad");
            self.events.push(ev);
            if should_fail {
                Err(ValidationError::ForbiddenValue)
            } else {
                Ok(())
            }
        }
    }

    #[test]
    fn test_try_load_stops_on_receiver_error() {
        let mut parser = Parser::new_from_str("ok: bad\nafter: value\n");
        let mut sink = FailingSink { events: Vec::new() };

        let err = parser.try_load(&mut sink, true).unwrap_err();

        assert_eq!(err, TryLoadError::Receiver(ValidationError::ForbiddenValue));
        assert!(sink
            .events
            .iter()
            .any(|event| matches!(event, Event::Scalar(value, ..) if value == "ok")));
        assert!(sink
            .events
            .iter()
            .any(|event| matches!(event, Event::Scalar(value, ..) if value == "bad")));
        assert!(!sink
            .events
            .iter()
            .any(|event| matches!(event, Event::Scalar(value, ..) if value == "after")));
    }

    struct SpannedFailingSink {
        failed_span: Option<Span>,
    }

    impl<'input> TrySpannedEventReceiver<'input> for SpannedFailingSink {
        type Error = Span;

        fn on_event(&mut self, ev: Event<'input>, span: Span) -> Result<(), Self::Error> {
            if matches!(ev, Event::Scalar(value, ..) if value.as_ref() == "bad") {
                self.failed_span = Some(span);
                Err(span)
            } else {
                Ok(())
            }
        }
    }

    #[test]
    fn test_try_load_spanned_receiver_gets_span() {
        let mut parser = Parser::new_from_str("value: bad\n");
        let mut sink = SpannedFailingSink { failed_span: None };

        let err = parser.try_load(&mut sink, false).unwrap_err();

        let TryLoadError::Receiver(span) = err else {
            panic!("expected receiver error");
        };

        assert_eq!(Some(span), sink.failed_span);
        assert!(!span.is_empty());
    }

    #[cfg(feature = "error_messages")]
    struct NeverFails {
        count: usize,
    }

    #[cfg(feature = "error_messages")]
    impl<'input> TryEventReceiver<'input> for NeverFails {
        type Error = ValidationError;

        fn on_event(&mut self, _ev: Event<'input>) -> Result<(), Self::Error> {
            self.count += 1;
            Ok(())
        }
    }

    #[cfg(feature = "error_messages")]
    #[test]
    fn test_try_load_returns_scan_error() {
        let mut parser = Parser::new_from_str("%YAML 1.2\n%YAML 1.2\n---\n");
        let mut sink = NeverFails { count: 0 };

        let err = parser.try_load(&mut sink, true).unwrap_err();

        let TryLoadError::Scan(err) = err else {
            panic!("expected scan error");
        };
        assert_eq!(err.kind(), &ErrorKind::DuplicateVersionDirective);
        assert_eq!(err.info(), "duplicate version directive");
    }

    #[cfg(feature = "error_messages")]
    #[test]
    fn test_try_load_error_display_and_source_cover_both_variants() {
        let scan = ScanError::from_kind(Marker::new(3, 1, 3), ErrorKind::UnexpectedEof);
        let scan_err: TryLoadError<ReceiverFailure> = scan.into();

        assert!(scan_err
            .to_string()
            .starts_with("parser error: unexpected eof"));
        assert!(scan_err.source().is_some());

        let receiver_err = TryLoadError::Receiver(ReceiverFailure);

        assert_eq!(receiver_err.to_string(), "receiver error: receiver failed");
        assert!(receiver_err.source().is_some());
    }

    #[cfg(feature = "error_messages")]
    #[test]
    fn test_try_load_requires_buffered_stream_start() {
        let mut parser = Parser::new_from_str("");
        let span = Span::empty(Marker::new(0, 1, 0));
        parser.current = Some((
            Event::Scalar("value".into(), ScalarStyle::Plain, 0, None),
            span,
        ));
        let mut sink = NeverFails { count: 0 };

        let err = parser.try_load(&mut sink, true).unwrap_err();

        let TryLoadError::Scan(err) = err else {
            panic!("expected scan error");
        };
        assert_eq!(err.info(), "did not find expected <stream-start>");
    }

    #[test]
    fn test_try_load_after_stream_already_ended_emits_stream_end() {
        let mut parser = Parser::new_from_str("");
        while parser.next_event().is_some() {}

        let mut sink = FailingSink { events: Vec::new() };
        parser.try_load(&mut sink, true).unwrap();

        assert_eq!(sink.events, vec![Event::StreamEnd]);
    }

    #[test]
    fn test_try_load_full_stream_fuses_iterator_after_stream_end() {
        let mut parser = Parser::new_from_str("a: 1\n");
        let mut sink = FailingSink { events: Vec::new() };

        parser.try_load(&mut sink, true).unwrap();

        assert!(matches!(sink.events.last(), Some(Event::StreamEnd)));
        assert!(parser.next_event().is_none());
        assert!(parser.peek().is_none());
    }

    #[test]
    fn test_try_load_after_peek_delivers_buffered_document_end_before_stream_end() {
        let mut parser = Parser::new_from_str("a");
        for _ in 0..3 {
            parser.next_event().unwrap().unwrap();
        }

        assert_eq!(parser.peek().unwrap().unwrap().0, Event::DocumentEnd);

        let mut sink = FailingSink { events: Vec::new() };
        parser.try_load(&mut sink, true).unwrap();

        assert_eq!(sink.events, vec![Event::DocumentEnd, Event::StreamEnd]);
        assert!(parser.next_event().is_none());
    }

    #[test]
    fn test_load_single_document_stops_before_next_document() {
        let mut parser = Parser::new_from_str("a: 1\n---\nb: 2\n");
        let mut sink = CollectingSink::default();

        parser.load(&mut sink, false).unwrap();

        assert!(sink
            .events
            .iter()
            .any(|event| matches!(event, Event::Scalar(value, ..) if value == "a")));
        assert!(!sink
            .events
            .iter()
            .any(|event| matches!(event, Event::Scalar(value, ..) if value == "b")));
        assert!(matches!(sink.events.last(), Some(Event::DocumentEnd)));
    }

    #[cfg(feature = "error_messages")]
    #[test]
    fn test_duplicate_version_directive_errors() {
        assert_eq!(
            first_error_info("%YAML 1.2\n%YAML 1.2\n---\n"),
            "duplicate version directive"
        );
    }

    #[cfg(feature = "error_messages")]
    #[test]
    fn test_unsupported_yaml_major_version_errors() {
        assert_eq!(
            first_error_info("%YAML 9.9\n--- a\n"),
            "unsupported YAML major version"
        );
    }

    #[test]
    fn test_document_start_emits_yaml_version() {
        let events = Parser::new_from_str("%YAML 1.2\n---\nvalue\n")
            .map(|event| event.unwrap().0)
            .collect::<Vec<_>>();

        assert!(matches!(
            events.get(1),
            Some(Event::DocumentStart(
                true,
                Some(YamlVersion { major: 1, minor: 2 })
            ))
        ));
    }

    #[test]
    fn test_document_start_allows_supported_major_future_minor_version() {
        let events = Parser::new_from_str("%YAML 1.9\n---\nvalue\n")
            .map(|event| event.unwrap().0)
            .collect::<Vec<_>>();

        assert!(matches!(
            events.get(1),
            Some(Event::DocumentStart(
                true,
                Some(YamlVersion { major: 1, minor: 9 })
            ))
        ));
    }

    #[test]
    fn test_document_start_keeps_version_and_tags_across_comment() {
        let events = Parser::new_from_str(
            "%YAML 1.2\n# directive comment\n%TAG !e! tag:example.com,2026:\n---\nkey: !e!thing value\n",
        )
        .map(|event| event.unwrap().0)
        .filter(|event| {
            #[cfg(feature = "comments")]
            {
                !matches!(event, Event::Comment(..))
            }
            #[cfg(not(feature = "comments"))]
            {
                let _ = event;
                true
            }
        })
        .collect::<Vec<_>>();

        assert!(matches!(
            events.get(1),
            Some(Event::DocumentStart(
                true,
                Some(YamlVersion { major: 1, minor: 2 })
            ))
        ));

        let tag = events
            .iter()
            .find_map(|event| match event {
                Event::Scalar(value, _, _, Some(tag)) if value == "value" => Some(tag),
                _ => None,
            })
            .expect("expected tagged scalar after comment-separated directives");

        assert_eq!(tag.handle, "tag:example.com,2026:");
        assert_eq!(tag.suffix, "thing");
    }

    #[cfg(feature = "comments")]
    #[test]
    fn tag_directive_state_borrows_str_input_across_comment() {
        let mut parser = Parser::new_from_str(
            "%TAG !e! tag:example.com,2026:\n# directive comment\n---\nkey: value\n",
        );

        while let Some(event) = parser.next_event() {
            if matches!(event.unwrap().0, Event::Comment(..)) {
                break;
            }
        }

        assert!(matches!(
            parser.tags.get("!e!"),
            Some(Cow::Borrowed("tag:example.com,2026:"))
        ));
        assert!(parser
            .pending_document_tag_handles
            .iter()
            .any(|handle| matches!(handle, Cow::Borrowed("!e!"))));
    }

    #[test]
    fn test_each_document_can_declare_own_yaml_version() {
        let document_starts = Parser::new_from_str(
            "%YAML 1.2\n---\na\n...\n%YAML 1.2\n---\nb\n...\n%YAML 1.1\n---\nc\n",
        )
        .filter_map(|event| match event.unwrap().0 {
            Event::DocumentStart(explicit, version) => Some((explicit, version)),
            _ => None,
        })
        .collect::<Vec<_>>();

        assert_eq!(
            document_starts,
            vec![
                (true, Some(YamlVersion::new(1, 2))),
                (true, Some(YamlVersion::new(1, 2))),
                (true, Some(YamlVersion::new(1, 1))),
            ]
        );
    }

    #[cfg(feature = "error_messages")]
    #[test]
    fn test_duplicate_tag_directive_errors() {
        assert_eq!(
            first_error_info("%TAG !t! tag:test,2024:\n%TAG !t! tag:other,2024:\n---\n"),
            "the TAG directive must only be given at most once per handle in the same document"
        );
    }

    #[cfg(feature = "error_messages")]
    #[test]
    fn duplicate_tag_directive_across_comment_is_rejected() {
        let input = concat!(
            "%TAG !e! tag:example.com,2000:one/\n",
            "# separator\n",
            "%TAG !e! tag:example.com,2000:two/\n",
            "---\n",
        );

        assert_eq!(
            first_error_info(input),
            "the TAG directive must only be given at most once per handle in the same document"
        );
    }

    #[test]
    fn test_keep_tags_inherited_handle_can_be_redeclared_in_next_document() {
        let input = concat!(
            "%TAG !e! tag:example.com,2000:one/\n",
            "---\n",
            "first: !e!thing value\n",
            "...\n",
            "%TAG !e! tag:example.com,2000:two/\n",
            "---\n",
            "second: !e!thing value\n",
        );

        let tags = Parser::new_from_str(input)
            .keep_tags(true)
            .filter_map(|event| match event.expect("input should parse").0 {
                Event::Scalar(value, _, _, Some(tag)) if value == "value" => {
                    Some(tag.handle.clone())
                }
                _ => None,
            })
            .collect::<Vec<_>>();

        assert_eq!(
            tags,
            vec!["tag:example.com,2000:one/", "tag:example.com,2000:two/"]
        );
    }

    #[cfg(feature = "error_messages")]
    #[test]
    fn test_directive_after_implicit_document_requires_explicit_end() {
        assert_eq!(
            first_error_info("---\nkey: value\n%YAML 1.2\n---\n"),
            "missing explicit document end marker before directive"
        );
    }

    #[cfg(feature = "error_messages")]
    #[test]
    fn test_anchor_offset_overflow_reports_error() {
        let mut parser = Parser::new_from_str("&a value");
        parser.set_anchor_offset(usize::MAX);

        let err = parser
            .find_map(Result::err)
            .expect("anchor registration should overflow");

        assert_eq!(
            err.info(),
            "while parsing anchor, anchor count exceeded supported limit"
        );
    }

    #[test]
    fn test_alias_resolves_to_registered_anchor_id() {
        let events = Parser::new_from_str("- &a value\n- *a\n")
            .map(|event| event.unwrap().0)
            .collect::<Vec<_>>();

        assert!(events.iter().any(|event| matches!(event, Event::Alias(1))));
    }

    #[test]
    fn test_anchor_then_tag_applies_both_to_scalar() {
        let events = Parser::new_from_str("&a !!str value")
            .map(|event| event.unwrap().0)
            .collect::<Vec<_>>();

        let Some(Event::Scalar(value, _, anchor_id, Some(tag))) = events
            .iter()
            .find(|event| matches!(event, Event::Scalar(value, ..) if value == "value"))
        else {
            panic!("expected tagged anchored scalar");
        };

        assert_eq!(value, "value");
        assert_eq!(*anchor_id, 1);
        assert_eq!(tag.handle, "tag:yaml.org,2002:");
        assert_eq!(tag.suffix, "str");
        assert_eq!(tag.original_handle, "!!");
        assert_eq!(tag.original(), "!!str");
    }

    #[test]
    fn test_tag_then_anchor_applies_both_to_scalar() {
        let events = Parser::new_from_str("!!str &a value")
            .map(|event| event.unwrap().0)
            .collect::<Vec<_>>();

        let Some(Event::Scalar(value, _, anchor_id, Some(tag))) = events
            .iter()
            .find(|event| matches!(event, Event::Scalar(value, ..) if value == "value"))
        else {
            panic!("expected tagged anchored scalar");
        };

        assert_eq!(value, "value");
        assert_eq!(*anchor_id, 1);
        assert_eq!(tag.handle, "tag:yaml.org,2002:");
        assert_eq!(tag.suffix, "str");
        assert_eq!(tag.original_handle, "!!");
        assert_eq!(tag.original(), "!!str");
    }

    #[test]
    fn test_tag_directive_preserves_original_handle() {
        let events =
            Parser::new_from_str("%TAG !e! tag:example.com,2000:\n---\nconfig: !e!keep value\n")
                .map(|event| event.unwrap().0)
                .collect::<Vec<_>>();

        let (value, tag) = events
            .iter()
            .find_map(|event| match event {
                Event::Scalar(value, _, _, Some(tag)) if value == "value" => Some((value, tag)),
                _ => None,
            })
            .expect("expected tagged scalar");

        assert_eq!(value, "value");
        assert_eq!(tag.handle, "tag:example.com,2000:");
        assert_eq!(tag.suffix, "keep");
        assert_eq!(tag.original_handle, "!e!");
        assert_eq!(tag.parts(), ("tag:example.com,2000:", "keep"));
        assert_eq!(tag.original_parts(), ("!e!", "keep"));
        assert_eq!(tag.original(), "!e!keep");
    }

    #[test]
    fn test_verbatim_tag_original_is_normalized_author_spelling() {
        let events = Parser::new_from_str("key: !<tag:example.com,2000:thing> value\n")
            .map(|event| event.unwrap().0)
            .collect::<Vec<_>>();

        let Some(Event::Scalar(value, _, _, Some(tag))) = events
            .iter()
            .find(|event| matches!(event, Event::Scalar(value, ..) if value == "value"))
        else {
            panic!("expected tagged scalar");
        };

        assert_eq!(value, "value");
        assert_eq!(tag.handle, "");
        assert_eq!(tag.suffix, "tag:example.com,2000:thing");
        assert_eq!(tag.original_handle, "");
        assert_eq!(tag.parts(), ("", "tag:example.com,2000:thing"));
        assert_eq!(tag.original_parts(), ("", "tag:example.com,2000:thing"));
        assert_eq!(tag.original(), "!<tag:example.com,2000:thing>");
    }

    #[test]
    fn test_multiple_tag_directives_are_kept_within_document() {
        let text = r"
%TAG !a! tag:a,2024:
%TAG !b! tag:b,2024:
---
first: !a!x foo
second: !b!y bar
";

        let mut seen_a = false;
        let mut seen_b = false;
        for event in Parser::new_from_str(text) {
            let (event, _) = event.unwrap();
            if let Event::Scalar(_, _, _, Some(tag)) = event {
                if tag.handle == "tag:a,2024:" {
                    seen_a = true;
                } else if tag.handle == "tag:b,2024:" {
                    seen_b = true;
                }
            }
        }

        assert!(seen_a);
        assert!(seen_b);
    }

    #[cfg(feature = "error_messages")]
    #[test]
    fn test_tags_are_cleared_when_next_document_has_no_directives() {
        let text = r"
%TAG !t! tag:test,2024:
--- !t!1
foo
--- !t!2
bar
";

        let mut parser = Parser::new_from_str(text);
        for event in parser.by_ref() {
            let (event, _) = event.unwrap();
            if let Event::DocumentEnd = event {
                break;
            }
        }

        match parser.next().unwrap().unwrap().0 {
            Event::DocumentStart(true, None) => {}
            _ => panic!("expected explicit second document start"),
        }

        let err = parser.next().unwrap().unwrap_err();
        assert!(format!("{err}").contains("the handle wasn't declared"));
    }

    #[cfg(feature = "error_messages")]
    #[test]
    fn test_pull_parser_clears_anchors_between_documents() {
        let mut parser = Parser::new_from_str(
            "--- &a value
--- *a
",
        );

        for event in parser.by_ref() {
            let (event, _) = event.unwrap();
            if matches!(event, Event::DocumentEnd) {
                break;
            }
        }

        match parser.next().unwrap().unwrap().0 {
            Event::DocumentStart(true, None) => {}
            _ => panic!("expected explicit second document start"),
        }

        let err = parser.next().unwrap().unwrap_err();
        assert!(format!("{err}").contains("unknown anchor"));
    }

    #[test]
    fn test_keep_tags_across_multiple_documents() {
        let text = r#"
%YAML 1.1
%TAG !t! tag:test,2024:
--- !t!1 &1
foo: "bar"
--- !t!2 &2
baz: "qux"
"#;
        for x in Parser::new_from_str(text).keep_tags(true) {
            let x = x.unwrap();
            if let Event::MappingStart(_, _, tag) = x.0 {
                let tag = tag.unwrap();
                assert_eq!(tag.handle, "tag:test,2024:");
            }
        }

        for x in Parser::new_from_str(text).keep_tags(false) {
            if x.is_err() {
                // Test successful
                return;
            }
        }
        panic!("Test failed, did not encounter error")
    }

    #[test]
    fn test_flow_sequence_mapping_allows_empty_key() {
        let parser = Parser::new_from_str("[?: value]");
        for event in parser {
            event.expect("parser should accept flow sequence mappings with empty keys");
        }
    }

    #[test]
    fn test_keep_tags_does_not_persist_default_tag_handles() {
        let text = "%TAG !! tag:evil,2024:\n--- !!int 1\n--- !!int 2\n";

        let mut int_tags = Vec::new();
        for event in Parser::new_from_str(text).keep_tags(true) {
            let event = event.unwrap().0;
            if let Event::Scalar(_, _, _, Some(tag)) = event {
                if tag.suffix == "int" {
                    int_tags.push(tag.handle.clone());
                }
            }
        }

        assert_eq!(int_tags, vec!["tag:evil,2024:", "tag:yaml.org,2002:"]);
    }

    #[test]
    fn test_keep_tags_does_not_persist_primary_tag_handle() {
        let text = "%TAG ! tag:evil,2024:\n--- !int 1\n--- !int 2\n";

        let tags = Parser::new_from_str(text)
            .keep_tags(true)
            .filter_map(|event| match event.expect("input should parse").0 {
                Event::Scalar(_, _, _, Some(tag)) if tag.suffix == "int" => {
                    Some(tag.handle.clone())
                }
                _ => None,
            })
            .collect::<Vec<_>>();

        assert_eq!(tags, vec!["tag:evil,2024:", "!"]);
    }

    #[test]
    fn common_tag_storage_preserves_comparison_and_hashing() {
        let parsed = first_tagged_scalar_tag("!!str value");
        let constructed = Tag::with_original_handle("tag:yaml.org,2002:", "str", "!!");
        assert!(matches!(parsed.handle, Cow::Borrowed(_)));
        assert!(matches!(parsed.suffix, Cow::Borrowed(_)));
        assert!(matches!(parsed.original_handle, Cow::Borrowed(_)));
        assert_eq!(parsed, constructed);
        assert_eq!(parsed.cmp(&constructed), core::cmp::Ordering::Equal);
        #[cfg(feature = "std")]
        {
            use core::hash::{Hash, Hasher};
            use std::collections::hash_map::DefaultHasher;

            let hash = |tag: &Tag| {
                let mut hasher = DefaultHasher::new();
                tag.hash(&mut hasher);
                hasher.finish()
            };
            assert_eq!(hash(&parsed), hash(&constructed));
        }
    }

    #[test]
    fn test_resolve_tag_distinguishes_non_specific_and_primary_handle_tags() {
        let mut parser = Parser::new_from_str("");
        parser
            .tags
            .insert("!".into(), "tag:local.example,2024:".into());

        for (handle, suffix, expected_prefix, original) in [
            ("", "!", "", "!"),
            ("!", "foo", "tag:local.example,2024:", "!foo"),
        ] {
            let tag = parser
                .resolve_tag(
                    Span::empty(Marker::new(0, 1, 0)),
                    Cow::Borrowed(handle),
                    Cow::Borrowed(suffix),
                )
                .unwrap();

            assert_eq!(tag.parts(), (expected_prefix, suffix));
            assert_eq!(tag.original_parts(), (handle, suffix));
            assert_eq!(tag.original(), original);
            assert_eq!(tag.to_string(), format!("{expected_prefix}{suffix}"));
        }
    }

    #[test]
    fn test_load_after_peek_stream_start() {
        #[derive(Default)]
        struct Sink<'input> {
            events: Vec<Event<'input>>,
        }

        impl<'input> EventReceiver<'input> for Sink<'input> {
            fn on_event(&mut self, ev: Event<'input>) {
                self.events.push(ev);
            }
        }

        let mut parser = Parser::new_from_str("key: value\n");
        let mut sink = Sink::default();

        assert_eq!(parser.peek().unwrap().unwrap().0, Event::StreamStart);
        parser.load(&mut sink, false).unwrap();

        assert!(matches!(sink.events.first(), Some(Event::StreamStart)));
        assert!(matches!(sink.events.get(1), Some(Event::DocumentStart(..))));
    }
}