Generation rules

As was explained in the syntax specifications, generation rules, also called "templates", make up the contents of a unit description. We explain here what they are and how to use them.

Definition of a generation rule

A generation rule is a rule that is part of a unit declaration. It is parsed by the parser and used by the generator to generate a string (or a set of strings).

A generation rule is actually a sequence of a positive number of rule contents or sub-rules. A sub-rule can be seen as a smaller rule that is able to generate a string (or a set of strings) as well.

Generating a string from a rule simply corresponds to using each of its sub-rule to generate a string, and joining the resulting strings together. There are different types of sub-rules, which are described in the following sections.

Words

They are the simplest sub-rules there exist: the only thing they are able to generate is the word they represent.

To put a word inside a rule, simply write it, separated from other sub-rules by whitespaces or special characters. If you want to use special characters, you will need to escape them using a backslash \ (e.g. use \; instead of ;). A sequence of words will thus generate the same sequence.

For example, the rule hello will generate the string hello, while the rule I'm back, made of 2 words (I'm and back), will generate I'm back.

Word groups

This kind of sub-rule simply allows to put words together. If no modifiers change the behavior of a word group, the generated string will be the same as the words that are in the word group.

A word group in a rule is simply denoted using square brackets [ and ] around the words that make up the group. For example, the sub-rule [This is a word group] will generate the string This is a word group; the rule [word group] word [other word group] will generate the string word group word other word group.

Obviously, word groups are not useful unless we use modifiers to change their generation behavior. Modifiers are described here.

Unit references

This type of sub-rule represents a "call" to a unit defined somewhere else in the template file(s). This "call" asks the unit to generate some string of characters.

A unit definition is made of a declaration, which contains the unit's type and name, and a list of rules. When asking a unit to generate a string, it simply chooses one of those rules and generates a string from this. This is the string that is generated by the unit.

In order to reference a unit within a rule, you will want to write the special character that corresponds to the type of the unit you're referencing (either %, @ or ~), followed by the unit's name surrounded by brackets [ and ].

For example, if we defined the following unit:

~[chatbot]
   chatbot
   chatterbot
   bot

the sub-rule ~[chatbot] will generate either chatbot, chatterbot or bot; the rule Are you a ~[chatbot]? will generate one of the following strings: Are you a chatbot?, Are you a chatterbot? or Are you a bot? (Note that for this last rule, ? is actually considered a word since it is not part of unit reference.)

Choices

The last type of sub-rule is choice. A choice is a set of sub-rules which will choose one and only one of them to generate upon generation.

A choice is denoted with curly braces { and } enclosing the whole choice, each of its sub-rules being separated by slashes /.

For example, {hello/Hi} would generate either hello or Hi at random; the rule This is a {nice ~[chatbot]/great thing/cool program} would generate either This is a nice chatbot, This is a nice chatterbot, This is a nice bot, This is a great thing or This is a cool program.

Note that the following unit definitions are similar (they would generate the same strings):

~[greetings]
  Hello world
  Hi world

and

~[greetings]
  {Hello/Hi} world

As you can see, choices don't need to be used to get a certain result. They are however very useful to prevent your template files from growing too large. An obvious disadvantage is readability.