[][src]Crate gobble

Gobble is a simple parser combinator system for parsing strings.

For example parsing a function call

use gobble::*;
let ident = || string_2_parts(Alpha.min_n(1),(Alpha,NumDigit,'_').any());

let fsig = (ident().then_ig("("),sep(ident(),",",0).then_ig(")"));
  
 let (nm, args) = fsig.parse_s("loadFile1(fname,ref)").unwrap();
 assert_eq!(nm, "loadFile1");
 assert_eq!(args, vec!["fname", "ref"]);

 //identifiers cant start with numbers,
 assert!(fsig.parse_s("23file(fname,ref)").is_err());
  

To work this library depends the following:

pub enum ParseError {
   //...
}
//The LCChars in the result will be a clone of the incoming iterator
//but having iterated to end of the what the parser required.
pub type ParseRes<'a, V> = Result<(LCChars<'a>, V), ParseError>;

//implements Iterator and can be cloned relatively cheaply
pub struct LCChars<'a>{
   it:std::str::Chars<'a>,
   line:usize,
   col:usize,
}

pub trait Parser<V> {
   // Takes a non mut pointer to the iterator, so that the caller
   // may try something else if this doesn't work
   // clone it before reading next
   fn parse<'a>(&self,it:&LCChars<'a>)->ParseRes<'a,V>;
    
   //...helper methods
}
pub trait BoolChar {
   fn bool_char(&self,c:char)->bool;
   //....helper methods
}

Parser is automatically implemented for:

  • Fn<'a>(&LCChars<'a>)->ParseRes<'a,String>
  • &'static str which will return itself if it matches
  • char which will return itself if it matched the next char
  • Tuples of up to 6 parsers. Returning a tuple of all the parsers matched one after the other.

Most of the time a parser can be built simply by combining other parsers

use gobble::*;

// map can be used to convert one result to another
// keyval is now a function that returns a parser
let keyval = || (common_ident,":",common_str).map(|(a,_,c)|(a,c));

//this can also be written as below for better type safety
fn keyval2()->impl Parser<(String,String)>{
   (common_ident,":",common_str).map(|(a,_,c)|(a,c))
}
 
//parse_s is a helper on Parsers
let (k,v) = keyval().parse_s(r#"car:"mini""#).unwrap();
assert_eq!(k,"car");
assert_eq!(v,"mini");

//this can now be combined with other parsers.
// 'ig_then' combines 2 parsers and drops the result of the first
// 'then_ig' drops the result of the second
// 'sep_until will repeat the first term into a Vec, separated by the second
//    until the final term.
let obj = || "{".ig_then(sep_until(keyval(),",","}"));

let obs = obj().parse_s(r#"{cat:"Tiddles",dog:"Spot"}"#).unwrap();
assert_eq!(obs[0],("cat".to_string(),"Tiddles".to_string()));

CharBool

CharBool is the trait for boolean char checks. It is auto implemented for:

  • Fn(char)->bool
  • char -- Returns true if the input matches the char
  • &'static str -- returns true if the str contains the input
  • several zero size types - Alpha,NumDigit,HexDigit,WS,WSL,Any
  • Tuples of up to 6 CharBools -- returning true if any of the members succeed

This means you can combine them in tuples (Alpha,NumDigit,"_").char_bool(c) will be true if any of them match

CharBool also provides 3 helper methods which each return a parser

  • one() matches and returns exactly 1 character
  • min_n(n) requires at least n matches ruturns a string
  • any() matches any number of chars returning a string

And a helper that returns a CharBool

  • except(cb) Passes if self does, and cb doesnt
use gobble::*;
let s = |c| c > 'w' || c == 'z';
let xv = s.one().parse_s("xhello").unwrap();
assert_eq!(xv,'x');

let id = (Alpha,"_*").min_n(4).parse_s("sm*shing_game+you").unwrap();
assert_eq!(id,"sm*shing_game");

// not enough matches
assert!((NumDigit,"abc").min_n(4).parse_s("23fflr").is_err());

// any succeeds even with no matches equivilent to min(0)
assert_eq!((NumDigit,"abc").any().parse_s("23fflr"),Ok("23".to_string()));
assert_eq!((NumDigit,"abc").any().parse_s("fflr"),Ok("".to_string()));

White Space

White space is pretty straight forward to handle

use gobble::*;
let my_ws = || " \t".any();
// middle takes three parsers and returns the result of the middle
// this could also be done easily with 'map' or 'then_ig'
let my_s = |p| middle(my_ws(),p,my_ws());

let sp_id = my_s(common_ident);
let v = sp_id.parse_s("   \t  doggo  ").unwrap();
assert_eq!(v,"doggo");

That said gobble already provides ws() and s_(p)

use gobble::*;
//eoi = end of input
let p = repeat_until_ig(s_("abc".min_n(1)),eoi);
let r = p.parse_s("aaa \tbbb bab").unwrap();
assert_eq!(r,vec!["aaa","bbb","bab"]);

Recursive Structures

Some structures like Json, or programming languages need to be able to handle recursion. However with the techniques we have used so far this would lead to infinitely sized structures.

The way to handle this is to make sure one member of the loop is not
build into the structure. Instead to create it using the 'Fn'

use gobble::*;
#[derive(Debug,PartialEq)]
enum Expr {
    Val(isize),
    Add(Box<Expr>,Box<Expr>),
    Paren(Box<Expr>),
}

fn expr_l()->impl Parser<Expr>{
    or(
        middle("(",s_(expr),")").map(|e|Expr::Paren(Box::new(e))),
        common_int.map(|v|Expr::Val(v))
    )
}

// using the full fn def we avoid the recursive structure
fn expr<'a>(it:&LCChars<'a>)->ParseRes<'a,Expr> {
    //note that expr_l has brackets but expr doesnt.
    //expr is a reference to a static function
    let p = (expr_l(),maybe(s_("+").ig_then(expr)))
        .map(|(l,opr)|match opr{
            Some(r)=>Expr::Add(Box::new(l),Box::new(r)),
            None=>l,
        });
     

    p.parse(it)
}

let r = expr.parse_s("45 + (34+3 )").unwrap();

//recursive structures are never fun to write manually
assert_eq!(r,Expr::Add(
                Box::new(Expr::Val(45)),
                Box::new(Expr::Paren(Box::new(Expr::Add(
                    Box::new(Expr::Val(34)),
                    Box::new(Expr::Val(3))
                ))))
            ));

Re-exports

pub use chars::*;
pub use combi::*;
pub use common::*;
pub use err::*;
pub use iter::*;
pub use ptrait::*;
pub use reader::*;
pub use repeater::*;
pub use skip::*;
pub use strings::*;
pub use tuple::*;

Modules

chars
combi
common
err
iter
ptrait
reader
repeater
skip
strings
tuple