Key Concepts

Particle Syntax (Particles) is a syntax 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.

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

Parsers is a language built on top of Particles for building other languages. This tutorial walks you through building a very simple language in Parsers.

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

Before you start:

Know where to get help. GitHub issues, WWS subreddit, or email Breck.

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

Open the Parser Designer or use your own editor (note: only SublimeText4 currently has partial syntax highlighting for Parsers).

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 atom 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 Parser 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}.parsers

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 Languages are keyword based. Because the atom keyword is currently a reserved language in many programming languages, we currently use the atom crux to refer to the same concept. The line cruxFromId instructs the Parser to extract the keyword from the id—friendParser. Ideally this will be cleaned up in a future version of Parsers.

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 Parsers are atom types. A Particles document has lines and atoms. Whereas Parsers parse the lines, AtomTypes are responsible for individual atoms on a line. Atom Types give us type checking, syntax highlighting, and autocomplete. By the current convention, we put the AtomTypes at the top of our parsers file.

nameAtom
 paint string
...

Step 11

Now let's make nameParser accept a "catch all" Atom Type of the nameAtom.

...
nameParser
 catchAllAtomType nameAtom

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.

Parsers Tutorial

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