GRAMMAR.md

Grammar

This file contains an explanation of the rules for highlighting grammar and a guide to adding new grammar for contributors.

---

Do's and Don'ts

1. Not all syntax is to be highlighted.
   We cannot highlight every syntax. RegEx is not the best tool for recognising syntaxes.
   The result becomes counterproductive since the entire text is highlighted, defeating the purpose of using a highlighter.

   

2. Ambiguous elements should not be highlighted.
   E.g. highlighting only the word loop will select different uses of it (loop ... times: and loop-...)
   Instead, each different use should be selected individually.

   

3. Aim for keywords and easily-recognised structures.
   Root-level structures like command /...: are easy to recognise since they have no indentation.
   Section-header keywords like if and while can be identified by the : colon at the end of their line.
   It is better not to highlight a structure than to incorrectly identify it.

   

4. While we do not directly support add-on grammar, please be respectful of it.
   E.g. do not add grammar that will preclude commonly-used add-on syntax.
   This is one of the reasons why we do not highlight all syntax.

---

Recognised Keywords

Section Headers

if <.+>:
else if <.+>:
else:

[(parse if|if)] <.+>:
else [parse] if <.+>:

loop %objects%:
loop %number% times:

[do] while <.+>:

command .+:
function .+:
on .+:

trigger:

options:
variables:
aliases:

The following section headers are currently not supported, as their effect-section style is not compatible with our highlighting rules.

(spawn|summon) %entity types% [%directions% %locations%]:
(spawn|summon) %number% of %entity types% [%directions% %locations%]:

Literals

"string" # text
123 # integer
1.0 # decimal
true false off on yes no # boolean

Structures

# Comment

{variable}
{list variable::*}
{_local variable}
{@option}

event-value
loop-value-x
arg-value-x
arg-x

Ending Words

These will be identified in red (or similar) as important words that either end a trigger or have major cancelling behaviour (e.g. cancel the event.)

cancel ...
stop ...
return ...

Types

player
item [type]
string
number
integer
block
entity

Todo: add remaining types and qualifiers.