Struct tracery::Grammar

pub struct Grammar { /* fields omitted */ }

Represents a single, complete tracery grammar.

See the crate-level documentation for a usage overview.

Implementations

impl Grammar

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)?;

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");

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");

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())?;

pub fn execute<R: ?Sized>(
    &mut self,
    key: &String,
    rng: &mut R
) -> Result<String> where
    R: 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())?;

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)?;

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.