token-parser 0.10.1

#![deny(missing_docs)]

/*!
Some utilities for parsing some format based on nested lists into arbitrary data structures.
It's also meant to be used as a backend for parsers.
**/

use std::{path::PathBuf, rc::Rc, sync::Arc};

use thiserror::Error;

#[cfg(feature = "derive")]
pub use token_parser_derive::{Parsable, SymbolParsable};

/// A trait required for all contexts being used for token parsing.
///
/// By default, only the empty tuple implements it.
/// It currently does not contain anything by default. It's just there to achieve compatibility with features and to allow more changes without breaking anything.
pub trait Context {
    #[cfg(feature = "radix-parsing")]
    #[inline]
    /// Specifies the radix if the feature radix parsing is enabled.
    fn radix(&self) -> u32 {
        10
    }
}

impl Context for () {}

/// A source range with line, column, and byte offsets.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct Span {
    /// The line number of the start position (0-based).
    pub line: usize,
    /// The column number of the start position (0-based).
    pub column: usize,
    /// The byte offset of the start of the span within the source.
    pub start: usize,
    /// The byte offset one past the end of the span within the source.
    pub end: usize,
}

impl std::fmt::Display for Span {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}:{}", self.line + 1, self.column + 1)
    }
}

/// The kind of error that occurred during token parsing.
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum ErrorKind {
    /// The sublist contains fewer elements than the given minimum.
    #[error("Not enough elements: at least {0} expected")]
    NotEnoughElements(usize),

    /// The sublist contains more elements than expected by a specified amount.
    #[error("Too many elements: {0} unexpected")]
    TooManyElements(usize),

    /// No list is allowed in this context.
    #[error("List not allowed")]
    ListNotAllowed,

    /// No symbol is allowed in this context.
    #[error("Symbol not allowed")]
    SymbolNotAllowed,

    /// String parsing failed for the named type.
    #[error("Expected {type_name}: {source}")]
    StringParsing {
        /// The name of the type that failed to parse.
        type_name: &'static str,
        /// The underlying parse error from `FromStr`.
        #[source]
        source: Box<dyn std::error::Error + Send + Sync>,
    },

    /// The named field does not exist.
    #[error("Unknown field {0}")]
    UnknownField(Box<str>),

    /// Some specific element is invalid.
    #[error("Invalid element")]
    InvalidElement,
}

/// The error type for token parsing, containing a kind and an optional source position.
#[derive(Debug)]
pub struct Error {
    /// The kind of error.
    pub kind: ErrorKind,
    /// The source position where the error occurred, if known.
    pub span: Option<Span>,
    /// Optional context describing what was being parsed.
    pub context: Option<Box<str>>,
}

impl std::fmt::Display for Error {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        if let Some(span) = self.span {
            write!(f, "{span}: ")?;
        }
        if let Some(ctx) = &self.context {
            write!(f, "{ctx}: ")?;
        }
        write!(f, "{}", self.kind)
    }
}

impl std::error::Error for Error {}

impl From<ErrorKind> for Error {
    fn from(kind: ErrorKind) -> Self {
        Self {
            kind,
            span: None,
            context: None,
        }
    }
}

impl Error {
    /// Attaches a source position to the error, keeping an already attached position.
    #[must_use]
    pub const fn at(mut self, span: Span) -> Self {
        if self.span.is_none() {
            self.span = Some(span);
        }
        self
    }

    /// Adds descriptive context to the error (e.g., which field was being parsed), keeping already attached context.
    pub fn context(mut self, msg: impl Into<Box<str>>) -> Self {
        if self.context.is_none() {
            self.context = Some(msg.into());
        }
        self
    }
}

/// The result type for token parsing.
pub type Result<T> = std::result::Result<T, Error>;

/// Some unit, which represents an intermediate state.
#[derive(Clone)]
pub enum Unit {
    /// The current unit is a single symbol.
    Symbol(Box<str>, Span),
    /// The current unit is a parser, which can yield multiple units.
    Parser(Parser),
}

impl Unit {
    /// Returns the source span of this unit.
    #[must_use]
    pub const fn span(&self) -> Span {
        match self {
            Self::Symbol(_, span) => *span,
            Self::Parser(parser) => parser.span,
        }
    }

    /// Returns the symbol, if applicable, as a result type.
    ///
    /// # Errors
    ///
    /// Returns an error if this unit is a parser (a sublist), not a symbol.
    pub fn symbol(self) -> Result<Box<str>> {
        match self {
            Self::Symbol(name, _) => Ok(name),
            Self::Parser(parser) => Err(Error::from(ErrorKind::ListNotAllowed).at(parser.span)),
        }
    }

    /// Returns the parser, if applicable, as a result type.
    ///
    /// # Errors
    ///
    /// Returns an error if this unit is a symbol, not a parser.
    pub fn parser(self) -> Result<Parser> {
        match self {
            Self::Parser(parser) => Ok(parser),
            Self::Symbol(_, span) => Err(Error::from(ErrorKind::SymbolNotAllowed).at(span)),
        }
    }

    /// Replaces all occurrences of a symbol with another symbol, recursively.
    pub fn substitute(&mut self, variable: &str, value: &str) {
        match self {
            Self::Symbol(name, _) => {
                if name.as_ref() == variable {
                    *name = value.into();
                }
            }
            Self::Parser(parser) => parser.substitute(variable, value),
        }
    }
}

impl<C: Context> Parsable<C> for Unit {
    fn parse_symbol(name: Box<str>, span: Span, _context: &C) -> Result<Self> {
        Ok(Self::Symbol(name, span))
    }

    fn parse_list(parser: &mut Parser, _context: &C) -> Result<Self> {
        let form = std::mem::take(&mut parser.form);
        let span = parser.span;
        Ok(Self::Parser(Parser {
            form,
            count: 0,
            span,
        }))
    }
}

/// This trait needs to be implemented for every struct which can be parsed using the token parser.
#[expect(clippy::boxed_local)]
pub trait Parsable<C: Context>: Sized {
    /// When a symbol is found by the parser, this will be called.
    ///
    /// # Errors
    ///
    /// The default implementation always returns `ErrorKind::SymbolNotAllowed`;
    /// implementors override this for types parsable from a symbol.
    fn parse_symbol(_name: Box<str>, _span: Span, _context: &C) -> Result<Self> {
        Err(ErrorKind::SymbolNotAllowed.into())
    }

    /// When a subparser is found by the parser, this will be called.
    ///
    /// # Errors
    ///
    /// The default implementation always returns `ErrorKind::ListNotAllowed`;
    /// implementors override this for types parsable from a sublist.
    fn parse_list(_parser: &mut Parser, _context: &C) -> Result<Self> {
        Err(ErrorKind::ListNotAllowed.into())
    }
}

/// The reverse of `Parsable`: emits a token `Unit` from a value.
///
/// Round-trip target: for a value `v` of type `T: Parsable<C> + Unparsable<C>`,
/// parsing the unit returned by `v.to_unit(context)` yields a value equal to `v`.
pub trait Unparsable<C: Context> {
    /// Produces the unit representing `self` in the given context.
    fn to_unit(&self, context: &C) -> Unit;
}

fn parse<C: Context, P: Parsable<C>>(unit: Unit, context: &C) -> Result<P> {
    match unit {
        Unit::Symbol(name, span) => {
            Parsable::parse_symbol(name, span, context).map_err(|e| e.at(span))
        }
        Unit::Parser(mut parser) => {
            let span = parser.span;
            Parsable::parse_list(&mut parser, context).map_err(|e| e.at(span))
        }
    }
}

impl<C: Context, T: Parsable<C>> Parsable<C> for Box<T> {
    fn parse_symbol(name: Box<str>, span: Span, context: &C) -> Result<Self> {
        Ok(Self::new(Parsable::parse_symbol(name, span, context)?))
    }

    fn parse_list(parser: &mut Parser, context: &C) -> Result<Self> {
        Ok(Self::new(parser.parse_list(context)?))
    }
}

impl<C: Context, T: Parsable<C>> Parsable<C> for Rc<T> {
    fn parse_symbol(name: Box<str>, span: Span, context: &C) -> Result<Self> {
        Ok(Self::new(Parsable::parse_symbol(name, span, context)?))
    }

    fn parse_list(parser: &mut Parser, context: &C) -> Result<Self> {
        Ok(Self::new(parser.parse_list(context)?))
    }
}

impl<C: Context, T: Parsable<C>> Parsable<C> for Arc<T> {
    fn parse_symbol(name: Box<str>, span: Span, context: &C) -> Result<Self> {
        Ok(Self::new(Parsable::parse_symbol(name, span, context)?))
    }

    fn parse_list(parser: &mut Parser, context: &C) -> Result<Self> {
        Ok(Self::new(parser.parse_list(context)?))
    }
}

impl<C: Context, T: Parsable<C>> Parsable<C> for Vec<T> {
    fn parse_list(parser: &mut Parser, context: &C) -> Result<Self> {
        let Parser { form, count, .. } = parser;
        form.drain(..)
            .rev()
            .map(|unit| {
                *count += 1;
                parse(unit, context)
            })
            .collect()
    }
}

impl<C: Context> Parsable<C> for String {
    fn parse_symbol(name: Box<str>, _span: Span, _context: &C) -> Result<Self> {
        Ok(name.into())
    }
}

impl<C: Context> Parsable<C> for Box<str> {
    fn parse_symbol(name: Box<str>, _span: Span, _context: &C) -> Result<Self> {
        Ok(name)
    }
}

impl<C: Context> Parsable<C> for PathBuf {
    fn parse_symbol(name: Box<str>, _span: Span, _context: &C) -> Result<Self> {
        Ok(name.as_ref().into())
    }
}

impl<C: Context, T: Unparsable<C> + ?Sized> Unparsable<C> for Box<T> {
    fn to_unit(&self, context: &C) -> Unit {
        (**self).to_unit(context)
    }
}

impl<C: Context, T: Unparsable<C> + ?Sized> Unparsable<C> for Rc<T> {
    fn to_unit(&self, context: &C) -> Unit {
        (**self).to_unit(context)
    }
}

impl<C: Context, T: Unparsable<C> + ?Sized> Unparsable<C> for Arc<T> {
    fn to_unit(&self, context: &C) -> Unit {
        (**self).to_unit(context)
    }
}

impl<C: Context, T: Unparsable<C>> Unparsable<C> for Vec<T> {
    fn to_unit(&self, context: &C) -> Unit {
        let items: Vec<Unit> = self.iter().map(|item| item.to_unit(context)).collect();
        Unit::Parser(Parser::new(items))
    }
}

impl<C: Context> Unparsable<C> for String {
    fn to_unit(&self, _context: &C) -> Unit {
        Unit::Symbol(self.clone().into_boxed_str(), Span::default())
    }
}

impl<C: Context> Unparsable<C> for str {
    fn to_unit(&self, _context: &C) -> Unit {
        Unit::Symbol(self.into(), Span::default())
    }
}

impl<C: Context> Unparsable<C> for PathBuf {
    fn to_unit(&self, _context: &C) -> Unit {
        Unit::Symbol(self.to_string_lossy().into(), Span::default())
    }
}

/// Derives `Parsable` from symbol for types which implement `FromStr`.
#[macro_export]
macro_rules! derive_symbol_parsable {
    ($t:ty) => {
        impl<C: $crate::Context> $crate::Parsable<C> for $t {
            fn parse_symbol(name: Box<str>, _span: $crate::Span, _context: &C) -> $crate::Result<Self> {
                name.parse().map_err(|error| $crate::ErrorKind::StringParsing {
                    type_name: stringify!($t),
                    source: Box::new(error),
                }.into())
            }
        }
    };
    ($t:ty, $($rest:ty),+) => {
        derive_symbol_parsable!($t);
        derive_symbol_parsable!($($rest),+);
    };
}

/// Derives `Unparsable` from symbol for types which implement `Display`.
#[macro_export]
macro_rules! derive_symbol_unparsable {
    ($t:ty) => {
        impl<C: $crate::Context> $crate::Unparsable<C> for $t {
            fn to_unit(&self, _context: &C) -> $crate::Unit {
                $crate::Unit::Symbol(
                    ::std::string::ToString::to_string(self).into(),
                    $crate::Span::default(),
                )
            }
        }
    };
    ($t:ty, $($rest:ty),+) => {
        derive_symbol_unparsable!($t);
        derive_symbol_unparsable!($($rest),+);
    };
}

#[cfg(not(feature = "radix-parsing"))]
mod numbers;
derive_symbol_parsable!(bool);
derive_symbol_unparsable!(bool);
derive_symbol_unparsable!(i8, i16, i32, i64, i128);
derive_symbol_unparsable!(u8, u16, u32, u64, u128);
derive_symbol_unparsable!(f32, f64);
derive_symbol_unparsable!(usize);

/// The token parser to parse the units into wanted types.
#[derive(Clone)]
pub struct Parser {
    form: Vec<Unit>,
    count: usize,
    span: Span,
}

impl Parser {
    /// Creates a new parser from a list of objects.
    pub fn new<I: IntoIterator>(form: I) -> Self
    where
        I::Item: Into<Unit>,
    {
        let mut form: Vec<_> = form.into_iter().map(I::Item::into).collect();
        form.reverse();
        Self {
            form,
            count: 0,
            span: Span::default(),
        }
    }

    /// Sets the span for this parser (builder pattern).
    #[must_use]
    pub const fn with_span(mut self, span: Span) -> Self {
        self.span = span;
        self
    }

    /// Returns the source span of this parser.
    #[must_use]
    pub const fn span(&self) -> Span {
        self.span
    }

    /// Returns whether the parser has no remaining elements.
    #[must_use]
    pub const fn is_empty(&self) -> bool {
        self.form.is_empty()
    }

    /// Returns the number of remaining elements.
    #[must_use]
    pub const fn len(&self) -> usize {
        self.form.len()
    }

    /// Replaces all occurrences of a symbol with another symbol, recursively.
    pub fn substitute(&mut self, variable: &str, value: &str) {
        for unit in &mut self.form {
            unit.substitute(variable, value);
        }
    }

    /// Returns the next unit without parsing it, or `None` if empty.
    pub fn next_unit(&mut self) -> Option<Unit> {
        self.count += 1;
        self.form.pop()
    }

    /// Tries to parse the next unit as the required type.
    ///
    /// # Errors
    ///
    /// Returns `ErrorKind::NotEnoughElements` if no elements remain, or
    /// whatever error `T`'s `Parsable` implementation returns.
    pub fn parse_next<C: Context, T: Parsable<C>>(&mut self, context: &C) -> Result<T> {
        self.count += 1;
        if let Some(token) = self.form.pop() {
            parse(token, context)
        } else {
            Result::Err(Error {
                kind: ErrorKind::NotEnoughElements(self.count),
                span: Some(self.span),
                context: None,
            })
        }
    }

    /// Tries to parse the next unit as the required type, returning `None` if no elements remain.
    ///
    /// # Errors
    ///
    /// Returns whatever error `T`'s `Parsable` implementation returns.
    pub fn parse_next_optional<C: Context, T: Parsable<C>>(
        &mut self,
        context: &C,
    ) -> Result<Option<T>> {
        if Self::is_empty(self) {
            Ok(None)
        } else {
            self.parse_next(context).map(Some)
        }
    }

    /// Tries to parse the rest of the current list into the required type.
    /// If not every available token is used, this will be an error.
    ///
    /// # Errors
    ///
    /// Returns `ErrorKind::TooManyElements` if tokens remain unconsumed
    /// after parsing, or whatever error `T`'s `Parsable` implementation
    /// returns.
    pub fn parse_rest<C: Context, T: Parsable<C>>(&mut self, context: &C) -> Result<T> {
        let result = self.parse_list(context);
        let count = self.form.len();
        if count > 0 {
            self.form.clear();
            result?;
            Err(Error {
                kind: ErrorKind::TooManyElements(count),
                span: Some(self.span),
                context: None,
            })
        } else {
            result
        }
    }

    /// Tries to parse as many tokens of the current list as needed into the required type.
    ///
    /// # Errors
    ///
    /// Returns whatever error `T`'s `Parsable` implementation returns.
    pub fn parse_list<C: Context, T: Parsable<C>>(&mut self, context: &C) -> Result<T> {
        Parsable::parse_list(self, context)
    }
}

impl Iterator for Parser {
    type Item = Result<Self>;

    fn next(&mut self) -> Option<Result<Self>> {
        self.count += 1;
        Some(self.form.pop()?.parser())
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        let remaining = self.form.len();
        (remaining, Some(remaining))
    }
}

#[cfg(feature = "radix-parsing")]
/// Contains utilities for radix parsing.
pub mod radix;