2 files changed, 47 insertions(+), 0 deletions(-)

M doc/goals.md
A doc/grammar.ebnf

@@ 14,6 14,8 @@
   - in particular, record position of rule/match pattern in the original grammar so an error can say "failed to match at line L col C rule R, expected one of RULES|LITERALS, got ..."
 * Stats - branches launched, rules executed, etc.
 
+At start, generate a map of all rules and expressions, assigning an incrementing int for each with location, parent rule, literal value in the grammar, so that great error messages can be generated. Each matcher knows it is executing for a certain grammar atom, and if it fails (and that failure is maintained as farthest position, then we can give good informative message where that happened (e.g. in rule "class_def", expected literal "class", got "async" at line 8 column 3 of input).
+
 ## Stretch goals
 
 * Location-aware parse - ability to parse from a specific location, using state from a previous parse for what came before (useful for e.g. editors) - might not be required if whole-file parsing is fast enough

@@ 0,0 1,45 @@
+# Notation follows the Go-style EBNF notation [0], except that non-terminal
+# productions are all lowercase, while terminal productions are all
+# uppercase.
+#
+# [0]: https://golang.org/ref/spec#Notation
+
+grammar    = definition { definition } .
+definition = identifier ARROW expression [ EOS ] .
+expression = sequence { SEPARATOR sequence } .
+sequence   = label { label } .
+label      = [ identifier COLON ] prefix .
+prefix     = AND coderef
+           | DOLLAR coderef
+           | AT coderef
+           | [ AND | NOT ] suffix
+           .
+suffix     = primary [ QUESTION | STAR | PLUS ] .
+primary    = identifier
+           | LPAREN expression RPAREN
+           | literal
+           | class
+           | DOT
+           .
+coderef    = LBRACE identifier RBRACE .
+
+# For reference, the terminal productions are loosely defined here.
+# They are handled by the scanner.
+
+ARROW     = '<-' | '←' | '⟵' | '=' .
+EOS       = ';' .                    # EOS stands for "end of statement".
+SEPARATOR = '|' | '/' .
+COLON     = ':' .
+AND       = '&' .
+DOLLAR    = '$' .
+AT        = '@' .
+NOT       = '!' .
+QUESTION  = '?' .
+STAR      = '*' .
+PLUS      = '+' .
+LPAREN    = '(' .
+RPAREN    = ')' .
+DOT       = '.' .
+LBRACE    = '{' .
+RBRACE    = '}' .
+