Grammar railroad diagram

[mingodad]

Looking through the code I think that adding an option to export the grammar to a format that can be recognized by https://www.bottlecaps.de/rr/ui to generate a navigable railroad diagram (https://en.wikipedia.org/wiki/Syntax_diagram) would make it easier to develop/debug/document jessica.

For example I manually created a grammar compatible with chpeg / cpp-peglib that can parse pegquasi grammars on their playgrounds (https://chrishixon.github.io/chpeg/playground/ , https://yhirose.github.io/cpp-peglib/) :

# Hierarchical syntax

Grammar      <- _Spacing Definition+ _EndOfFile

Definition   <- Identifier LEFTARROW Expression SEMI #&${ACCEPT}

Expression   <- Sequence ( _SLASH Sequence )*

Sequence     <- Prefix* HOLE?

Prefix       <- AND HOLE
              / AND Suffix
              / NOT Suffix
              /     Suffix

Suffix       <- Primary (STARSTAR / PLUSPLUS) Primary
              / Primary (QUESTION
                        / STAR
                        / PLUS)
              / Primary

Primary      <- Super
              / Identifier !LEFTARROW
              / OPEN Expression CLOSE
              / Literal
              / Class
              / DOT
              / BEGIN
              / END


Super        <- 'super.' Identifier

# Lexical syntax

Identifier   <- < IdentStart IdentCont* > _Spacing
IdentStart   <- [a-zA-Z_]
IdentCont    <- IdentStart / [0-9]
Literal      <- ['] < (!['] Char )* > ['] _Spacing
              / ["] < (!["] Char )* > ["] _Spacing
Class        <- '[' < (!']' Range)* > ']' _Spacing
Range        <- Char '-' Char / Char
Char         <- '\\' [abefnrtv'"\[\]\\`$]
              / '\\x' [0-9a-fA-F][0-9a-fA-F]
              / '\\' '-'
              / !'\\' .
LEFTARROW    <- '<-' _Spacing
_SLASH        <- '/' _Spacing              #${_ => SKIP};
SEMI         <- ';' _Spacing
AND          <- '&' _Spacing
NOT          <- '~' _Spacing
QUESTION     <- '?' _Spacing
STAR         <- '*' _Spacing
PLUS         <- '+' _Spacing
OPEN         <- '(' _Spacing
CLOSE        <- ')' _Spacing
DOT          <- '.' _Spacing
#_Spacing {I}     <- (Space / Comment)*        # this line is for chpeg
~_Spacing {I}     <- (Space / Comment)*        # this line is for cpp-peglib
Comment      <- '#' (!EndOfLine .)* EndOfLine
Space        <- ' ' / '\t' / EndOfLine
EndOfLine    <- '\r\n' / '\n' / '\r'
_EndOfFile    <- !.

HOLE_LITERAL <- Literal / [`] < (![`] Char )* > [`] _Spacing
HOLE         <- "${" (!'}' ( HOLE_LITERAL / .))* "}" _Spacing
BEGIN        <- '<' _Spacing
END          <- '>' _Spacing
PLUSPLUS     <- '++' _Spacing
STARSTAR     <- '**' _Spacing

And with a variant of that I could do a basic conversion of jessica to a peg format that can be used at https://www.bottlecaps.de/convert/ to be converted and generate a navigable railroad diagram.

Copy and paste the grammar shown bellow on https://www.bottlecaps.de/convert/ on the Input grammar: textarea and then click the Convert button then click the View Diagram button (that will appear after the conversion) to view the navigable railroad diagram.

 start  <-
	 _WS  moduleBody  _EOF 

 LATER  <-
	 "~."  ! [0-9] _WS 

 RESERVED_WORD  <-
	 "super."  RESERVED_WORD 
	/  (  "insulate"  _WSN  ) 

 primaryExpr  <-
	 "super."  primaryExpr 
	/  functionExpr 

 propDef  <-
	 methodDef 
	/  "super."  propDef 

 purePropDef  <-
	 methodDef 
	/  "super."  purePropDef 

 prePre  <-
	 (  PLUSPLUS  /  MINUSMINUS  ) 
	/  "super."  prePre 

 memberPostOp  <-
	 "super."  memberPostOp 
	/  LEFT_BRACKET  assignExpr  RIGHT_BRACKET 
	/  LATER  LEFT_BRACKET  assignExpr  RIGHT_BRACKET 
	/  LATER  IDENT_NAME 

 callPostOp  <-
	 "super."  callPostOp 
	/  LATER  args 

 postOp  <-
	 (  PLUSPLUS  /  MINUSMINUS  )  _WS 

 assignExpr  <-
	 arrowFunc 
	/  functionExpr 
	/  lValue  postOp 
	/  lValue  (  EQUALS  /  assignOp  )  assignExpr 
	/  "super."  assignExpr 
	/  primaryExpr 

 pureExpr  <-
	 arrowFunc 
	/  "super."  pureExpr 

 lValue  <-
	 primaryExpr  LEFT_BRACKET  indexExpr  RIGHT_BRACKET 
	/  primaryExpr  LATER  LEFT_BRACKET  indexExpr  RIGHT_BRACKET 
	/  primaryExpr  DOT  IDENT_NAME 
	/  primaryExpr  LATER  IDENT_NAME 
	/  useVar 

 assignOp  <-
	 (  "*="  /  "/="  /  "%="  /  "+="  /  "-="  /  "<<="  /  ">>="  /  ">>>="  /  "&="  /  "^="  /  "|="  /  "**="  )  _WS 

 statement  <-
	 block 
	/  IF  LEFT_PAREN  expr  RIGHT_PAREN  arm  ELSE  elseArm 
	/  IF  LEFT_PAREN  expr  RIGHT_PAREN  arm 
	/  breakableStatement 
	/  terminator 
	/  IDENT  COLON  statement 
	/  TRY  block  catcher  finalizer 
	/  TRY  block  catcher 
	/  TRY  block  finalizer 
	/  DEBUGGER  SEMI 
	/  exprStatement 

 arm  <-
	 block 

 elseArm  <-
	 arm 
	/  IF  LEFT_PAREN  expr  RIGHT_PAREN  arm  ELSE  elseArm 
	/  IF  LEFT_PAREN  expr  RIGHT_PAREN  arm 

 breakableStatement  <-
	 FOR  LEFT_PAREN  declOp  forOfBinding  OF  expr  RIGHT_PAREN  arm 
	/  FOR  LEFT_PAREN  declaration  expr  SEMI  expr  RIGHT_PAREN  arm 
	/  WHILE  LEFT_PAREN  expr  RIGHT_PAREN  arm 
	/  SWITCH  LEFT_PAREN  expr  RIGHT_PAREN  LEFT_BRACE  clause  RIGHT_BRACE 

 terminator  <-
	 "continue"  _NO_NEWLINE  IDENT  SEMI 
	/  "continue"  _WS  SEMI 
	/  "break"  _NO_NEWLINE  IDENT  SEMI 
	/  "break"  _WS  SEMI 
	/  "return"  _NO_NEWLINE  expr  SEMI 
	/  "return"  _WS  SEMI 
	/  "throw"  _NO_NEWLINE  expr  SEMI 

 block  <-
	 LEFT_BRACE  body  RIGHT_BRACE 

 body  <-
	 statementItem 

 statementItem  <-
	 declaration 
	/  statement 

 declaration  <-
	 declOp  binding  (  _COMMA  binding  )  *  SEMI 
	/  functionDecl 

 declOp  <-
	 (  "const"  /  "let"  )  _WSN 

 forOfBinding  <-
	 bindingPattern 
	/  defVar 

 binding  <-
	 bindingPattern  EQUALS  assignExpr 
	/  defVar  EQUALS  assignExpr 
	/  defVar 

 bindingPattern  <-
	 LEFT_BRACKET  elementParam  (  _COMMA  elementParam  )  *  RIGHT_BRACKET 
	/  LEFT_BRACE  propParam  (  _COMMA  propParam  )  *  RIGHT_BRACE 

 pattern  <-
	 bindingPattern 
	/  defVar 
	/  undefined 
	/  dataLiteral 
	/  HOLE 

 elementParam  <-
	 param 

 param  <-
	 ELLIPSIS  pattern 
	/  defVar  EQUALS  assignExpr 
	/  pattern 

 propParam  <-
	 ELLIPSIS  pattern 
	/  propName  COLON  pattern 
	/  defVar  EQUALS  assignExpr 
	/  defVar 

 exprStatement  <-
	 !  cantStartExprStatement  expr  SEMI 

 cantStartExprStatement  <-
	 (  "{"  /  "function"  /  "async"  _NO_NEWLINE  "function"  /  "class"  /  "let"  /  "["  )  _WSN 

 terminatedBody  <-
	 (  (  !  terminator  statementItem  )  terminator  ) 

 clause  <-
	 caseLabel  LEFT_BRACE  terminatedBody  RIGHT_BRACE 

 caseLabel  <-
	 CASE  expr  COLON 
	/  DEFAULT  _WS  COLON 

 catcher  <-
	 CATCH  LEFT_PAREN  pattern  RIGHT_PAREN  block 

 finalizer  <-
	 FINALLY  block 

 functionDecl  <-
	 FUNCTION  defVar  LEFT_PAREN  param  (  _COMMA  param  )  *  RIGHT_PAREN  block 

 functionExpr  <-
	 FUNCTION  defVar  LEFT_PAREN  param  (  _COMMA  param  )  *  RIGHT_PAREN  block 

 arrowFunc  <-
	 arrowParams  _NO_NEWLINE  ARROW  block 
	/  arrowParams  _NO_NEWLINE  ARROW  assignExpr 

 arrowParams  <-
	 IDENT 
	/  LEFT_PAREN  param  (  _COMMA  param  )  *  RIGHT_PAREN 

 methodDef  <-
	 method 
	/  GET  propName  LEFT_PAREN  RIGHT_PAREN  block 
	/  SET  propName  LEFT_PAREN  param  RIGHT_PAREN  block 

 method  <-
	 propName  LEFT_PAREN  param  (  _COMMA  param  )  *  RIGHT_PAREN  block 

 moduleBody  <-
	 moduleItem 

 moduleItem  <-
	 SEMI 
	/  importDecl 
	/  exportDecl 
	/  moduleDeclaration 

 useImport  <-
	 IDENT 

 defImport  <-
	 IDENT 

 moduleDeclaration  <-
	 "const"  _WSN  moduleBinding  (  _COMMA  moduleBinding  )  *  SEMI 

 hardenedExpr  <-
	 dataLiteral 
	/  undefined 
	/  "harden"  _WS  LEFT_PAREN  (  pureExpr  /  useImport  )  RIGHT_PAREN 
	/  useVar 

 moduleBinding  <-
	 bindingPattern  EQUALS  hardenedExpr 
	/  defVar  EQUALS  hardenedExpr 
	/  defVar 

 importClause  <-
	 STAR  AS  defImport 
	/  namedImports 
	/  defImport  _COMMA  STAR  AS  defImport 
	/  defImport  _COMMA  namedImports 
	/  defImport 

 safeImportClause  <-
	 safeNamedImports 

 importSpecifier  <-
	 IDENT_NAME  AS  defImport 
	/  defImport 

 safeImportSpecifier  <-
	 IDENT_NAME  AS  defVar 
	/  defVar 

 namedImports  <-
	 LEFT_BRACE  importSpecifier  (  _COMMA  importSpecifier  )  *  _COMMA  RIGHT_BRACE 

 safeNamedImports  <-
	 LEFT_BRACE  safeImportSpecifier  (  _COMMA  safeImportSpecifier  )  *  _COMMA  RIGHT_BRACE 

 safeModule  <-
	 STRING 

 importDecl  <-
	 IMPORT  importClause  FROM  STRING  SEMI 
	/  IMPORT  safeImportClause  FROM  safeModule  SEMI 

 exportDecl  <-
	 EXPORT  DEFAULT  exportableExpr  SEMI 
	/  EXPORT  moduleDeclaration 

 exportableExpr  <-
	 hardenedExpr 

 ARROW  <-
	 "=>"  _WS 

 AS  <-
	 "as"  _WSN 

 DEBUGGER  <-
	 "debugger"  _WSN 

 PLUSPLUS  <-
	 "++"  _WSN 

 MINUSMINUS  <-
	 "--"  _WSN 

 CASE  <-
	 "case"  _WSN 

 IF  <-
	 "if"  _WSN 

 ELSE  <-
	 "else"  _WSN 

 FOR  <-
	 "for"  _WSN 

 OF  <-
	 "of"  _WSN 

 WHILE  <-
	 "while"  _WSN 

 BREAK  <-
	 "break"  _WSN 

 CONTINUE  <-
	 "continue"  _WSN 

 SWITCH  <-
	 "switch"  _WSN 

 TRY  <-
	 "try"  _WSN 

 CATCH  <-
	 "catch"  _WSN 

 FINALLY  <-
	 "finally"  _WSN 

 GET  <-
	 "get"  _WSN 

 SET  <-
	 "set"  _WSN 

 IMPORT  <-
	 "import"  _WSN 

 EXPORT  <-
	 "export"  _WSN 

 FROM  <-
	 "from"  _WSN 

 FUNCTION  <-
	 "function"  _WSN 

 DEFAULT  <-
	 "default"  _WSN 

 EQUALS  <-
	 "="  _WS 

 SEMI  <-
	 ";"  _WS 

 STAR  <-
	 "*"  _WS 

[erights]

@mingodad wow, this looks like great work! What do you think we should add to this repository? Would you be interesting in submitting a PR? I would happily review, thanks!

[mingodad]

Why not add the capability to export the grammar like I did manually directly in the pegquasi itself ?

[erights]

Hi @michaelfig I added you to the assignees along with me. Looks like fun! Let's discuss sometime. No rush.