Generate functions to quickly map byte string prefixes to values

[TreeMatcher] can be used from a [build script] to generate a matcher function that maps byte sequences to arbitrary values. It returns the mapped value (or None) and the remainder of the input.

For example, suppose you generate a matcher for all HTML entities called entity_matcher():

rust assert!(entity_matcher(b"×XYZ") == (Some("×"), b"XYZ".as_slice()));

The prefixes it checks do not all have to be the same length.
If more than one prefix matches, it will return the longest one.
If nothing matches, it will return (None, &input).

Since the matchers only check the start of the input, you will want to use [iter().position()] or the memchr crate to find the start of a potential match.

It can also be configured to accept an iterator over bytes as input instead of a slice.

Simple example

To create a matcher to handle the four basic HTML entities, use a build script like the following:

```rust use matchgen::TreeMatcher; use std::env; use std::error::Error; use std::fs::File; use std::io::{BufWriter, Write}; use std::path::Path;

fn main() -> Result<(), Box> { let outpath = Path::new(&env::var("OUTDIR")?).join("matcher.rs"); let mut out = BufWriter::new(File::create(out_path)?);

writeln!(out, "/// Decode basic HTML entities.")?;
TreeMatcher::new("pub fn entity_decode", "u8")
    .add(b"&amp;", "b'&'")
    .add(b"&lt;", "b'<'")
    .add(b"&gt;", "b'>'")
    .add(b"&quot;", "b'\"'")
    .render(&mut out)?;

Ok(())

} ```

To use the matcher:

```rust include!(concat!(env!("OUT_DIR"), "/matcher.rs"));

fn main() { asserteq!( entitydecode(b"& on & on"), (Some(b'&'), b" on & on".as_slice()), ); } ```

License

This project dual-licensed under the Apache 2 and MIT licenses. You may choose to use either.

Contributions

Unless you explicitly state otherwise, any contribution you submit as defined in the Apache 2.0 license shall be dual licensed as above, without any additional terms or conditions.