Syntax specifications

Overview

The Domain Specific Language (DSL) used to make templates within Chatette is heavily influenced by the DSL of the prior close project Chatito. Specifically, it is very close to Chatito 2.1.x's DSL, when its target is Rasa NLU.

The current aim of the project is to stay as interoperable as possible with Chatito: Chatette's DSL should stay a "superset" of Chatito's. In other words, a template file intended for Chatito should be usable seemlessly with Chatette (not the other way around).

We will here describe the DSL used with Chatette. If you need the specifications for the DSL used with versions prior to Chatette 1.3.1, please refer to this file. If you need to know about Chatito's DSL, you can find its syntax specifications on its repository.

Structure of a template file

The templates that are used as inputs for Chatette are always text files. We will refer to them as "template files". Even though the template files you can find in the examples all have the extension .chatette, no extension is required.

Those files will first be parsed (i.e. read and "understood" by the parser), then the parsed data will be used to generate examples.

A template file is made up of lines of text. Each line of the file can be one of 4 types:

1. Empty lines and comments

   Empty lines are lines that contain no characters or only whitespaces. Comment lines begin with a double slash //, possibly preceded by any number of whitespace characters (spaces and/or tabs).

   Those lines are ignored by the parser. Note that a comment can also be put at the end of another line. This doesn't make the line a comment line, simply the part following the double slash will be ignored by the parser.

   There also exist a deprecated way to make comments, using a semi-colon ;. This shouldn't be used anymore but will still work anyway and print a warning on the standard output. If you want to use a semi-colon in your templates (and not a comment), use \; instead of ;.

2. Unit declaration opener

   Those lines are not indented and mark the start of a unit. They start with a special character, depending on the type of unit that is being declared. Those special characters are %, @ and ~. This special character is then directly followed by a set of unicode characters surrounded by opening and closing square brackets ([ and ]). This can in turn sometimes be followed by a text surrounded by parentheses.

   We explain in the next subsection what units are and which different unit exist.

3. Unit declaration content

   They are the content of a unit declaration. One declaration can have several lines of content. The indentation of those lines must be coherent. In other words, for a declaration to be valid, all its contents must be indented in the same way. Different indentations can be used for different declarations, even though this is not advised for clarity purposes.

   Each line defines a generation rule for the current unit being declaration. These rules will also be referred to as templates.

4. Inclusion of another file

   Those lines tell the parser to include another file at this place. They begin with a pipe symbol | (no indentation allowed), followed by the path for the file. The path is relative to the template file that is currently being parsed.

A template file will thus have a structure that is akin to the following one:

// comment
%[DECLARATION](something)
    RULE1
@[DECLARATION]
  RULE1 //comment
  RULE2

~[DECLARATION]
    RULE1
    RULE2//comment

We describe what generation rules (i.e. templates) are and how to use them on this page.

The different existing units are described on this page.

Generation modifiers used with units and groups are described here.