Simplify grammar specification

brendanzab · brendanzab · commit 3ef44b778bba · 2020-11-28T16:53:40.000+11:00
diff --git a/book/src/specification/textual-representation/concrete-syntax.md b/book/src/specification/textual-representation/concrete-syntax.md
@@ -4,45 +4,43 @@ This section defines the concrete syntax of the surface language.
 
 ## Terms
 
-Precedence climbing is used to define the syntax of terms:
-
-> **Grammar**:
->
-> <a href="#var:term"><var id="var:term">term</var></a> ::=\
-> &emsp;|&ensp;<a href="#var:expr-term"><var>expr-term</var></a>\
-> &emsp;|&ensp;<a href="#var:expr-term"><var>expr-term</var></a> `:` <a href="#var:term"><var>term</var></a>
->
-> <a href="#var:expr-term"><var id="var:expr-term">expr-term</var></a> ::=\
-> &emsp;|&ensp;<a href="#var:arrow-term"><var>arrow-term</var></a>\
-> &emsp;|&ensp;`fun` <var>name</var><sup>+</sup> `=>` <a href="#var:expr-term"><var>expr-term</var></a>
->
-> <a href="#var:arrow-term"><var id="var:arrow-term">arrow-term</var></a> ::=\
-> &emsp;|&ensp;<a href="#var:app-term"><var>app-term</var></a>\
-> &emsp;|&ensp;`Fun` (`(` <var>name</var><sup>+</sup> `:` <a href="#var:arrow-term"><var>arrow-term</var></a> `)`)<sup>+</sup> `->` <a href="#var:arrow-term"><var>arrow-term</var></a>\
-> &emsp;|&ensp;<a href="#var:app-term"><var>app-term</var></a> `->` <a href="#var:arrow-term"><var>arrow-term</var></a>
->
-> <a href="#var:app-term"><var id="var:app-term">app-term</var></a> ::=\
-> &emsp;|&ensp;<a href="#var:atomic-term"><var>atomic-term</var></a>\
-> &emsp;|&ensp;<a href="#var:atomic-term"><var>atomic-term</var></a> <a href="#var:atomic-term"><var>atomic-term</var></a><sup>+</sup>
->
-> <a href="#var:atomic-term"><var id="var:atomic-term">atomic-term</var></a> ::=\
-> &emsp;|&ensp;`(` <a href="#var:term"><var>term</var></a> `)`\
-> &emsp;|&ensp;<var>name</var>\
-> &emsp;|&ensp;<a href="#var:atomic-term"><var>atomic-term</var></a> `^` <var>number-literal</var>\
-> &emsp;|&ensp;`Record` `{` (<a href="#var:type-entry"><var>type-entry</var></a> `,`)<sup>\*</sup> <a href="#var:type-entry"><var>type-entry</var></a><sup>?</sup>  `}`\
-> &emsp;|&ensp;`record` `{` (<a href="#var:term-entry"><var>term-entry</var></a> `,`)<sup>\*</sup> <a href="#var:term-entry"><var>term-entry</var></a><sup>?</sup> `}`\
-> &emsp;|&ensp;<a href="#var:atomic-term"><var>atomic-term</var></a> `.` <var>name</var>\
-> &emsp;|&ensp;`[` (<a href="#var:term"><var>term</var></a> `,`)<sup>\*</sup> <a href="#var:term"><var>term</var></a><sup>?</sup> `]`\
-> &emsp;|&ensp;<var>number-literal</var>\
-> &emsp;|&ensp;<var>character-literal</var>\
-> &emsp;|&ensp;<var>string-literal</var>
+```text
+term ::=
+    | expr-term
+    | expr-term ":" term
+
+expr-term ::=
+    | arrow-term
+    | "fun" name+ "=>" expr-term
+
+arrow-term ::=
+    | app-term
+    | "Fun" ("(" name+ ":" arrow-term ")")+ "->" arrow-term
+    | app-term "->" arrow-term
+
+app-term ::=
+    | atomic-term
+    | atomic-term atomic-term+
+
+atomic-term ::=
+    | "(" term ")"
+    | name
+    | atomic-term "^" number-literal
+    | "Record" "{" (type-entry ",")* type-entry? "}"
+    | "record" "{" (term-entry ",")* term-entry? "}"
+    | atomic-term "." name
+    | "[" (term ",")* term? "]"
+    | number-literal
+    | character-literal
+    | string-literal
+```
 
 ## Entries
 
-> **Grammar**:
->
-> <a href="#var:type-entry"><var id="var:type-entry">type-entry</var></a> ::=\
-> &emsp;|&ensp;<var>doc-comment</var><sup>\*</sup> <var>name</var> (`as` <var>name</var>)<sup>?</sup> `:` <a href="#var:term"><var>term</var></a>
->
-> <a href="#var:term-entry"><var id="var:term-entry">term-entry</var></a> ::=\
-> &emsp;|&ensp;<var>doc-comment</var><sup>\*</sup> <var>name</var> (`as` <var>name</var>)<sup>?</sup> `=` <a href="#var:term"><var>term</var></a>
+```text
+type-entry ::=
+    | doc-comment* name ("as" name)? ":" term
+
+term-entry ::=
+    | doc-comment* name ("as" name)? "=" term
+```
diff --git a/book/src/specification/textual-representation/lexical-syntax.md b/book/src/specification/textual-representation/lexical-syntax.md
@@ -6,150 +6,127 @@ The _lexical structure_ of the Pikelet programming langues is a description of w
 
 The textual surface language assigns meaning to a source string,
 which consists of a sequence of _Unicode scalar values_ (as defined in Section 3.4 of [the Unicode Standard](www.unicode.org/versions/latest/)),
-terminated with a virtual end-of-file symbol, &empty;:
-
-> **Grammar**:
->
-> <a href="#var:unicode-scalar-value"><var id="var:unicode-scalar-value">unicode-scalar-value</var></a> ::=\
-> &emsp;|&ensp;<kbd>U+00</kbd> &hellip; <kbd>U+D7FF</kbd>\
-> &emsp;|&ensp;<kbd>U+E000</kbd> &hellip; <kbd>U+10FFF</kbd>
->
-> <a href="#var:source"><var id="var:source">source</var></a> ::=\
-> &emsp;|&ensp;<a href="#var:unicode-scalar-value"><var>unicode-scalar-value</var></a><sup>\*</sup> &empty;
-
-For convenience, we define a number of special values within the above <a href="#var:unicode-scalar-value"><var>unicode-scalar-value</var></a> definition:
-
-> **Grammar**:
->
-> <a href="#var:horizontal-tab"><var id="var:horizontal-tab">horizontal-tab</var></a> ::=\
-> &emsp;|&ensp;<kbd>U+0009</kbd>
->
-> <a href="#var:line-feed"><var id="var:line-feed">line-feed</var></a> ::=\
-> &emsp;|&ensp;<kbd>U+000A</kbd>
->
-> <a href="#var:vertical-tab"><var id="var:vertical-tab">vertical-tab</var></a> ::=\
-> &emsp;|&ensp;<kbd>U+000B</kbd>
->
-> <a href="#var:form-feed"><var id="var:form-feed">form-feed</var></a> ::=\
-> &emsp;|&ensp;<kbd>U+000C</kbd>
->
-> <a href="#var:carriage-return"><var id="var:carriage-return">carriage-return</var></a> ::=\
-> &emsp;|&ensp;<kbd>U+000D</kbd>
->
-> <a href="#var:next-line"><var id="var:next-line">next-line</var></a> ::=\
-> &emsp;|&ensp;<kbd>U+0085</kbd>
->
-> <a href="#var:left-to-right-mark"><var id="var:left-to-right-mark">left-to-right-mark</var></a> ::=\
-> &emsp;|&ensp;<kbd>U+200E</kbd>
->
-> <a href="#var:right-to-left-mark"><var id="var:right-to-left-mark">right-to-left-mark</var></a> ::=\
-> &emsp;|&ensp;<kbd>U+200F</kbd>
->
-> <a href="#var:line-separator"><var id="var:line-separator">line-separator</var></a> ::=\
-> &emsp;|&ensp;<kbd>U+2028</kbd>
->
-> <a href="#var:paragraph-separator"><var id="var:paragraph-separator">paragraph-separator</var></a> ::=\
-> &emsp;|&ensp;<kbd>U+2029</kbd>
+terminated with a virtual end-of-file symbol, `"\0"`:
+
+```text
+unicode-scalar-value ::=
+    | "\u{00}" ... "\u{D7FF}"
+    | "\u{E000}" ... "\u{10FFF}"
+
+source ::=
+    | unicode-scalar-value* "\0"
+```
+
+For convenience, we define a number of special values within the above `unicode-scalar-value` definition:
+
+```text
+horizontal-tab        ::= "\u{0009}"
+line-feed             ::= "\u{000A}"
+vertical-tab          ::= "\u{000B}"
+form-feed             ::= "\u{000C}"
+carriage-return       ::= "\u{000D}"
+next-line             ::= "\u{0085}"
+left-to-right-mark    ::= "\u{200E}"
+right-to-left-mark    ::= "\u{200F}"
+line-separator        ::= "\u{2028}"
+paragraph-separator   ::= "\u{2029}"
+```
 
 ## Whitespace and comments
 
-> **Grammar**:
->
-> <a href="#var:line-break"><var id="var:line-break">line-break</var></a> ::=\
-> &emsp;|&ensp;<a href="#var:line-feed"><var>line-feed</var></a>\
-> &emsp;|&ensp;<a href="#var:carriage-return"><var>carriage-return</var></a>\
-> &emsp;|&ensp;<a href="#var:carriage-return"><var>carriage-return</var></a> <a href="#var:line-feed"><var>line-feed</var></a>\
-> &emsp;|&ensp;&empty;
->
-> <a href="#var:comment-text"><var id="var:comment-text">comment-text</var></a> ::=\
-> &emsp;|&ensp;~(<a href="#var:line-feed"><var>line-feed</var></a> | <a href="#var:carriage-return"><var>carriage-return</var></a>) <a href="#var:unicode-scalar-value"><var>unicode-scalar-value</var></a><sup>\*</sup>
->
-> <a href="#var:comment"><var id="var:comment">comment</var></a> ::=\
-> &emsp;|&ensp;`--` <a href="comment-text"><var>comment-text</var></a> <a href="#var:line-break"><var>line-break</var></a>
->
-> <a href="#var:doc-comment"><var id="var:doc-comment">doc-comment</var></a> ::=\
-> &emsp;|&ensp;`|||` <a href="comment-text"><var>comment-text</var></a> <a href="#var:line-break"><var>line-break</var></a>
->
-> <a href="#var:white-space"><var id="var:white-space">white-space</var></a> ::=\
-> &emsp;|&ensp;<a href="#var:horizontal-tab"><var>horizontal-tab</var></a>\
-> &emsp;|&ensp;<a href="#var:comment"><var>comment</var></a>\
-> &emsp;|&ensp;<a href="#var:vertical-tab"><var>vertical-tab</var></a>\
-> &emsp;|&ensp;<a href="#var:form-feed"><var>form-feed</var></a>\
-> &emsp;|&ensp;<a href="#var:line-break"><var>line-break</var></a>\
-> &emsp;|&ensp;<a href="#var:next-line"><var>next-line</var></a>\
-> &emsp;|&ensp;<a href="#var:left-to-right-mark"><var>left-to-right-mark</var></a>\
-> &emsp;|&ensp;<a href="#var:right-to-left-mark"><var>right-to-left-mark</var></a>\
-> &emsp;|&ensp;<a href="#var:line-separator"><var>line-separator</var></a>\
-> &emsp;|&ensp;<a href="#var:paragraph-separator"><var>paragraph-separator</var></a>
-
-## Keywords and identifiers
-
-> **Grammar**:
->
-> <a href="#var:keyword"><var id="var:keyword">keyword</var></a> ::=\
-> &emsp;|&ensp;`as`\
-> &emsp;|&ensp;`fun`\
-> &emsp;|&ensp;`Fun`\
-> &emsp;|&ensp;`Record`\
-> &emsp;|&ensp;`record`
->
-> <a href="#var:ident-or-keyword"><var id="var:ident-or-keyword">ident-or-keyword</var></a> ::=\
-> &emsp;|&ensp;(`a` &hellip; `z` | `A` &hellip; `Z`) (`a` &hellip; `z` | `A` &hellip; `Z` | `0` &hellip; `9` | `-`)<sup>\*</sup>
->
-> <a href="#var:ident"><var id="var:ident">ident</var></a> ::=\
-> &emsp;|&ensp;~<a href="#var:keyword"><var>keyword</var></a> <a href="#var:ident-or-keyword"><var>ident-or-keyword</var></a>
+```text
+line-break ::=
+    | line-feed
+    | carriage-return
+    | carriage-return line-feed
+    | "\0"
+
+comment-text ::=
+    | (~(line-feed | carriage-return) unicode-scalar-value)*
+
+comment ::=
+    | "--" comment-text line-break
+
+doc-comment ::=
+    | "|||" comment-text line-break
+
+white-space ::=
+    | horizontal-tab
+    | comment
+    | vertical-tab
+    | form-feed
+    | line-break
+    | next-line
+    | left-to-right-mark
+    | right-to-left-mark
+    | line-separator
+    | paragraph-separator
+```
+
+## Keywords and names
+
+```text
+keyword ::=
+    | "as"
+    | "fun"
+    | "Fun"
+    | "Record"
+    | "record"
+
+name-or-keyword ::=
+    | ("a" ... "z" | "A" ... "Z") ("a" ... "z" | "A" ... "Z" | "0" ... "9" | "-")*
+
+name ::=
+    | ~keyword name-or-keyword
+```
 
 ### Punctuation
 
-> **Grammar**:
->
-> <a href="#var:delimiter"><var id="var:delimiter">delimiter</var></a> ::=\
-> &emsp;|&ensp;`{`\
-> &emsp;|&ensp;`}`\
-> &emsp;|&ensp;`[`\
-> &emsp;|&ensp;`]`\
-> &emsp;|&ensp;`(`\
-> &emsp;|&ensp;`)`
->
-> <a href="#var:symbol"><var id="var:symbol">symbol</var></a> ::=\
-> &emsp;|&ensp;`.`\
-> &emsp;|&ensp;`:`\
-> &emsp;|&ensp;`,`\
-> &emsp;|&ensp;`=`\
-> &emsp;|&ensp;`=>`\
-> &emsp;|&ensp;`->`
->
-> <a href="#var:punctuation"><var id="var:punctuation">punctuation</var></a> ::=\
-> &emsp;|&ensp;<a href="#var:delimiter"><var>delimiter</var></a>\
-> &emsp;|&ensp;<a href="#var:symbol"><var>symbol</var></a>
-
-### Numeric literals
-
-> **Grammar**:
->
-> <a href="#var:number-literal"><var id="var:number-literal">number-literal</var></a> ::=\
-> &emsp;|&ensp;(`+` | `-`)<sup>?</sup> (`0` &hellip; `9`) (`a` &hellip; `z` | `A` &hellip; `Z` | `0` &hellip; `9` | `.`)<sup>*</sup></sup>
-
-### Character and string literals
-
-> **Grammar**:
->
-> <a href="#var:character-literal"><var id="var:character-literal">character-literal</var></a> ::=\
-> &emsp;|&ensp;`"` (`\"` | ~`"` <a href="#var:unicode-scalar-value"><var>unicode-scalar-value</var></a>)<sup>\*</sup>  `"`
->
-> <a href="#var:string-literal"><var id="var:string-literal">string-literal</var></a> ::=\
-> &emsp;|&ensp;`'` (`\'` | ~`'` <a href="#var:unicode-scalar-value"><var>unicode-scalar-value</var></a>)<sup>\*</sup>  `'`
+```text
+delimiter ::=
+    | "{"
+    | "}"
+    | "["
+    | "]"
+    | "("
+    | ")"
+
+symbol ::=
+    | "."
+    | ":"
+    | ","
+    | "="
+    | "=>"
+    | "->"
+
+punctuation ::=
+    | delimiter
+    | symbol
+```
+
+### Literals
+
+```text
+number-literal ::=
+    | ("+" | "-")? ("0" ... "9") ("a" ... "z" | "A" ... "Z" | "0" ... "9" | ".")*
+
+character-literal ::=
+    | "\"" ("\"" | ~"\"" unicode-scalar-value)* "\""
+
+string-literal ::=
+    | "'" ("'" | ~"'" unicode-scalar-value)* "'"
+```
 
 ### Tokens
 
-> **Grammar**:
->
-> <a href="#var:token"><var id="var:token">token</var></a> ::=\
-> &emsp;|&ensp;<a href="#var:white-space"><var>white-space</var></a>\
-> &emsp;|&ensp;<a href="#var:doc-comment"><var>doc-comment</var></a>\
-> &emsp;|&ensp;<a href="#var:keyword"><var>keyword</var></a>\
-> &emsp;|&ensp;<a href="#var:ident"><var>ident</var></a>\
-> &emsp;|&ensp;<a href="#var:punctuation"><var>punctuation</var></a>\
-> &emsp;|&ensp;<a href="#var:number-literal"><var>number-literal</var></a>\
-> &emsp;|&ensp;<a href="#var:character-literal"><var>character-literal</var></a>\
-> &emsp;|&ensp;<a href="#var:string-literal"><var>string-literal</var></a>
+```text
+token ::=
+    | white-space
+    | doc-comment
+    | keyword
+    | name
+    | punctuation
+    | number-literal
+    | character-literal
+    | string-literal
+```
