Trait Rule 

pub trait Rule<'input, SliceType: ?Sized + 'input>: NamedRule {
    type Output;

    // Required method
    fn parse_at<'cursor, 'this, 'index>(
        &'this self,
        input: &'cursor mut &'input SliceType,
        index: &'index mut usize,
    ) -> Result<Self::Output, ParseError>
       where 'input: 'this;

    // Provided methods
    fn parse<'this>(
        &'this self,
        input: &'input SliceType,
    ) -> Result<(&'input SliceType, Self::Output), ParseError>
       where 'input: 'this { ... }
    fn map_parsed<Output, F: Fn(Self::Output) -> Output>(
        self,
        function: F,
    ) -> Map<'input, SliceType, Self, Output, F>
       where Self: Sized { ... }
    fn try_map_parsed<Output, E: Error + 'static, F: Fn(Self::Output) -> Result<Output, E>>(
        self,
        function: F,
    ) -> TryMap<'input, SliceType, Self, Output, E, F>
       where Self: Sized { ... }
    fn prevent(self) -> Not<Self>
       where Self: Sized { ... }
    fn repeat_for<const REPS: usize>(
        self,
    ) -> RepeatFor<'input, SliceType, Self, REPS>
       where Self: Sized { ... }
    fn repeat(self, reps: usize) -> Repeat<'input, SliceType, Self>
       where Self: Sized { ... }
    fn take(self, at_most: usize) -> Many<'input, SliceType, Self>
       where Self: Sized { ... }
    fn hoard(self) -> Many<'input, SliceType, Self>
       where Self: Sized { ... }
    fn take_sep<R: Rule<'input, SliceType>>(
        self,
        separator: R,
        at_most: usize,
    ) -> Separated<'input, SliceType, Self, R>
       where Self: Sized { ... }
    fn hoard_sep<R: Rule<'input, SliceType>>(
        self,
        separator: R,
    ) -> Separated<'input, SliceType, Self, R>
       where Self: Sized { ... }
    fn consume_all(self) -> Consume<'input, SliceType, Self>
       where Self: Sized,
             Consume<'input, SliceType, Self>: Rule<'input, SliceType, Output = Vec<Self::Output>> { ... }
    fn spanned(self) -> Spanned<'input, SliceType, Self>
       where Self: Sized,
             SliceType: Index<RangeTo<usize>, Output = SliceType> { ... }
    fn attempt(self) -> Attempt<'input, SliceType, Self>
       where Self: Sized { ... }
}

Trait dictating that something can be used as a rule within a parsing grammar.

Implementation

Imlpementing this trait means that anyone can use your struct as a rule in any of their their grammars with a supported slice type.

If you’re defining simple rules that don’t depend on the input, you can make rules generic over all slice types!

This is done for most of the “helper rules”, like Any, in this crate.

Required Associated Types

type Output

The type of the value of a successful parse of this rule.

Required Methods

fn parse_at<'cursor, 'this, 'index>( &'this self, input: &'cursor mut &'input SliceType, index: &'index mut usize, ) -> Result<Self::Output, ParseError>

where 'input: 'this,

Parses a rule at a given index with a given input.

Errors

Errors if the rule fails to parse.

Correctness

When a parse succeeds, you must replace the borrowed input and index with a slice of it past the index you stopped parsing at - for example,

*input = &input[2..];
*index += 2;

You also must reset the values of input and index if an error occurs.

For example, this can be done as follows:

let before = (*input, *index);
// later...
let res = match inner_rule.parse_at(input, index) {
    Ok(v) => v,
    Err(err) => {
        (*input, *index) = before;
        return Err(err);
    }
}

Fsilure to do uphold of these could cause other code using your rule to misbehave, potentially inducing panics and/or non-termination.

As this is not a safety contract, implementors cannot rely on this for soundness in unsafe code.

Provided Methods

fn parse<'this>( &'this self, input: &'input SliceType, ) -> Result<(&'input SliceType, Self::Output), ParseError>

where 'input: 'this,

Parses a given rule at the start of some input.

Errors

Errors if the rule fails to parse.

Examples found in repository

examples/math.rs (line 104)

fn main() -> Result<(), std::io::Error> {
    let mut lines = std::io::stdin().lines();
    println!("Input a math expression below, `clear` to clear the console, or `exit` / `quit` to exit.");
    println!("You can access the result of the last expression with `ans`.");
    let mut last_ans = None;
    'outer: loop {
        print!("[?] ");
        std::io::stdout().flush()?;
        let Some(input) = lines.next().transpose()? else { break Ok(()) };
        let input = input.trim_ascii();
        if input.is_empty() { print!("\x1b[1A"); continue; }
        match input {
            "clear" => print!("\x1bc"),
            "exit" | "quit" => break Ok(()),
            _ => {
                let (_, mut tokens) = match MathTokens::LangTokens.parse(&input) {
                    Ok(v) => v,
                    Err(err) => {
                        println!("[!] Failed to parse: {err}");
                        continue;
                    }
                };
                for ans in tokens.iter_mut().filter(|t| matches!(t, Token::Ans)) {
                    let Some(answer) = last_ans else {
                        println!("[!] No previous answer exists");
                        continue 'outer;
                    };
                    *ans = Token::Number(answer);
                }
                let (_, result) = match TokenMath::Expr.parse(tokens.as_ref()) {
                    Ok(v) => v,
                    Err(err) => {
                        println!("[!] Failed to parse: {err}");
                        continue;
                    }
                };
                last_ans = Some(result);
                println!("[=] {result:.}")
            } 
        }
    }
}

fn map_parsed<Output, F: Fn(Self::Output) -> Output>( self, function: F, ) -> Map<'input, SliceType, Self, Output, F>

where Self: Sized,

Maps an infallible function onto the output of a rule.

Examples found in repository

examples/math.rs (line 19)

        pub LangTokens -> Vec<Token> = LangToken.consume_all()
            .map_parsed(|v| v.into_iter().filter_map(|v| v).collect() );

fn try_map_parsed<Output, E: Error + 'static, F: Fn(Self::Output) -> Result<Output, E>>( self, function: F, ) -> TryMap<'input, SliceType, Self, Output, E, F>

where Self: Sized,

Maps a function onto the output of a rule, passing the error back if it fails.

fn prevent(self) -> Not<Self>

where Self: Sized,

Matches when this fails, and vice versa.

fn repeat_for<const REPS: usize>( self, ) -> RepeatFor<'input, SliceType, Self, REPS>

where Self: Sized,

Repeats this rule a known amount of times.

fn repeat(self, reps: usize) -> Repeat<'input, SliceType, Self>

where Self: Sized,

Repeats this rule a set amount of times.

fn take(self, at_most: usize) -> Many<'input, SliceType, Self>

where Self: Sized,

Repeats this rule at most a set amount of times.

fn hoard(self) -> Many<'input, SliceType, Self>

where Self: Sized,

Repeats this rule forever until it fails.

fn take_sep<R: Rule<'input, SliceType>>( self, separator: R, at_most: usize, ) -> Separated<'input, SliceType, Self, R>

where Self: Sized,

Repeats this rule at most a set amount of times, separated by another rule.

fn hoard_sep<R: Rule<'input, SliceType>>( self, separator: R, ) -> Separated<'input, SliceType, Self, R>

where Self: Sized,

Repeats this rule forever until it fails, separated by another rule.

fn consume_all(self) -> Consume<'input, SliceType, Self>

where Self: Sized, Consume<'input, SliceType, Self>: Rule<'input, SliceType, Output = Vec<Self::Output>>,

Repeats this rule until the end of input, failing if it ever does.

Examples found in repository

examples/math.rs (line 18)

        pub LangTokens -> Vec<Token> = LangToken.consume_all()
            .map_parsed(|v| v.into_iter().filter_map(|v| v).collect() );
        LangToken -> Option<Token> = 
            Num : Plus : Minus : Asterisk : Slash : Percent : Carat
            : LParen : RParen : Ans : _ Whitespace 
            : InvalidChar;
        // Since Fail returns !, we can coerce from that to a token
        InvalidChar -> Token from(|_, n| n) = Any, Fail::new(Unexpected::new(arg_0));

        Plus -> Token = '+'.map_parsed(|_| Token::Plus);
        Minus -> Token = '-'.map_parsed(|_| Token::Minus);
        Asterisk -> Token = '*'.map_parsed(|_| Token::Asterisk);
        Slash -> Token = '/'.map_parsed(|_| Token::Slash);
        Percent -> Token = '%'.map_parsed(|_| Token::Percent);
        Carat -> Token = '^'.map_parsed(|_| Token::Carat);
        LParen -> Token = '('.map_parsed(|_| Token::LeftParen);
        RParen -> Token = ')'.map_parsed(|_| Token::RightParen);

        Ans -> Token = "ans".map_parsed(|_| Token::Ans);

        Num -> Token from(|n| Token::Number(n)) = 
            ("nan", "NaN").map_parsed(|_| f64::NAN) : 
            ("inf", "Infinity").map_parsed(|_| f64::INFINITY) : 
            Float;
        Float -> f64 try_from(f64::from_str) = FloatTokens.spanned().map_parsed(|span| span.source);
        
        FloatTokens -> () = _ UInt, _ FloatFract.attempt(), _ FloatExp.attempt();
        FloatFract -> () = _ '.', _ UInt;
        FloatExp -> () = _ ('e', 'E'), _ ('-', '+').attempt(), _ UInt;

        UInt -> &'input str = While::from(char::is_ascii_digit);
    }
}

define! {
    grammar TokenMath<[Token]> {
        pub Expr -> f64 from(parse_expr) = Prod, SumSuf.consume_all();

fn spanned(self) -> Spanned<'input, SliceType, Self>

where Self: Sized, SliceType: Index<RangeTo<usize>, Output = SliceType>,

Captures the output and span of this rule, returning them along with the output in a Span.

fn attempt(self) -> Attempt<'input, SliceType, Self>

where Self: Sized,

Tries to capture this rule, returning None if it doesn’t match.

Implementations on Foreign Types

impl<'input> Rule<'input, str> for char

type Output = char

fn parse_at<'cursor, 'this, 'index>( &'this self, input: &'cursor mut &'input str, index: &'index mut usize, ) -> Result<Self::Output, ParseError>

where 'input: 'this,

impl<'input> Rule<'input, str> for fn(&char) -> bool

type Output = char

fn parse_at<'cursor, 'this, 'index>( &'this self, input: &'cursor mut &'input str, index: &'index mut usize, ) -> Result<Self::Output, ParseError>

where 'input: 'this,

impl<'input> Rule<'input, str> for str

type Output = &'input str

fn parse_at<'cursor, 'this, 'index>( &'this self, input: &'cursor mut &'input str, index: &'index mut usize, ) -> Result<Self::Output, ParseError>

where 'input: 'this,

impl<'input, S: ?Sized + 'input, T: ?Sized + Rule<'input, S>> Rule<'input, S> for &T

type Output = <T as Rule<'input, S>>::Output

fn parse_at<'cursor, 'this, 'index>( &'this self, input: &'cursor mut &'input S, index: &'index mut usize, ) -> Result<Self::Output, ParseError>

where 'input: 'this,

impl<'input, SliceType: ?Sized + 'input, Output, T> Rule<SliceType> for (T₁, T₂, …, Tₙ)

where T: Rule<'input, SliceType, Output = Output>,

For tuples up to arity 16, Rule is implemented as a sort of “anonymous group”, where each rule will be tried in sequence until one matches, or an error will be raised if none do.

The more_tuple_impls feature raises the implemented arity to 256, but massively increases compilation time. Use only when strictly necessary.

type Output = Output

fn parse_at<'cursor, 'this, 'index>( &'this self, input: &'cursor mut &'input SliceType, index: &'index mut usize, ) -> Result<Output, ParseError>

where 'input: 'this,

impl<'input, T: 'input> Rule<'input, [T]> for for<'a> fn(&'a T) -> bool

type Output = &'input T

fn parse_at<'cursor, 'this, 'index>( &'this self, input: &'cursor mut &'input [T], index: &'index mut usize, ) -> Result<Self::Output, ParseError>

where 'input: 'this,

impl<'input, T: PartialEq + 'input> Rule<'input, [T]> for [T]

type Output = &'input [T]

fn parse_at<'cursor, 'this, 'index>( &'this self, input: &'cursor mut &'input [T], index: &'index mut usize, ) -> Result<Self::Output, ParseError>

where 'input: 'this,

impl<'input, const N: usize, T: PartialEq + 'input> Rule<'input, [T]> for [T; N]

type Output = &'input [T]

fn parse_at<'cursor, 'this, 'index>( &'this self, input: &'cursor mut &'input [T], index: &'index mut usize, ) -> Result<Self::Output, ParseError>

where 'input: 'this,

impl<'ty, T, S: ?Sized> Rule<'ty, S> for for<'index, 'cursor> fn(&'cursor mut &'ty S, &'index mut usize) -> Result<T, ParseError>

type Output = T

fn parse_at<'cursor, 'this, 'index>( &'this self, input: &'cursor mut &'ty S, index: &'index mut usize, ) -> Result<T, ParseError>

where 'ty: 'this,

Implementors

impl<'i, S: 'i + ?Sized, O, F: FnMut() -> O> Rule<'i, S> for Action<O, F>

type Output = O

impl<'input> Rule<'input, str> for Any

type Output = char

impl<'input, F: Fn(&char) -> bool> Rule<'input, str> for While<F, char>

type Output = &'input str

impl<'input, R: Rule<'input, str>> Rule<'input, str> for Consume<'input, str, R>

type Output = Vec<<R as Rule<'input, str>>::Output>

impl<'input, SliceType: ?Sized, R: Rule<'input, SliceType>, O, E: Error + 'static, Func: Fn(R::Output) -> Result<O, E>> Rule<'input, SliceType> for TryMap<'input, SliceType, R, O, E, Func>

type Output = O

impl<'input, SliceType: ?Sized, R: Rule<'input, SliceType>, O, Func: Fn(R::Output) -> O> Rule<'input, SliceType> for Map<'input, SliceType, R, O, Func>

type Output = <Func as FnOnce(<R as Rule<'input, SliceType>>::Output)>::Output

impl<'input, T: 'input + Index<RangeTo<usize>, Output = T> + ?Sized, R: Rule<'input, T>> Rule<'input, T> for Spanned<'input, T, R>

type Output = Span<'input, T, <R as Rule<'input, T>>::Output>

impl<'input, T: 'input + ?Sized, R: Rule<'input, T>> Rule<'input, T> for Attempt<'input, T, R>

type Output = Result<<R as Rule<'input, T>>::Output, ParseError>

impl<'input, T: 'input + ?Sized, R: Rule<'input, T>> Rule<'input, T> for Many<'input, T, R>

type Output = Vec<<R as Rule<'input, T>>::Output>

impl<'input, T: 'input + ?Sized, R: Rule<'input, T>> Rule<'input, T> for Repeat<'input, T, R>

type Output = Vec<<R as Rule<'input, T>>::Output>

impl<'input, T: 'input + ?Sized, R: Rule<'input, T>, S: Rule<'input, T>> Rule<'input, T> for Separated<'input, T, R, S>

type Output = Vec<(<R as Rule<'input, T>>::Output, Option<<S as Rule<'input, T>>::Output>)>

impl<'input, T: 'input + ?Sized, R: Rule<'input, T>, const REPETITIONS: usize> Rule<'input, T> for RepeatFor<'input, T, R, REPETITIONS>

type Output = [<R as Rule<'input, T>>::Output; REPETITIONS]

impl<'input, T: 'input> Rule<'input, [T]> for Any

type Output = &'input T

impl<'input, T: 'input, F: Fn(&T) -> bool> Rule<'input, [T]> for While<F, T>

type Output = &'input [T]

impl<'input, T: 'input, R: Rule<'input, [T]>> Rule<'input, [T]> for Consume<'input, [T], R>

type Output = Vec<<R as Rule<'input, [T]>>::Output>

impl<'input, T: ?Sized + 'input, E: Error + Clone + 'static> Rule<'input, T> for Fail<E>

type Output = <fn() -> ! as FnOnce<()>>::Output

impl<'input, T: ?Sized + 'input, R: Rule<'input, T>> Rule<'input, T> for Not<R>

type Output = ()