rlsp-yaml-parser 0.5.0

// SPDX-License-Identifier: MIT

use crate::error::Error;
use crate::event::{Event, ScalarStyle};
use crate::pos::{Pos, Span};
use std::borrow::Cow;

/// Outcome of one state-machine step inside [`crate::EventIter::next`].
#[expect(
    clippy::large_enum_variant,
    reason = "Yield carries Event<'input> which grows with each new span field; boxing would require widespread call-site changes for an internal type"
)]
pub enum StepResult<'input> {
    /// The step pushed to `queue` or changed state; loop again to drain.
    Continue,
    /// The step produced an event or error to return immediately.
    Yield(Result<(Event<'input>, Span), Error>),
}

/// State of the top-level event iterator.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum IterState {
    /// About to emit `StreamStart`.
    BeforeStream,
    /// Between documents: skip blanks/comments/directives, detect next document.
    BetweenDocs,
    /// Inside a document: consume lines until a boundary marker or EOF.
    InDocument,
    /// `StreamEnd` emitted or an error was yielded; iteration is finished.
    Done,
}

/// What the state machine expects next for an open mapping entry.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MappingPhase {
    /// The next node is a key (first half of a pair).
    Key,
    /// The next node is a value (second half of a pair).
    Value,
}

/// An entry on the collection stack, tracking open block sequences and mappings.
///
/// Flow collections are fully parsed by [`crate::EventIter::handle_flow_collection`]
/// before returning; they never leave an entry on this stack.  The combined
/// depth limit (block + flow) is enforced inside `handle_flow_collection` by
/// summing `coll_stack.len()` with the local flow-frame count.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CollectionEntry {
    /// An open block sequence.  Holds the column of its `-` indicator and
    /// whether at least one complete item has been delivered.  `has_had_item`
    /// is `false` for a freshly opened sequence and becomes `true` once a
    /// complete item (scalar or sub-collection) has been emitted.  Used by
    /// `handle_sequence_entry` to detect a `-` at the wrong indentation level.
    Sequence(usize, bool),
    /// An open block mapping.  Holds the column of its first key, the
    /// current phase (expecting key or value), and whether the mapping has
    /// had at least one key advanced to the value phase (`has_had_value`).
    /// `has_had_value` is `false` for a freshly opened mapping and becomes
    /// `true` the first time `advance_mapping_to_value` is called on it.
    /// The wrong-indentation check in `handle_mapping_entry` uses this flag
    /// to avoid false positives on explicit-key content nodes (e.g. V9D5).
    Mapping(usize, MappingPhase, bool),
}

impl CollectionEntry {
    /// The indentation column of this collection's indicator/key.
    pub const fn indent(self) -> usize {
        match self {
            Self::Sequence(col, _) | Self::Mapping(col, _, _) => col,
        }
    }
}

/// Whether the next expected token in a flow mapping is a key or value.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FlowMappingPhase {
    /// Expecting the next key (or the closing `}`).
    Key,
    /// Expecting the value after a key has been consumed.
    Value,
}

/// Disposition of a pending anchor before it's attached to a node event.
///
/// Anchors in YAML precede the node they annotate. After scanning `&name`,
/// the parser stores the name here until the next `Scalar`, `SequenceStart`,
/// or `MappingStart` event is emitted. The disposition determines which
/// node the anchor annotates:
///
/// - `Standalone`: anchor was on its own line (`&name\n- item`) — annotates
///   the next node regardless of type (collection or scalar).
/// - `Inline`: anchor was inline with key content (`&name key: value`) —
///   annotates the key scalar, not the enclosing mapping.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PendingAnchor<'input> {
    Standalone(&'input str, Span),
    Inline(&'input str, Span),
}

impl<'input> PendingAnchor<'input> {
    pub const fn name(self) -> &'input str {
        match self {
            Self::Standalone(n, _) | Self::Inline(n, _) => n,
        }
    }

    pub const fn loc(self) -> Span {
        match self {
            Self::Standalone(_, s) | Self::Inline(_, s) => s,
        }
    }
}

/// Disposition of a pending tag before it's attached to a node event.
///
/// Parallel to [`PendingAnchor`] but for tags. Tags in YAML precede the
/// node they annotate. The disposition determines which node the tag
/// annotates:
///
/// - `Standalone`: tag was on its own line (`!!seq\n- item`) — annotates
///   the next node regardless of type (collection or scalar).
/// - `Inline`: tag was inline with key content (`!!str key: value`) —
///   annotates the key scalar, not the enclosing mapping.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum PendingTag<'input> {
    Standalone(Cow<'input, str>, Span),
    Inline(Cow<'input, str>, Span),
}

impl<'input> PendingTag<'input> {
    pub fn into_cow(self) -> Cow<'input, str> {
        match self {
            Self::Standalone(c, _) | Self::Inline(c, _) => c,
        }
    }

    pub const fn loc(&self) -> Span {
        match self {
            Self::Standalone(_, s) | Self::Inline(_, s) => *s,
        }
    }
}

/// Result of consuming a mapping-entry line.
pub enum ConsumedMapping<'input> {
    /// Explicit key (`? key`).
    ExplicitKey,
    /// Implicit key (`key: value`).
    ///
    /// The key content and span are pre-extracted so the caller can push the
    /// key `Scalar` event directly without routing it through
    /// `try_consume_plain_scalar` — which would treat the adjacent value
    /// synthetic line as a plain-scalar continuation.
    ImplicitKey {
        /// The decoded key value (may be owned if escapes were resolved).
        key_value: std::borrow::Cow<'input, str>,
        /// The scalar style of the key (`Plain`, `SingleQuoted`, or `DoubleQuoted`).
        key_style: ScalarStyle,
        /// Span covering the key text (including quotes if quoted).
        key_span: Span,
    },
    /// The inline value of an implicit key itself contained a value indicator,
    /// making it an illegal inline block mapping (e.g. `a: b: c` or `a: 'b': c`).
    /// The error position points to the start of the inline value content.
    InlineImplicitMappingError { pos: Pos },
    /// A quoted implicit key could not be decoded (e.g. bad escape sequence).
    QuotedKeyError { pos: Pos, message: String },
}

#[cfg(test)]
mod tests {
    use super::{PendingAnchor, PendingTag};
    use crate::pos::{Pos, Span};
    use std::borrow::Cow;

    const TEST_SPAN: Span = Span {
        start: Pos {
            byte_offset: 0,
            line: 1,
            column: 0,
        },
        end: Pos {
            byte_offset: 7,
            line: 1,
            column: 7,
        },
    };

    // A-1: Standalone variant carries the anchor name.
    #[test]
    fn pending_anchor_standalone_carries_name() {
        let a = PendingAnchor::Standalone("myanchor", TEST_SPAN);
        assert_eq!(a.name(), "myanchor");
        assert!(matches!(a, PendingAnchor::Standalone("myanchor", _)));
    }

    // A-2: Inline variant carries the anchor name.
    #[test]
    fn pending_anchor_inline_carries_name() {
        let a = PendingAnchor::Inline("inlineanchor", TEST_SPAN);
        assert_eq!(a.name(), "inlineanchor");
        assert!(matches!(a, PendingAnchor::Inline("inlineanchor", _)));
    }

    // A-3: None::<PendingAnchor> matches the None arm (documents cleared state).
    #[test]
    fn pending_anchor_none_matches_none_arm() {
        let a: Option<PendingAnchor<'_>> = None;
        assert!(a.is_none());
        assert!(!matches!(a, Some(PendingAnchor::Standalone(..))));
        assert!(!matches!(a, Some(PendingAnchor::Inline(..))));
    }

    // SA-1: Standalone variant loc() returns the stored span.
    #[test]
    fn pending_anchor_standalone_loc_returns_span() {
        let span = Span {
            start: Pos {
                byte_offset: 5,
                line: 2,
                column: 3,
            },
            end: Pos {
                byte_offset: 12,
                line: 2,
                column: 10,
            },
        };
        let a = PendingAnchor::Standalone("anchor", span);
        assert_eq!(a.loc(), span);
    }

    // SA-2: Inline variant loc() returns the stored span.
    #[test]
    fn pending_anchor_inline_loc_returns_span() {
        let span = Span {
            start: Pos {
                byte_offset: 10,
                line: 3,
                column: 0,
            },
            end: Pos {
                byte_offset: 17,
                line: 3,
                column: 7,
            },
        };
        let a = PendingAnchor::Inline("anchor", span);
        assert_eq!(a.loc(), span);
    }

    fn dummy_span() -> Span {
        Span {
            start: Pos {
                byte_offset: 0,
                line: 1,
                column: 0,
            },
            end: Pos {
                byte_offset: 1,
                line: 1,
                column: 1,
            },
        }
    }

    // T-1: Standalone variant carries the tag string.
    #[test]
    fn pending_tag_standalone_carries_value() {
        let tag = PendingTag::Standalone(Cow::Borrowed("tag:yaml.org,2002:str"), dummy_span());
        assert!(
            matches!(&tag, PendingTag::Standalone(c, _) if c.as_ref() == "tag:yaml.org,2002:str")
        );
        assert_eq!(tag.into_cow().as_ref(), "tag:yaml.org,2002:str");
    }

    // T-2: Inline variant carries the tag string.
    #[test]
    fn pending_tag_inline_carries_value() {
        let tag = PendingTag::Inline(Cow::Borrowed("!mytag"), dummy_span());
        assert!(matches!(&tag, PendingTag::Inline(c, _) if c.as_ref() == "!mytag"));
        assert_eq!(tag.into_cow().as_ref(), "!mytag");
    }

    // TL-U1: Standalone variant loc() returns the stored span.
    #[test]
    fn pending_tag_standalone_loc_returns_span() {
        let span = Span {
            start: Pos {
                byte_offset: 5,
                line: 2,
                column: 3,
            },
            end: Pos {
                byte_offset: 12,
                line: 2,
                column: 10,
            },
        };
        let tag = PendingTag::Standalone(Cow::Borrowed("!!str"), span);
        assert_eq!(tag.loc(), span);
    }

    // TL-U2: Inline variant loc() returns the stored span.
    #[test]
    fn pending_tag_inline_loc_returns_span() {
        let span = Span {
            start: Pos {
                byte_offset: 10,
                line: 3,
                column: 0,
            },
            end: Pos {
                byte_offset: 17,
                line: 3,
                column: 7,
            },
        };
        let tag = PendingTag::Inline(Cow::Borrowed("!mytag"), span);
        assert_eq!(tag.loc(), span);
    }
}