Getting started

Welcome to the cflp book. This is to teach you how to use cflp and contains some benchmarks (More on that later)

To start, make sure you've added the library to your Cargo.toml file

cflp = "1.0"

Overview

cflp allows you to derive a parser trait with a derive macro and helper attributes. The macro can derive a context-free language (hence the name of the crate), but the trait can be used more generally if required.

When discussing the trait, we have two types to consider:

I: Input type

C : Comparison type

The parser takes an iterator over input tokens which are of type I and compares them to some instances of the type C. These may be the same type in simple instances, but for more complex uses will most likely be different types.

Required impls

pub trait Parser<I, C, R = Self> where
    I: PartialEq<C>,
    C: PartialEq<C>
{
	fn parse<T>(src: &mut T) -> Result<R, Error<I, C>> where
        I: Iterator<Item=I> + Clone,
        Self: Sized;
}

When deriving the Parser trait, you will need to ensure that your input type I implements PartialEq<C> where C is your comparison type (this will make sense the more you read). You will also need to ensure that C: PartialEq<C>.

IMPORTANT: If the input and comparison types are given as the same thing, deriving PartialEq on the input type will not cover the requirement I: PartialEq<C>. Since the input comes from an iterator, I will be a reference. If the input and comparison types are given as the same, then I = &C. In this case, you will need to impl &C: PartialEq<C>. You can use the PartiqlEqRef derive macro to derive a simple impl for this:

impl PartialEq<C> for &C {
    fn eq(&self, other: &C) -> bool {
        self == other
    }
}