Grammar railroad diagram

[Domingo Alvarez Duarte]

Hello !

I just found out about this project and looking around I found that it's 
using flex/bison for the parser and using this tool 
https://www.bottlecaps.de/convert/ and manually adding the tokens from 
pkl-lex.l we have an EBNF accepted by https://www.bottlecaps.de/rr/ui to 
generate a railroad diagram 
(https://en.wikipedia.org/wiki/Syntax_diagram) for the grammar (see 
bellow), copy and paste the EBNF shown bellow on 
https://www.bottlecaps.de/rr/ui in the tab "Edit Grammar" then click the 
tab "View Diagram".

I think that it's useful to give a global view of the grammar, 
documentation, ...

====

/* converted on Thu Dec 23, 2021, 11:47 (UTC+01) by bison-to-w3c v0.54 
which is Copyright (c) 2011-2021 by Gunther Rademacher <grd@gmx.net> */

pushlevel
         ::=
start    ::= ( START_EXP expression | START_DECL declaration ) ','?
           | START_STMT ( stmt | load ) ';'?
           | START_PROGRAM program
program  ::= program_elem*
program_elem
         ::= declaration
           | stmt
           | load
load     ::= LOAD ( IDENTIFIER | STR ) ';'
identifier
         ::= TYPENAME
           | IDENTIFIER
expression_opt
         ::= expression?
expression
         ::= primary
           | ( unary_operator | INC | DEC ) expression
           | ( SIZEOF '(' simple_type_specifier | cons_type_specifier 
'(' expression? ( ',' expression )* opt_comma ) ')'
           | expression ( ATTR | ( '+' | '-' | '*' | '/' | CEILDIV | 
POW | '%' | SL | SR | EQ | NE | '<' | '>' | LE | GE | '|' | '^' | '&' | 
AND | OR | IMPL | IN | '?' expression ':' ) expression | ( AS | ISA ) 
simple_type_specifier | UNIT )
           | typename '{' struct_field? ( ',' struct_field )* opt_comma '}'
           | UNIT
           | OFFSET
           | bconc
           | map
bconc    ::= expression BCONC expression
mapop    ::= '@'
           | NSMAP
map      ::= simple_type_specifier mapop expression ( ':' expression )?
unary_operator
         ::= '-'
           | '+'
           | '~'
           | '!'
           | UNMAP
primary  ::= ( IDENTIFIER | INTEGER | INTEGER_OVERFLOW | CHAR | STR | ( 
'(' ( expression | funcall_stmt ) | FORMAT '(' STR format_arg_list ) ')' 
| array | funcall | LAMBDA function_specifier | expression ( INC | DEC ) 
) ( '.' identifier | '[' ( expression ( RANGEA expression | ':' 
expression? )? | ':' expression? ) ']' )*
funcall  ::= primary '(' funcall_arg? ( ',' funcall_arg )* ')'
funcall_arg
         ::= expression
format_arg_list
         ::= format_arg? ( ',' expression )*
format_arg
         ::= expression
opt_comma
         ::= ','?
struct_field
         ::= ( identifier '=' )? expression
array    ::= '[' array_initializer ( ',' array_initializer )* opt_comma ']'
array_initializer
         ::= ( '.' '[' expression ']' '=' )? expression
pushlevel_args
         ::=
function_specifier
         ::= ( '(' pushlevel_args function_arg ( ',' function_arg )* 
')' simple_type_specifier ':' | simple_type_specifier ':' pushlevel_args 
) comp_stmt
function_arg
         ::= simple_type_specifier identifier function_arg_initial
           | identifier THREEDOTS
function_arg_initial
         ::= ( '=' expression )?
type_specifier
         ::= simple_type_specifier
           | struct_type_specifier
           | function_type_specifier
typename ::= TYPENAME
string_type_specifier
         ::= STRING
simple_type_specifier
         ::= ANY
           | VOID
           | typename
           | integral_type_specifier
           | offset_type_specifier
           | array_type_specifier
           | string_type_specifier
cons_type_specifier
         ::= typename
           | array_type_specifier
           | string_type_specifier
integral_type_specifier
         ::= integral_type_sign INTEGER '>'
integral_type_sign
         ::= INTCONSTR
           | UINTCONSTR
offset_type_specifier
         ::= OFFSETCONSTR simple_type_specifier ',' ( identifier | 
INTEGER ) '>'
array_type_specifier
         ::= simple_type_specifier '[' expression? ']'
function_type_specifier
         ::= '(' ( function_type_arg ( ',' function_type_arg )* )? ')' 
simple_type_specifier
function_type_arg
         ::= simple_type_specifier '?'?
           | THREEDOTS
struct_type_specifier
         ::= pushlevel struct_type_pinned struct_or_union 
integral_struct '{' ( ( struct_type_field | declaration ) ( declaration 
| struct_type_field )* )? '}'
struct_or_union
         ::= STRUCT
           | UNION
struct_type_pinned
         ::= PINNED?
integral_struct
         ::= simple_type_specifier?
endianness
         ::= ( LITTLE | BIG )?
struct_type_field
         ::= endianness type_specifier struct_type_field_identifier 
struct_type_field_constraint_and_init struct_type_field_label 
struct_type_field_optcond ';'
struct_type_field_identifier
         ::= identifier?
struct_type_field_label
         ::= ( '@' expression )?
struct_type_field_constraint_and_init
         ::= ( ( ':' ( expression '=' )? | '=' ( expression ':' )? | EQ 
) expression )?
struct_type_field_optcond
         ::= ( IF expression )?
simple_declaration
         ::= DEFVAR defvar ( ',' defvar )*
           | DEFTYPE deftype ( ',' deftype )*
           | DEFUNIT defunit ( ',' defunit )*
declaration
         ::= defun_or_method identifier '=' function_specifier
           | simple_declaration ';'
defun_or_method
         ::= DEFUN
           | METHOD
defvar   ::= identifier '=' expression
deftype  ::= identifier '=' type_specifier
defunit  ::= identifier '=' expression
comp_stmt
         ::= pushlevel ( '{' ( stmt | declaration )* '}' | builtin )
builtin  ::= BUILTIN_RAND
           | BUILTIN_GET_ENDIAN
           | BUILTIN_SET_ENDIAN
           | BUILTIN_GET_IOS
           | BUILTIN_SET_IOS
           | BUILTIN_OPEN
           | BUILTIN_CLOSE
           | BUILTIN_IOSIZE
           | BUILTIN_IOFLAGS
           | BUILTIN_IOGETB
           | BUILTIN_IOSETB
           | BUILTIN_GETENV
           | BUILTIN_FORGET
           | BUILTIN_GET_TIME
           | BUILTIN_SLEEP
           | BUILTIN_STRACE
           | BUILTIN_TERM_GET_COLOR
           | BUILTIN_TERM_SET_COLOR
           | BUILTIN_TERM_GET_BGCOLOR
           | BUILTIN_TERM_SET_BGCOLOR
           | BUILTIN_TERM_BEGIN_CLASS
           | BUILTIN_TERM_END_CLASS
           | BUILTIN_TERM_BEGIN_HYPERLINK
           | BUILTIN_TERM_END_HYPERLINK
           | BUILTIN_VM_OBASE
           | BUILTIN_VM_SET_OBASE
           | BUILTIN_VM_OACUTOFF
           | BUILTIN_VM_SET_OACUTOFF
           | BUILTIN_VM_ODEPTH
           | BUILTIN_VM_SET_ODEPTH
           | BUILTIN_VM_OINDENT
           | BUILTIN_VM_SET_OINDENT
           | BUILTIN_VM_OMAPS
           | BUILTIN_VM_SET_OMAPS
           | BUILTIN_VM_OMODE
           | BUILTIN_VM_SET_OMODE
           | BUILTIN_VM_OPPRINT
           | BUILTIN_VM_SET_OPPRINT
           | BUILTIN_UNSAFE_STRING_SET
ass_exp_op
         ::= POWA
           | MULA
           | DIVA
           | MODA
           | ADDA
           | SUBA
           | SLA
           | SRA
           | BANDA
           | IORA
           | XORA
simple_stmt_list
         ::= simple_stmt? ( ',' simple_stmt )*
simple_stmt
         ::= ( primary ( '=' | ass_exp_op ) | ( bconc | map ) '=' )? 
expression
           | ( PRINTF '(' STR format_arg_list | ASSERT '(' expression ( 
',' expression )? ) ')'
           | funcall_stmt
stmt     ::= comp_stmt
           | ( simple_stmt | BREAK | CONTINUE | PRINT expression | 
PRINTF STR format_arg_list | ( RETURN | RAISE ) expression? )? ';'
           | ( IF '(' expression ')' ( stmt ELSE )? | ( WHILE '(' 
expression | FOR '(' ( ( pushlevel simple_declaration )? ';' 
expression_opt ';' simple_stmt_list | IDENTIFIER IN expression pushlevel 
( WHERE expression )? ) ) ')' ) stmt
           | TRY stmt ( CATCH ( IF expression | '(' pushlevel 
function_arg ')' )? comp_stmt | UNTIL expression ';' )
funcall_stmt
         ::= primary funcall_stmt_arg+
funcall_stmt_arg
         ::= ':' IDENTIFIER expression

//Tokens
//\("[^"]+"\)\s+{ return \(\S[^;]+\).+
PINNED ::= "pinned"
STRUCT ::= "struct"
UNION ::= "union"
ELSE ::= "else"
WHILE ::= "while"
UNTIL ::= "until"
FOR ::= "for"
IN ::= "in"
WHERE ::= "where"
IF ::= "if"
SIZEOF ::= "sizeof"
DEFUN ::= "fun"
METHOD ::= "method"
DEFTYPE ::= "type"
DEFVAR ::= "var"
DEFUNIT ::= "unit"
BREAK ::= "break"
CONTINUE ::= "continue"
RETURN ::= "return"
STRING ::= "string"
AS ::= "as"
TRY ::= "try"
CATCH ::= "catch"
RAISE ::= "raise"
VOID ::= "void"
ANY ::= "any"
PRINT ::= "print"
PRINTF ::= "printf"
ISA ::= "isa"
UNMAP ::= "unmap"
BIG ::= "big"
LITTLE ::= "little"
LOAD ::= "load"
LAMBDA ::= "lambda"
ASSERT ::= "assert"
FORMAT ::= "format"

//\("[^"]+"\)\s+.+? return \(\S[^;]+\).+
BUILTIN_RAND ::= "__PKL_BUILTIN_RAND__"
BUILTIN_GET_ENDIAN ::= "__PKL_BUILTIN_GET_ENDIAN__"
BUILTIN_SET_ENDIAN ::= "__PKL_BUILTIN_SET_ENDIAN__"
BUILTIN_GET_IOS ::= "__PKL_BUILTIN_GET_IOS__"
BUILTIN_SET_IOS ::= "__PKL_BUILTIN_SET_IOS__"
BUILTIN_OPEN ::= "__PKL_BUILTIN_OPEN__"
BUILTIN_CLOSE ::= "__PKL_BUILTIN_CLOSE__"
BUILTIN_IOSIZE ::= "__PKL_BUILTIN_IOSIZE__"
BUILTIN_IOFLAGS ::= "__PKL_BUILTIN_IOFLAGS__"
BUILTIN_IOGETB ::= "__PKL_BUILTIN_IOGETB__"
BUILTIN_IOSETB ::= "__PKL_BUILTIN_IOSETB__"
BUILTIN_GETENV ::= "__PKL_BUILTIN_GETENV__"
BUILTIN_FORGET ::= "__PKL_BUILTIN_FORGET__"
BUILTIN_GET_TIME ::= "__PKL_BUILTIN_GET_TIME__"
BUILTIN_SLEEP ::= "__PKL_BUILTIN_SLEEP__"
BUILTIN_STRACE ::= "__PKL_BUILTIN_STRACE__"
BUILTIN_TERM_BEGIN_HYPERLINK ::= "__PKL_BUILTIN_TERM_BEGIN_HYPERLINK__"
BUILTIN_TERM_END_HYPERLINK ::= "__PKL_BUILTIN_TERM_END_HYPERLINK__"
BUILTIN_TERM_BEGIN_CLASS ::= "__PKL_BUILTIN_TERM_BEGIN_CLASS__"
BUILTIN_TERM_END_CLASS ::= "__PKL_BUILTIN_TERM_END_CLASS__"
BUILTIN_TERM_GET_COLOR ::= "__PKL_BUILTIN_TERM_GET_COLOR__"
BUILTIN_TERM_SET_COLOR ::= "__PKL_BUILTIN_TERM_SET_COLOR__"
BUILTIN_TERM_GET_BGCOLOR ::= "__PKL_BUILTIN_TERM_GET_BGCOLOR__"
BUILTIN_TERM_SET_BGCOLOR ::= "__PKL_BUILTIN_TERM_SET_BGCOLOR__"
BUILTIN_VM_OBASE ::= "__PKL_BUILTIN_VM_OBASE__"
BUILTIN_VM_SET_OBASE ::= "__PKL_BUILTIN_VM_SET_OBASE__"
BUILTIN_VM_OACUTOFF ::= "__PKL_BUILTIN_VM_OACUTOFF__"
BUILTIN_VM_SET_OACUTOFF ::= "__PKL_BUILTIN_VM_SET_OACUTOFF__"
BUILTIN_VM_ODEPTH ::= "__PKL_BUILTIN_VM_ODEPTH__"
BUILTIN_VM_SET_ODEPTH ::= "__PKL_BUILTIN_VM_SET_ODEPTH__"
BUILTIN_VM_OINDENT ::= "__PKL_BUILTIN_VM_OINDENT__"
BUILTIN_VM_SET_OINDENT ::= "__PKL_BUILTIN_VM_SET_OINDENT__"
BUILTIN_VM_OMAPS ::= "__PKL_BUILTIN_VM_OMAPS__"
BUILTIN_VM_SET_OMAPS ::= "__PKL_BUILTIN_VM_SET_OMAPS__"
BUILTIN_VM_OMODE ::= "__PKL_BUILTIN_VM_OMODE__"
BUILTIN_VM_SET_OMODE ::= "__PKL_BUILTIN_VM_SET_OMODE__"
BUILTIN_VM_OPPRINT ::= "__PKL_BUILTIN_VM_OPPRINT__"
BUILTIN_VM_SET_OPPRINT ::= "__PKL_BUILTIN_VM_SET_OPPRINT__"
BUILTIN_UNSAFE_STRING_SET ::= "__PKL_BUILTIN_UNSAFE_STRING_SET__"

UINTCONSTR ::= "uint<"
INTCONSTR ::= "int<"
OFFSETCONSTR ::= "offset<"

THREEDOTS ::= "..."
RANGEA ::= "+:"

POWA ::= "**="
MULA ::= "*="
DIVA ::= "/="
MODA ::= "%="
ADDA ::= "+="
SUBA ::= "-="
SLA ::= "<<.="
SRA ::= ".>>="
BANDA ::= "&="
IORA ::= "|="
XORA ::= "^="
BCONC ::= ":::"

OR ::= "||"
AND ::= "&&"
IMPL ::= "=>"
EQ ::= "=="
NE ::= "!="
LE ::= "<="
GE ::= ">="
SL ::= "<<."
SR ::= ".>>"
INC ::= "++"
DEC ::= "--"

POW ::= "**"
CEILDIV ::= "/^"
NSMAP ::= "@!"

====

Cheers !