Advanced: Working with Tracery

Tracery Links to an external site. is a “story-grammar generation library” written in JavaScript. It was created by Kate Compton Links to an external site. and has risen in popularity for its easy-to-follow functions for taking a set of options and creating a grammar that can produce different texts.

(This page uses the NodeJS Links to an external site. version of tracery called "tracery-grammar Links to an external site." for its examples.)

Example

Run it a few times without changing anything yet. 

Definitions

While Tracery may seem complicated at first, it works on two things: symbols and rules.

Symbols

Think of symbols as possible outcomes. These can be words, numbers, or phrases. They are simply possible output.

Rules

Rules are just that: rules. The rules define how the symbols relate to each other.

Symbols + Rules = Grammar

In Tracery, symbols are given to it through the createGrammar() function. They define what the symbols are and possible values for those symbols to create a grammar.

Then, with the rules and symbols, the grammar is flattened into one possible outcome through filtering the symbols, their possibilities, and the rules.

Grammars

A grammar is a set of symbols and some rules to follow. When using Tracery, these are feed to the createGrammar() function to tell it what symbols to use and their possible options.

Symbols

In Tracery, symbols and their choices are defined as an object literal. Each property within the object is an array where the property is the symbol name and the array is all of its possible choices.

createGrammar()

These symbols are passed to the createGrammar() function as part of the Tracery object. This takes the properties of the object passed to it to create associations where the property names can be substituted for one of their possible values in the next step.

The createGrammar() function also returns a grammar object that can be feed some text with certain values to substitute for the property names of the object passed to it.

flatten()

The flatten() function of the object returned by createGrammar() has a function, flatten(), that “flattens” all of the possible choices for each symbol into one randomly chosen from its choices.

This function returns a text representing any textual substitutions made based on what was passed to it. For any symbols wrapped in hashes (#animals# in this example) it is switched for one of its choices.

Try it 

You can try adding new symbols and/or changing the rules. 

And More Grammars!

Through adding more symbols, more complicated output can be achieved. Beyond using #animals#, a second symbol, #locations# could be added.

Adding new symbols with new rules does not change the basic output of the example. However, Tracery also understands symbols within symbols.

Complex rules can be created that will take symbols and expand them based on other, existing symbols.