Struct Grammar

Source

pub struct Grammar { /* private fields */ }

Expand description

Represents a single, complete tracery grammar.

See the crate-level documentation for a usage overview.

Implementations§

Source §

impl Grammar

Source

pub fn from_json<S: AsRef<str>>(s: S) -> Result<Grammar>

Creates a new grammar from a JSON grammar string

§Examples

use tracery::Grammar;
let json = r##"{
    "origin": [ "#tool# is #description#!" ],
    "tool": [ "tracery" ],
    "description": [ "fun", "awesome" ]
}"##;
let g = Grammar::from_json(json)?;

Source

pub fn with_default_rule<S: Into<String>>(self, s: S) -> Grammar

Sets a default rule, then returns the modified Grammar

§Examples

use tracery::grammar;
let g = grammar! {
    "start" => "#tool# is #description#!",
    "tool" => "tracery",
    "description" => [ "fun", "awesome" ]
}?.with_default_rule("start");

Source

pub fn set_default_rule<S: Into<String>>(&mut self, s: S)

Sets a default rule

§Examples

use tracery::grammar;
let mut g = grammar! {
    "start" => "#tool# is #description#!",
    "tool" => "tracery",
    "description" => [ "fun", "awesome" ]
}?;
g.set_default_rule("start");

Source

pub fn flatten<R: ?Sized + Rng>(&self, rng: &mut R) -> Result<String>

Attempts to use the Grammar to produce an output String.

This method clones the Grammar, so any changes made in the course of producing an output string (such as pushing a new rule onto a stack using a labeled action such as [foo:bar]) will be discarded after the output is produced.

If you wish to preserve changes use execute

§Examples

use tracery::grammar;
let g = grammar! {
    "origin" => "#tool# is #description#!",
    "tool" => "tracery",
    "description" => [ "fun", "awesome" ]
}?;

// Generate output (either "tracery is fun!" or "tracery is awesome!")
let output = g.flatten(&mut rand::thread_rng())?;

Source

pub fn execute<R>(&mut self, key: &String, rng: &mut R) -> Result<String>
where R: ?Sized + Rng,

Attempts to use the Grammar to produce an output String, preserving any side effects that occur while doing so.

This method produces an output string, but preserves any changes made to the Grammar in the course of doing so. For instance, if a labeled action such as [foo:bar] is executed, then the Grammar will maintain that rule after this method returns.

If you wish to produce an output String without preserving changes, use flatten.

use tracery::grammar;
let mut g = grammar! {
    "origin" => "#tool# is #description#!",
    "tool" => "tracery",
    "description" => [ "fun", "awesome" ]
}?;

// Generate output (either "tracery is fun!" or "tracery is awesome!")
let key = String::from("origin");
let output = g.execute(&key, &mut rand::thread_rng())?;

Using a key created during a previous execution:

use tracery::grammar;
// This time, origin has a side-effect: it creates the rule 'aside'
let mut g = grammar! {
    "origin" => "#[aside:Rust is, too]tool# is #description#!",
    "tool" => "tracery",
    "description" => [ "fun", "awesome" ]
}?;

// Generate output (either "tracery is fun!" or "tracery is awesome!")
let key = String::from("origin");
let output = g.execute(&key, &mut rand::thread_rng())?;

// The previous call to execute created the 'aside' rule
let key = String::from("aside");
// Generates the string "Rust is, too"
let output = g.execute(&key, &mut rand::thread_rng())?;

Source

pub fn from_map<I, K, C, S>(iter: I) -> Result<Self>
where I: IntoIterator<Item = (K, C)>, K: Into<String>, C: IntoIterator<Item = S>, S: Into<String>,

Creates a new Grammar from an input map of keys to rule lists

§Examples

let map = hashmap! {
    "origin" => vec![ "#tool# is #description#!" ],
    "tool" => vec![ "tracery" ],
    "description" => vec![ "fun", "awesome" ]
};
let g = tracery::from_map(map)?;

Any object implementing IntoIterator<Item = (Into<String>, Into<Vec<Into<String>>>)> will be accepted by this function, despite its name:

let map = vec![ ("origin", vec![ "#tool# is #description#!" ]),
                ("tool", vec![ "tracery" ]),
                ("description", vec![ "fun", "awesome" ]) ];
let g = tracery::from_map(map)?;