Crate tracery [−] [src]

Rust port of tracery

This library is a port of https://github.com/galaxykate/tracery, which implements Generative grammars. Given a set of rules, written in a specific syntax, it will generate strings of text.

Example:

let source = r##"
{
    "origin": ["foo #bar#", "#baz# quux #quuux#"],
    "bar": ["bar", "BAR"],
    "baz": ["baz", "BaZ", "bAAZ"],
    "quuux": ["quick brown fox", "lazy dog"]
}
"##;

let grammar = tracery::from_json(source).unwrap();
println!(grammar.flatten()) // => starting from the "origin" rule (which is selected by
                            //    default), fills in random
                            //    entries from the "bar", "baz", and "quuux" rules,
                            //    where called for in the "origin" text.

or, even shorter:

let source = r##"
{
    "origin": ["foo #bar#", "#baz# quux #quuux#"],
    "bar": ["bar", "BAR"],
    "baz": ["baz", "BaZ", "bAAZ"],
    "quuux": ["quick brown fox", "lazy dog"]
}"##;
tracery::flatten(source).unwrap();

So, in the example above, we might end up with "foo bar" or "BaZ quux lazy dog", etc

API

In the example above, we used Grammar.flatten, but that is a convenience function that does the following:

let grammar = tracery::from_json(source).unwrap();
let flattened = grammar.flatten();

.from_json will parse the rule set out into a tree-like structure, and .flatten collapses that tree-like structure into a single string.

More tracery syntax

Tracery allows for more than just word replacement. You can attach "actions" and "modifiers" to rules as well. There are quite a few modifiers built-in to this library. Here is one:

let source = r##"
{
    "origin": ["this word is in plural form: #noun.s#"],
    "noun": ["apple", "bear", "cat", "dog", "equine", "fish", "garbage"]
}"##;

let grammar = tracery::from_json(source).unwrap();
println!(grammar.flatten());

This will generate sentences like:

"this word is in plural form: bears"

or

"this word is in plural form: fishes"

etc...

Actions allow you to, for example, lock in a specific value for a #tag#, so that you can refer to it multiple times in your story. Here is an example (modified from @galaxykate's official tutorial http://www.crystalcodepalace.com/traceryTut.html)

let source = r##"{
    "name": ["Arjun","Yuuma","Darcy","Mia","Chiaki","Izzi","Azra","Lina"],
    "animal": ["unicorn","raven","sparrow","scorpion","coyote","eagle","owl","lizard","zebra","duck","kitten"],
    "mood": ["vexed","indignant","impassioned","wistful","astute","courteous"],
    "story": ["#hero# traveled with her pet #heroPet#.  #hero# was never #mood#, for the #heroPet# was always too #mood#."],
    "origin": ["#[hero:#name#][heroPet:#animal#]story#"]
}"##;

We see, in the "origin" rule, the use of actions to lock-in the value of #hero# and #heroPet#, so that we can use those tags in the "story" rule, and know that the same generated value will be used in all cases.

Structs

Grammar

Represents a single grammar

Enums

Error

Traits

Flatten

Functions

flatten
from_json

Type Definitions

Result