Struct pidgin::Grammar

pub struct Grammar {
    pub name: Option<String>,
    /* private fields */
}

A compiled collection of rules ready for the building of a pidgin::Matcher or for use in the definition of a new rule.

You do not build new Grammars directly. Rather, the compile or grammar method of a Pidgin produces them for you.

Fields

name: Option<String>

Implementations

impl Grammar

pub fn name(&mut self, name: &str)

Assigns a name to the grammar.

This will have no effect on any uses of the grammar already in rules.

Examples

let mut p = Pidgin::new();
let g = p.grammar(&vec!["foo", "bar", "baz"]);
p.rule("foo", &g);
let mut g = p.grammar(&vec!["foo cat", "foo dog"]);
print!("{}", g);
// TOP := {foo} (?:cat|dog)
// foo := foo|ba[rz]
g.name("Bartholemew");
print!("{}", g);
// Bartholemew := {foo} (?:cat|dog)
//         foo := foo|ba[rz]

pub fn matcher(&self) -> Result<Matcher, Error>

Compiles a Matcher based on the Grammar’s rules.

Errors

If the Grammar contains a “foreign rule” with a named capture, an error may be returned.

pub fn reps(&self, r: usize) -> Grammar

Sets the required number of repetitions of the grammar in the string matched against to exactly r.

This is chiefly useful in conjunction with Pidgin::build_rule.

Examples

let mut p = Pidgin::new();
let g = p.grammar(&vec!["foo", "bar", "baz"]);
p.build_rule("foo", vec![sf("xyzzy "), gf(g.reps(3)), sf(" plugh")]);
let g = p.grammar(&vec!["foo"]);
let m = g.matcher()?;
assert!(m.is_match("xyzzy foobarbaz plugh"));
assert!(!m.is_match("xyzzy foo plugh"));
assert!(!m.is_match("xyzzy foobarbazfoo plugh"));

pub fn reps_min(&self, r: usize) -> Result<Grammar, String>

Sets the minimum required number of repetitions of the grammar in the string matched against to r. If no maximum is set, this will be equivalent to the regex repetition suffix {r,} – there will be no upper limit.

If you set the lower limit to 0 and set no upper limit, this will be equivalent to the regex repetition suffix *. Likewise, 1 and no upper limit will be equivalent to +.

This is chiefly useful in conjunction with Pidgin::build_rule.

Examples

let mut p = Pidgin::new();
let g = p.grammar(&vec!["foo", "bar", "baz"]);
p.build_rule("foo", vec![sf("xyzzy "), gf(g.reps_min(3)?), sf(" plugh")]);
let m = p.matcher()?;
assert!(m.is_match("xyzzy foobarbaz plugh"));
assert!(m.is_match("xyzzy foobarbazfoo plugh"));
assert!(!m.is_match("xyzzy foobar plugh"));

Errors

If an upper limit has been set and it is lower than the minimum, an error will be returned

pub fn reps_max(&self, r: usize) -> Result<Grammar, String>

Sets the maximum number of repetitions of the grammar in the string matched against to r. If no minimum is set, this will be equivalent to the regex repetition suffix {0,r} – there will be no lower limit.

This is chiefly useful in conjunction with Pidgin::build_rule.

Examples

let mut p = Pidgin::new();
let g = p.grammar(&vec!["foo", "bar", "baz"]);
p.build_rule("foo", vec![sf("xyzzy "), gf(g.reps_max(3)?), sf(" plugh")]);
let m = p.matcher()?;
assert!(m.is_match("xyzzy foobarbaz plugh"));
assert!(m.is_match("xyzzy foobar plugh"));
assert!(!m.is_match("xyzzy foobarbazfoo plugh"));

Errors

If an lower limit has been set and it is higher than the maximum, an error will be returned. Also, if the maximum is set to 0 an error will be returned.

pub fn stingy(self, stingy: bool) -> Grammar

Sets whether the grammar’s repetition suffix, if any, has the ? modifier. This has no effect on repetition suffixes created during the ingestion of phrases.

Examples

let mut p = Pidgin::new();
let g = p.grammar(&vec!["foo"]);
p.build_rule("foo", vec![gf(g.reps_min(1)?.stingy(true))]);
let g = p.add_str("foo").compile();
let m = g.matcher()?;
let t = m.parse("foofoo").unwrap();
assert_eq!(t.as_str(), "foo");

pub fn reps_min_max(&self, min: usize, max: usize) -> Result<Grammar, String>

Sets the minimum number of repetitions of the grammar in the string matched against to min and the maximum to max. If no minimum is set, this will be equivalent to the regex repetition suffix {min,max}.

This is chiefly useful in conjunction with Pidgin::build_rule.

Examples

let mut p = Pidgin::new();
let g = p.grammar(&vec!["foo", "bar", "baz"]);
p.build_rule("foo", vec![sf("xyzzy "), gf(g.reps_min_max(1, 3)?), sf(" plugh")]);
let m = p.matcher()?;
assert!(m.is_match("xyzzy foo plugh"));
assert!(m.is_match("xyzzy foobar plugh"));
assert!(m.is_match("xyzzy foobarbaz plugh"));
assert!(!m.is_match("xyzzy  plugh"));
assert!(!m.is_match("xyzzy foobarbazfoo plugh"));

Errors

If the minimum is greater than the maximum or the maximum is 0, an errors will be returned.

pub fn rule(&self, rule: &str) -> Option<Grammar>

Return a copy of one of the rules used by the grammar.

This is chiefly useful when combining grammars generated by the macro.

Examples

#[macro_use] extern crate pidgin;
let library = grammar!{
    books => <cat> | <dog> | <camel>
    cat   => [&vec!["persian", "siamese", "calico", "tabby"]]
    dog   => [&vec!["dachshund", "chihuahua", "corgi", "malamute"]]
    camel => [&vec!["bactrian", "dromedary"]]
};
let g = grammar!{
    seen -> ("I saw a") g(library.rule("cat").unwrap()) (".")
};
let matcher = g.matcher().unwrap();
assert!(matcher.is_match("I saw a calico."));

pub fn describe(&self) -> String

Produces a quasi-BNF representation of the grammar.

This is how pidging::Grammar implements std::fmt::Display, so a grammar’s description is what you get if you feed it to the {} pattern.

Examples

let mut p = Pidgin::new();
let g = p.grammar(&vec!["bar", "baz"]);
p.rule("foo", &g);
p = p.case_insensitive(true);
let g = p.grammar(&vec!["ping", "pang", "pong"]);
p = p.case_insensitive(false);
p.rule("xyzzy", &g);
let g = p.grammar(&vec!["xyzzy", "qux"]);
p.rule("plugh", &g);
let g = p.grammar(&vec!["foo", "plugh"]);
println!("{}", g.describe());
//   TOP :=      {foo}|{plugh}
//   foo :=      ba[rz]
// plugh :=      qux|{xyzzy}
// xyzzy := (?i) p[aio]ng
println!("{}", g);
//   TOP :=      {foo}|{plugh}
//   foo :=      ba[rz]
// plugh :=      qux|{xyzzy}
// xyzzy := (?i) p[aio]ng

pub fn rx(&self) -> Result<Regex, Error>

Generates a non-capturing regex matching what the grammar matches.

Examples

let g = grammar!{
    foo -> r(r"\A") <bar> r(r"\z")
    bar => (?i) [&vec!["cat", "camel", "corn"]]
};
let rx = g.rx()?.to_string();
assert_eq!(r"\A(?i:\s*c(?:orn|a(?:t|mel)))\s*\z", rx);

let g = grammar!{
    sentence    -> <capitalized_word> <other_words>? <terminal_punctuation>
    other_words -> <other_word>+
    other_word  -> <non_terminal_punctuation>? <word>
    capitalized_word         => r(r"\b[A-Z]\w*\b")
    word                     => r(r"\b\w+\b")
    terminal_punctuation     => r(r"[.?!]")
    non_terminal_punctuation => r("(?:--?|[,;'\"])")
};
let rx = g.rule("word").unwrap().rx().unwrap();
let p = g
    .matcher()?
    .parse("John, don't forget to pick up chips.")
    .unwrap();
let other_words = p.name("other_words").unwrap().as_str();
let other_words = rx
    .find_iter(other_words)
    .map(|m| m.as_str())
    .collect::<Vec<_>>();
assert_eq!(
    vec!["don", "t", "forget", "to", "pick", "up", "chips"],
    other_words
);

pub fn to_string(&self) -> String

Returns a quasi-regex representation of the grammar. This is intended mostly for debugging. Rules will be identifiable by named groups, but group names may repeat, in which case the stringification cannot be compiled into a regular expression.

Trait Implementations

impl Clone for Grammar

fn clone(&self) -> Grammar

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Grammar

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Grammar

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Ord for Grammar

fn cmp(&self, other: &Grammar) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere
    Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere
    Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere
    Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl PartialEq<Grammar> for Grammar

fn eq(&self, other: &Grammar) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<Grammar> for Grammar

fn partial_cmp(&self, other: &Grammar) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Eq for Grammar