From 40373310c5c741210b7a681c19eb97031493c038 Mon Sep 17 00:00:00 2001 From: "Elliott B. Edwards (el2iot2)" <28941195+el2iot2@users.noreply.github.com> Date: Sat, 21 Dec 2024 15:57:13 -0800 Subject: [PATCH] Add railroad diagrams for KDL 2.0 grammar closes Railroad diagrams for kdl #9 --- doc/README.md | 7 + doc/kdl-2-0-railroad-diagrams.html | 512 +++++++++++++++++++++++++++++ doc/kdl-2-0.ebnf | 56 ++++ 3 files changed, 575 insertions(+) create mode 100644 doc/README.md create mode 100644 doc/kdl-2-0-railroad-diagrams.html create mode 100644 doc/kdl-2-0.ebnf diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..3c20bf7 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,7 @@ +# `kdl-2-0.ebnf` + +This file is a simplification of the [v2.0 spec for KDL](https://github.com/kdl-org/kdl/blob/main/SPEC.md) as adapted purely for the creation of approximated railroad diagrams (via this handy [application](https://www.bottlecaps.de/rr/ui)). + +> Largely this was adapted by summarizing certain "reg-ex" like formulations of rules as production rules with names that simply describe the resulting character classes. These rules, then left undefined in the grammar, display an intelligible intuition of what the grammar will do. For full details, one should carefully review the official spec. + +The resulting generated html is [here](kdl-2-0-railroad-diagrams.html). diff --git a/doc/kdl-2-0-railroad-diagrams.html b/doc/kdl-2-0-railroad-diagrams.html new file mode 100644 index 0000000..87f9111 --- /dev/null +++ b/doc/kdl-2-0-railroad-diagrams.html @@ -0,0 +1,512 @@ + + + + + + + + +

document:

+

+
document ::= '\u{FEFF}'? nodes
+

+

no references


nodes:

+

+
nodes    ::= line-space* ( nodeline-space* )*
+

+

referenced by: + +

+


node:

+

+
node     ::= base-nodenode-terminator
+

+

referenced by: + +

+


final-node:

+

+
final-node
+
         ::= base-nodenode-terminator?
+

+

referenced by: + +

+


base-node:

+

+
base-node
+
         ::= slashdash? type? node-space* string ( node-space+ slashdash? node-prop-or-arg )* ( node-space+ slashdashnode-children )* ( node-space+ node-children )? ( node-space+ slashdashnode-children )* node-space*
+

+

referenced by: + +

+


node-prop-or-arg:

+

+
node-prop-or-arg
+
         ::= prop
+
           | value
+

+

referenced by: + +

+


node-children:

+

+
node-children
+
         ::= '{' nodesfinal-node? '}'
+

+

referenced by: + +

+


node-terminator:

+

+
node-terminator
+
         ::= single-line-comment
+
           | newline
+
           | ';'
+
           | eof
+

+

referenced by: + +

+


prop:

+

+
prop     ::= stringnode-space* '=' node-space* value
+

+

referenced by: + +

+


value:

+

+
value    ::= type? node-space* ( string | number | keyword )
+

+

referenced by: + +

+


type:

+

+
type     ::= '(' node-space* stringnode-space* ')'
+

+

referenced by: + +

+


string:

+

+
string   ::= identifier-string
+
           | quoted-string
+
           | raw-string
+

+

referenced by: + +

+


identifier-string:

+

+
identifier-string
+
         ::= unambiguous-ident
+
           | signed-ident
+
           | dotted-ident
+

+

referenced by: + +

+


quoted-string:

+

+
quoted-string
+
         ::= '"' single-line-string-body '"'
+
           | '"""' newlinemulti-line-string-bodynewlineunicode-space* '"""'
+

+

referenced by: + +

+


single-line-string-body:

+

+
single-line-string-body
+
         ::= string-character-minus-newline*
+

+

referenced by: + +

+


multi-line-string-body:

+

+
multi-line-string-body
+
         ::= ( ( '"' | '""' )? string-character )*
+

+

referenced by: + +

+


string-character:

+

+
string-character
+
         ::= '\' escape
+
           | neither-quote-nor-disallowed-literal-code-points
+

+

referenced by: + +

+


escape:

+

+
escape   ::= ["\bfnrts]
+
           | 'u{' hex-digit ( hex-digit ( hex-digit ( hex-digit ( hex-digithex-digit? )? )? )? )? '}'
+
           | ( unicode-space | newline )+
+

+

referenced by: + +

+


hex-digit:

+

+
hex-digit
+
         ::= [0-9a-fA-F]
+

+

referenced by: + +

+


raw-string:

+

+
raw-string
+
         ::= '#' ( raw-string-quotes | raw-string ) '#'
+

+

referenced by: + +

+


raw-string-quotes:

+

+
raw-string-quotes
+
         ::= '"' single-line-raw-string-body '"'
+
           | '"""' newlinemulti-line-raw-string-body '"""'
+

+

referenced by: + +

+


single-line-raw-string-body:

+

+
single-line-raw-string-body
+
         ::= ''
+
           | '"'? single-line-raw-string-char-minus-double-quotesingle-line-raw-string-char*
+

+

referenced by: + +

+


number:

+

+
number   ::= keyword-number
+
           | hex
+
           | octal
+
           | binary
+
           | decimal
+

+

referenced by: + +

+


decimal:

+

+
decimal  ::= sign? integer ( '.' integer )? exponent?
+

+

referenced by: + +

+


exponent:

+

+
exponent ::= ( 'e' | 'E' ) sign? integer
+

+

referenced by: + +

+


integer:

+

+
integer  ::= digit ( digit | '_' )*
+

+

referenced by: + +

+


digit:

+

+
digit    ::= [0-9]
+

+

referenced by: + +

+


sign:

+

+
sign     ::= '+'
+
           | '-'
+

+

referenced by: + +

+


hex:

+

+
hex      ::= sign? '0x' hex-digit ( hex-digit | '_' )*
+

+

referenced by: + +

+


octal:

+

+
octal    ::= sign? '0o' [0-7] [0-7_]*
+

+

referenced by: + +

+


binary:

+

+
binary   ::= sign? '0b' ( '0' | '1' ) ( '0' | '1' | '_' )*
+

+

referenced by: + +

+


keyword:

+

+
keyword  ::= boolean
+
           | '#null'
+

+

referenced by: + +

+


keyword-number:

+

+
keyword-number
+
         ::= '#inf'
+
           | '#-inf'
+
           | '#nan'
+

+

referenced by: + +

+


boolean:

+

+
boolean  ::= '#true'
+
           | '#false'
+

+

referenced by: + +

+


single-line-comment:

+

+
single-line-comment
+
         ::= '//' anything-but-newline* ( newline | eof )
+

+

referenced by: + +

+


multi-line-comment:

+

+
multi-line-comment
+
         ::= '/*' ( multi-line-comment | '*' | '/' | not-block-end+ )* '*/'
+

+

referenced by: + +

+


slashdash:

+

+
slashdash
+
         ::= '/-' ( node-space | line-space )*
+

+

referenced by: + +

+


ws:

+

+
ws       ::= unicode-space
+
           | multi-line-comment
+

+

referenced by: + +

+


escline:

+

+
escline  ::= '\\' ws* ( single-line-comment | newline | eof )
+

+

referenced by: + +

+


line-space:

+

+
line-space
+
         ::= newline
+
           | ws
+
           | single-line-comment
+

+

referenced by: + +

+


node-space:

+

+
node-space
+
         ::= ws* ( esclinews* | ws )
+

+

referenced by: + +

+


+

+ + + + + + +
  + ... generated by RR - Railroad Diagram Generator +
+

+ + \ No newline at end of file diff --git a/doc/kdl-2-0.ebnf b/doc/kdl-2-0.ebnf new file mode 100644 index 0000000..d4d813b --- /dev/null +++ b/doc/kdl-2-0.ebnf @@ -0,0 +1,56 @@ +document ::= bom? nodes +bom ::= '\u{FEFF}' +nodes ::= (line-space* node)* line-space* +node ::= base-node node-terminator +final-node ::= base-node node-terminator? +base-node ::= slashdash? type? node-space* string + (node-space+ slashdash? node-prop-or-arg)* + // slashdashed node-children must always be after props and args. + (node-space+ slashdash node-children)* + (node-space+ node-children)? + (node-space+ slashdash node-children)* + node-space* +node-prop-or-arg ::= prop | value +node-children ::= '{' nodes final-node? '}' +node-terminator ::= single-line-comment | newline | ';' | eof +prop ::= string node-space* '=' node-space* value +value ::= type? node-space* (string | number | keyword) +type ::= '(' node-space* string node-space* ')' +string ::= identifier-string | quoted-string | raw-string +identifier-string ::= unambiguous-ident | signed-ident | dotted-ident +quoted-string ::= '"' single-line-string-body '"' | '"""' newline multi-line-string-body newline unicode-space* '"""' +single-line-string-body ::= (string-character-minus-newline)* +multi-line-string-body ::= (('"' | '""')? string-character)* +string-character ::= '\' escape | neither-quote-nor-disallowed-literal-code-points +escape ::= ["\\bfnrts] | + 'u{' hex-digit '}' | + 'u{' hex-digit hex-digit '}' | + 'u{' hex-digit hex-digit hex-digit '}' | + 'u{' hex-digit hex-digit hex-digit hex-digit '}' | + 'u{' hex-digit hex-digit hex-digit hex-digit hex-digit '}' | + 'u{' hex-digit hex-digit hex-digit hex-digit hex-digit hex-digit '}' | + (unicode-space | newline)+ +hex-digit ::= [0-9a-fA-F] +raw-string ::= '#' raw-string-quotes '#' | '#' raw-string '#' +raw-string-quotes ::= '"' single-line-raw-string-body '"' | '"""' newline multi-line-raw-string-body '"""' +single-line-raw-string-body ::= '' | (single-line-raw-string-char-minus-double-quote) single-line-raw-string-char*? | '"' (single-line-raw-string-char-minus-double-quote) single-line-raw-string-char*? +number ::= keyword-number | hex | octal | binary | decimal +decimal ::= sign? integer ('.' integer)? exponent? +exponent ::= ('e' | 'E') sign? integer +integer ::= digit (digit | '_')* +digit ::= [0-9] +sign ::= '+' | '-' +hex ::= sign? '0x' hex-digit (hex-digit | '_')* +octal ::= sign? '0o' [0-7] [0-7_]* +binary ::= sign? '0b' ('0' | '1') ('0' | '1' | '_')* +keyword ::= boolean | '#null' +keyword-number ::= '#inf' | '#-inf' | '#nan' +boolean ::= '#true' | '#false' +single-line-comment ::= '//' anything-but-newline* (newline | eof) +multi-line-comment ::= '/*' commented-block +commented-block ::= '*/' | (multi-line-comment | '*' | '/' | not-block-end+) commented-block +slashdash ::= '/-' (node-space | line-space)* +ws ::= unicode-space | multi-line-comment +escline ::= '\\' ws* (single-line-comment | newline | eof) +line-space ::= newline | ws | single-line-comment +node-space ::= ws* escline ws* | ws+