Tree Notation is a notation for human & machine friendly languages that are as simple as possible. Simplicity is measured by the count of the pieces: the fewer pieces to build a language the better. We call languages that use Tree Notation Tree Languages.

A Tree Notation program is a string, a tree, and a spreadsheet all at the same time. You will often work treat your program as all 3, sometimes concurrently.

Grammar is a Tree Language for building other Tree Languages. This tutorial walks you through building a very simple language in Grammar.

Grammar has one main concepts: Parsers. Parsers take a line(s) and handle it according to the definitions you write in your Grammar program. A language is simple a combination of Parsers.

Before you start:

Know where to get help. GitHub issues, Tree Notation subreddit, Google Groups, or email Breck.

Take a look at some of the sample languages in the Tree Language Designer. You might be able to use these as a reference if you get stuck.

Open the Tree Language Designer or use your own editor (note: only SublimeText4 currently has partial syntax highlighting for Grammar Languages).

Step 1

Name your language. For now, it is recommended that your language name be lowercase, only letters between A-Z, and not a common reserved word like "while/if/true/etc". You are free to name it anything you want, but if you do we ask that you report any bugs you encounter.

Step 2

If you are using the Tree Language Designer, clear the boxes to create a new language from scratch. If you are using your own editor, create a new file with the name {yourLanguageNameGoesHere}.grammar

Step 3

Create your first Parser. This will be the root parser for your language. It should like this:

{yourLanguageNameGoesHere}Parser
 root

Step 4

Add a description line to your new Parser. This should describe what the purpose of your language is:

{yourLanguageNameGoesHere}Parser
 root
 description {thisIsALangageToHelpYouDoX}

Step 5

Add another Parser to your language. In this example, we'll make a simple language that allows to store your friend's birthdays. Let's add a "friend" Parser. We add a line to the friendParser cruxFromId. Most Tree Languages are keyword based. Because the word keyword is currently a reserved language in many programming languages, we currently use the word crux to refer to the same concept. The line cruxFromId instructs the GrammarParser to extract the keyword from the id—friendParser. Ideally this will be cleaned up in a future version of Grammar.

birthdaysParser
 root
 description A language for storing your friend's birthdays.
friendParser
 description Store information about a friend.
 cruxFromId

Step 6

Now let's add an inScope line to the root Parser so that the friend Parser is in scope:

birthdaysParser
 root
 description A language for storing your friend's birthdays.
 inScope friendParser
friendParser
 description Store information about a friend.
 cruxFromId

Step 7

Now the following is a valid program in your language:

friend
friend
friend

Step 8

Now let's add a nameParser under the friendParser's scope. [Code already covered in this tutorial will be represented with "..."]

...
friendParser
 description Store information about a friend.
 cruxFromId
 inScope nameParser
nameParser

Step 9

Now the following is a valid program in your language:

friend
 name
friend
 name
...

Step 10

A second minor concept in Grammar are cell types. A Tree Notation document has lines and cells. Whereas Parsers parse the lines, CellTypes are responsible for individual words on a line. Cell Types give us type checking, syntax highlighting, and autocomplete. By the current convention, we put the CellTypes at the top of our grammar file.

nameCell
 highlightScope string
...

Step 11

Now let's make nameParser accept a "catch all" Cell Type of the nameCell.

...
nameParser
 catchAllCellType nameCell

Step 12

Now the following is a valid program in your language:

friend
 name Ben Franklin
friend
 name Ada Lovelace

Step 13

Now let's add an error Parser and link it to the Parser to catch errors:

birthdaysParser
 root
 description A language for storing your friend's birthdays.
 inScope friendParser
 catchAllParser errorParser
errorParser
 baseParser errorParser

Now you should get an error for a program like this:

frieeeend
 name Ben Franklin

Step 14

That's all for now! Let us know what you need to do next. Of course, we haven't really gotten to the fun stuff yet. Languages get really interesting once you start implementing the "interesting methods", like compile, execute, render, and format.

Tutorial: create a new Tree Language using Grammar

Key Concepts

Before you start:

Step 1

Step 2

Step 3

Step 4

Step 5

Step 6

Step 7

Step 8

Step 9

Step 10

Step 11

Step 12

Step 13

Step 14