noyalib/

document.rs

//! Multi-document YAML loading.
//!
//! This module provides functionality for parsing YAML documents that contain
//! multiple documents separated by `---`.
//!
//! # Examples
//!
//! ```rust
//! use noyalib::document::load_all;
//!
//! let yaml = "---
//! name: doc1
//! ---
//! name: doc2
//! ";
//!
//! let docs: Vec<_> = load_all(yaml).unwrap().collect();
//! assert_eq!(docs.len(), 2);
//! ```

// SPDX-License-Identifier: MIT OR Apache-2.0
// Copyright (c) 2026 Noyalib. All rights reserved.

use crate::de::ParserConfig;
use crate::error::{Error, Result};
use crate::parser;
use crate::prelude::*;
#[cfg(feature = "std")]
use crate::span_context::{self, SpanTree};
use crate::value::Value;
#[cfg(not(feature = "std"))]
use alloc::vec::IntoIter;
#[cfg(feature = "std")]
use core::marker::PhantomData;
#[cfg(feature = "std")]
use std::vec::IntoIter;

/// An iterator over YAML documents in a string.
///
/// Created by the [`load_all`] function.
///
/// # Examples
///
/// ```
/// use noyalib::document::load_all;
/// let iter = load_all("---\na: 1\n---\nb: 2\n").unwrap();
/// assert_eq!(iter.len(), 2);
/// ```
#[derive(Debug)]
pub struct DocumentIterator {
    docs: IntoIter<Value>,
    #[cfg(feature = "std")]
    _span_trees: Vec<SpanTree>,
    total: usize,
}

impl DocumentIterator {
    /// Returns the total number of documents parsed.
    ///
    /// # Examples
    ///
    /// ```
    /// use noyalib::document::load_all;
    /// let iter = load_all("a: 1\n").unwrap();
    /// assert_eq!(iter.len(), 1);
    /// ```
    #[must_use]
    pub fn len(&self) -> usize {
        self.total
    }

    /// Returns true if there are no documents.
    ///
    /// # Examples
    ///
    /// ```
    /// use noyalib::document::load_all;
    /// let iter = load_all("a: 1\n").unwrap();
    /// assert!(!iter.is_empty());
    /// ```
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.total == 0
    }
}

impl Iterator for DocumentIterator {
    type Item = Result<Value>;

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

    fn size_hint(&self) -> (usize, Option<usize>) {
        self.docs.size_hint()
    }
}

impl ExactSizeIterator for DocumentIterator {}

/// Load all YAML documents from a string.
///
/// This function parses a YAML string that may contain multiple documents
/// separated by `---` markers. Default security limits are applied.
///
/// # Examples
///
/// ```rust
/// use noyalib::document::load_all;
///
/// let yaml = "---
/// first: 1
/// ---
/// second: 2
/// ";
///
/// let docs: Vec<_> = load_all(yaml).unwrap().filter_map(Result::ok).collect();
/// assert_eq!(docs.len(), 2);
/// ```
///
/// # Errors
///
/// Returns an error if the YAML syntax is invalid.
pub fn load_all(input: &str) -> Result<DocumentIterator> {
    load_all_with_config(input, &ParserConfig::default())
}

/// Load all YAML documents from a string with custom security limits.
///
/// # Errors
///
/// Returns an error if the YAML syntax is invalid or the document
/// exceeds the configured limits.
///
/// # Examples
///
/// ```
/// use noyalib::{document::load_all_with_config, ParserConfig};
/// let cfg = ParserConfig::new();
/// let iter = load_all_with_config("a: 1\n---\nb: 2\n", &cfg).unwrap();
/// assert_eq!(iter.len(), 2);
/// ```
pub fn load_all_with_config(input: &str, config: &ParserConfig) -> Result<DocumentIterator> {
    if input.len() > config.max_document_length {
        return Err(Error::Parse(format!(
            "document exceeds maximum length of {} bytes",
            config.max_document_length
        )));
    }
    let parse_config = parser::ParseConfig::from(config);

    #[cfg(feature = "std")]
    {
        let mut pairs = parser::parse(input, &parse_config)?;
        for (doc, _) in &mut pairs {
            crate::de::post_process_document(doc, config)?;
        }
        let (docs, span_trees): (Vec<_>, Vec<_>) = pairs.into_iter().unzip();
        let total = docs.len();
        Ok(DocumentIterator {
            docs: docs.into_iter(),
            _span_trees: span_trees,
            total,
        })
    }

    #[cfg(not(feature = "std"))]
    {
        let mut docs = parser::parse_all_values(input, &parse_config)?;
        for doc in &mut docs {
            crate::de::post_process_document(doc, config)?;
        }
        let total = docs.len();
        Ok(DocumentIterator {
            docs: docs.into_iter(),
            total,
        })
    }
}

/// Load all YAML documents from a string, returning an error if parsing fails.
///
/// This is an alias for [`load_all`] which also returns errors on invalid
/// syntax.
///
/// # Examples
///
/// ```rust
/// use noyalib::document::try_load_all;
///
/// let yaml = "---
/// first: 1
/// ---
/// second: 2
/// ";
///
/// let iter = try_load_all(yaml).unwrap();
/// assert_eq!(iter.len(), 2);
/// ```
///
/// # Errors
///
/// Returns an error if the YAML syntax is invalid.
pub fn try_load_all(input: &str) -> Result<DocumentIterator> {
    load_all(input)
}

/// Load all YAML documents and deserialize them into a typed vector.
///
/// # Examples
///
/// ```rust
/// use noyalib::document::load_all_as;
///
/// #[derive(Debug, serde::Deserialize, PartialEq)]
/// struct Doc {
///     name: String,
/// }
///
/// let yaml = "---
/// name: first
/// ---
/// name: second
/// ";
///
/// let docs: Vec<Doc> = load_all_as(yaml).unwrap();
/// assert_eq!(docs.len(), 2);
/// assert_eq!(docs[0].name, "first");
/// assert_eq!(docs[1].name, "second");
/// ```
///
/// # Errors
///
/// Returns an error if parsing fails or if any document cannot be
/// deserialized into the target type.
pub fn load_all_as<T>(input: &str) -> Result<Vec<T>>
where
    T: for<'de> serde_core::Deserialize<'de> + 'static,
{
    load_all_as_with_config(input, &ParserConfig::default())
}

/// [`load_all_as`] with a custom [`ParserConfig`]: its limits, its
/// scalar-resolution and merge settings, and its policies.
///
/// # Errors
///
/// Returns an error if the stream exceeds a configured limit, a policy
/// refuses a document, parsing fails, or a document cannot be
/// deserialized into `T`.
///
/// # Examples
///
/// ```
/// use noyalib::{load_all_as_with_config, ParserConfig};
/// let cfg = ParserConfig::strict();
/// let docs: Vec<i32> = load_all_as_with_config("1\n---\n2\n", &cfg).unwrap();
/// assert_eq!(docs, vec![1, 2]);
/// ```
pub fn load_all_as_with_config<T>(input: &str, config: &ParserConfig) -> Result<Vec<T>>
where
    T: for<'de> serde_core::Deserialize<'de> + 'static,
{
    if input.len() > config.max_document_length {
        return Err(Error::Parse(format!(
            "document exceeds maximum length of {} bytes",
            config.max_document_length
        )));
    }
    let parse_config = parser::ParseConfig::from(config);

    #[cfg(feature = "std")]
    {
        let mut pairs = parser::parse(input, &parse_config)?;
        let mut results = Vec::with_capacity(pairs.len());
        let source: Arc<str> = input.into();
        let lines = span_context::SharedLineIndex::default();

        for (value, span_tree) in &mut pairs {
            crate::de::post_process_document(value, config)?;
            let spans = span_context::build_span_map(value, span_tree);
            let ctx = span_context::SpanContext::with_lines(spans, source.clone(), lines.clone())
                .with_key_texts(value, span_tree);
            let typed: T = crate::de::from_value_spanned_with_options(
                value,
                ctx,
                config.ignore_binary_tag_for_string,
                config.plain_scalar_strings,
            )?;
            results.push(typed);
        }

        Ok(results)
    }

    #[cfg(not(feature = "std"))]
    {
        let mut docs = parser::parse_all_values(input, &parse_config)?;
        let mut results = Vec::with_capacity(docs.len());
        for value in &mut docs {
            crate::de::post_process_document(value, config)?;
            let typed: T = crate::de::from_value_with_options(
                value,
                config.ignore_binary_tag_for_string,
                config.plain_scalar_strings,
            )?;
            results.push(typed);
        }
        Ok(results)
    }
}

/// Lazy iterator that yields `Result<T>` per YAML document parsed
/// from a reader.
///
/// Created by [`read`] / [`read_with_config`]. Deserialisation
/// errors on individual documents are surfaced as `Err` values; the
/// iterator continues so callers can recover and process subsequent
/// documents. Syntax errors during the initial parse are returned
/// from [`read`] / [`read_with_config`] before iteration starts.
///
/// # Memory
///
/// Today the reader is fully drained into a `String` before the
/// underlying parser runs, so memory is `O(input_len)`. True
/// `O(1)`-document streaming requires a parser-level rewrite that
/// can accept incremental byte chunks; that work is tracked
/// separately.
#[cfg(feature = "std")]
#[derive(Debug)]
pub struct DocumentReadIterator<T> {
    docs: IntoIter<(Value, SpanTree)>,
    source: Arc<str>,
    ignore_binary_tag_for_string: bool,
    plain_scalar_strings: bool,
    _phantom: PhantomData<fn() -> T>,
}

#[cfg(feature = "std")]
impl<T> DocumentReadIterator<T> {
    /// Total number of documents pending iteration.
    ///
    /// # Examples
    ///
    /// ```
    /// use std::io::Cursor;
    /// let yaml = "a: 1\n---\nb: 2\n";
    /// let iter: noyalib::DocumentReadIterator<noyalib::Value> =
    ///     noyalib::read(Cursor::new(yaml)).unwrap();
    /// assert_eq!(iter.len(), 2);
    /// ```
    #[must_use]
    pub fn len(&self) -> usize {
        self.docs.len()
    }

    /// Whether the iterator has no further documents.
    ///
    /// # Examples
    ///
    /// ```
    /// use std::io::Cursor;
    /// let iter: noyalib::DocumentReadIterator<noyalib::Value> =
    ///     noyalib::read(Cursor::new("")).unwrap();
    /// assert!(iter.is_empty());
    /// ```
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.docs.len() == 0
    }
}

#[cfg(feature = "std")]
impl<T> Iterator for DocumentReadIterator<T>
where
    T: for<'de> serde_core::Deserialize<'de> + 'static,
{
    type Item = Result<T>;
    fn next(&mut self) -> Option<Self::Item> {
        let (value, span_tree) = self.docs.next()?;
        let spans = span_context::build_span_map(&value, &span_tree);
        let ctx = span_context::SpanContext::new(spans, self.source.clone())
            .with_key_texts(&value, &span_tree);
        Some(crate::de::from_value_spanned_with_options(
            &value,
            ctx,
            self.ignore_binary_tag_for_string,
            self.plain_scalar_strings,
        ))
    }
    fn size_hint(&self) -> (usize, Option<usize>) {
        self.docs.size_hint()
    }
}

#[cfg(feature = "std")]
impl<T> ExactSizeIterator for DocumentReadIterator<T> where
    T: for<'de> serde_core::Deserialize<'de> + 'static
{
}

/// Stream-decode every YAML document from a reader into typed
/// values, yielding one `Result<T>` per document.
///
/// The reader is drained eagerly (see [`DocumentReadIterator`] for
/// the memory caveat); document-by-document deserialisation is then
/// produced lazily on demand. Per-document deserialisation errors
/// surface as `Err` values inside the iterator so callers can
/// recover and continue. A syntax error in the underlying YAML is
/// returned synchronously from this function before any iteration
/// happens.
///
/// # Errors
///
/// Returns an error if the reader fails, the YAML cannot be parsed,
/// or any document exceeds the default security limits. Per-document
/// deserialisation errors are *not* surfaced here; they appear
/// inside the iterator.
///
/// # Examples
///
/// ```
/// use std::io::Cursor;
///
/// #[derive(Debug, serde::Deserialize, PartialEq)]
/// struct Doc { id: u32 }
///
/// let yaml = "id: 1\n---\nid: 2\n---\nid: 3\n";
/// let docs: Vec<Doc> = noyalib::read::<_, Doc>(Cursor::new(yaml))
///     .unwrap()
///     .filter_map(Result::ok)
///     .collect();
/// assert_eq!(docs, vec![Doc { id: 1 }, Doc { id: 2 }, Doc { id: 3 }]);
/// ```
#[cfg(feature = "std")]
pub fn read<R, T>(reader: R) -> Result<DocumentReadIterator<T>>
where
    R: std::io::Read,
    T: for<'de> serde_core::Deserialize<'de> + 'static,
{
    read_with_config(reader, &ParserConfig::default())
}

/// [`read`] with a custom [`ParserConfig`] for tightened security
/// limits.
///
/// # Errors
///
/// Same as [`read`].
///
/// # Examples
///
/// ```
/// use std::io::Cursor;
/// use noyalib::{read_with_config, ParserConfig, Value};
///
/// let cfg = ParserConfig::strict();
/// let yaml = "a: 1\n---\nb: 2\n";
/// let count = read_with_config::<_, Value>(Cursor::new(yaml), &cfg)
///     .unwrap()
///     .count();
/// assert_eq!(count, 2);
/// ```
#[cfg(feature = "std")]
pub fn read_with_config<R, T>(
    mut reader: R,
    config: &ParserConfig,
) -> Result<DocumentReadIterator<T>>
where
    R: std::io::Read,
    T: for<'de> serde_core::Deserialize<'de> + 'static,
{
    use std::io::Read as _;

    // Cap on the *aggregated* multi-document buffer: `max_stream_bytes`,
    // or 64 times `max_document_length` when that is smaller. Reading
    // stops one byte past it, so an unbounded reader is refused
    // without being buffered first.
    let doc_cap = config.max_document_length.saturating_mul(64);
    let cap = config.max_stream_bytes.min(doc_cap);
    let limit = u64::try_from(cap).unwrap_or(u64::MAX).saturating_add(1);
    let mut bytes = Vec::new();
    let _read_bytes = reader
        .by_ref()
        .take(limit)
        .read_to_end(&mut bytes)
        .map_err(|e| Error::Parse(format!("reader I/O failed: {e}")))?;
    if bytes.len() > cap {
        return Err(Error::Parse(if cap < doc_cap {
            format!("reader payload exceeds max_stream_bytes ({cap} bytes)")
        } else {
            format!(
                "reader payload exceeds 64× max_document_length ({} bytes)",
                config.max_document_length
            )
        }));
    }
    let buf = String::from_utf8(bytes).map_err(|_| {
        Error::Parse("reader I/O failed: stream did not contain valid UTF-8".into())
    })?;
    // The stream may hold up to 64 documents' worth of bytes, but each
    // document is still held to `max_document_length`, as every other
    // entry point holds it.
    for doc in crate::doc_boundary::split_documents_checked(&buf, config.max_documents)? {
        if doc.len() > config.max_document_length {
            return Err(Error::Parse(format!(
                "document exceeds maximum length of {} bytes",
                config.max_document_length
            )));
        }
    }
    let parse_config = parser::ParseConfig::from(config);
    let mut pairs = parser::parse(&buf, &parse_config)?;
    for (doc, _) in &mut pairs {
        crate::de::post_process_document(doc, config)?;
    }
    Ok(DocumentReadIterator {
        docs: pairs.into_iter(),
        source: buf.into(),
        ignore_binary_tag_for_string: config.ignore_binary_tag_for_string,
        plain_scalar_strings: config.plain_scalar_strings,
        _phantom: PhantomData,
    })
}