//! This file defines the expected behaviours of a recursive descent
//! parser.

use super::Regex;
use graph::GraphLabel;

/// A thin wrapper of the parse output, to simplify the function
/// signature a little.
pub type ParseOutput<'a, T> = Option<(T, &'a str)>;

/// Types implementing this trait provide a method to be recursively
/// parsed.
pub trait DesRec {
    /// The type of labels of the resulting regular expression.
    type Label: GraphLabel;

    /// The type of the resulting regular expression.
    type Regex: Regex<Self::Label>;

    /// The type of errors encountered when parsing.
    type Error: std::error::Error;

    /// Intermediate data when parsing
    type Inter;

    /// The type of a scanner that classifies inputs into tokens.
    ///
    /// The return type indicates the result of classification:
    ///
    /// - `Err(_)`: the classification fails
    ///
    /// - `Ok(None)`: the classification succeeds, and the parsing
    /// should stop here
    ///
    /// - `Ok(Some(_))`: the classification succeeds and the parsing
    /// should continue.
    type Scanner<'a, 'b>: FnMut(
        &'b Self,
        &'a str,
    )
        -> Result<Option<(usize, Self::Label, Self::Inter)>, Self::Error>
    where
        Self: 'b,
        Self::Label: 'b;

    /// Parse a string into a regular expression with the aid of this
    /// type.
    ///
    /// Accept a slice of string and return either a parsing error, or
    /// a pair of correctly parsed regular expression and the
    /// remaining slice.
    fn parse<'a, 'b>(
        &'b self,
        input: &'a str,
        scanner: Self::Scanner<'a, 'b>,
        post_p: bool,
    ) -> Result<ParseOutput<'a, Self::Regex>, Self::Error>
    where
        Self::Label: 'b;
}