Consistency improvements in fsgrammar listings (#86)

Improves the consistency of `fsgrammar` listings. The following changes
were applied in general:

- Replaced `opt` or `~opt` suffixes with `?`
- Enclosed symbolic keywords and operators with single quotes
- Used parentheses to group optional terms in `attribute := (
attribute-target ':' )? object-construction`

Author: roboz0r

spec/custom-attributes-and-reflection.md

@@ -8,9 +8,9 @@ describes these mechanisms for F#.
 Attributes are given by the following grammar:
 
 ```fsgrammar
-attribute := attribute-target : opt object-construction
+attribute := ( attribute-target ':' )? object-construction
 
-attribute-set := [< attribute ; ... ; attribute >]
+attribute-set := '[<' attribute ';' ... ';' attribute '>]'
 
 attributes := attribute-set ... attribute-set
 

spec/expressions.md

@@ -73,22 +73,22 @@ F# includes the following additional syntactic forms for ML compatibility:
 ```fsgrammar
 expr :=
     | ...
-    | expr .( expr ) // array lookup
-    | expr .( expr ) <- expr // array assignment
+    | expr '.(' expr ')' // array lookup
+    | expr '.(' expr ')' '<-' expr // array assignment
 ```
 
 ```fsgrammar
 type :=
     | ...
-    | ( type ,..., type ) long-ident // generic type instantiation
+    | '(' type ',' ... ',' type ')' long-ident // generic type instantiation
 
 module-implementation :=
     | ...
-    | module ident = struct ... end
+    | module ident '=' struct ... end
 
 module-signature :=
     | ...
-    | module ident : sig ... end
+    | module ident ':' sig ... end
 ```
 
 An ML compatibility warning occurs when these constructs are used.
@@ -100,13 +100,13 @@ The following expression forms
 ```fsgrammar
 expr :=
     | ...
-    | expr.(expr) // array lookup
-    | expr.(expr) <- expr // array assignment
+    | expr '.(' expr ')' // array lookup
+    | expr '.(' expr ')' '<-' expr // array assignment
 ```
 
 Are equivalent to the following uses of library-defined operators:
 
-```fsgrammar
+```fsharp
 e1.(e2)               → (.()) e1 e2
 e1.(e2) <- e3         → (.()<-) e1 e2 e3
 ```
@@ -115,7 +115,7 @@ e1.(e2) <- e3         → (.()<-) e1 e2 e3
 
 F# defines the following two additional shortcut operators:
 
-```fsgrammar
+```fsharp
 e1 or e2                  → (or) e1 e2
 e1 & e2                   → (&) e1 e2
 ```

spec/features-for-ml-compatibility.md

@@ -64,7 +64,7 @@ val vowels: char list = ['e'; 'i'; 'o'; 'u']
 
 > ['a'] @ vowels;;
 val it: char list = ['a'; 'e'; 'i'; 'o'; 'u']
-    
+
 > vowels @ ['y'];;
 val it: char list = ['e'; 'i'; 'o'; 'u'; 'y']
 ```
@@ -451,4 +451,4 @@ Regular expressions are typically used to specify tokens.
 token token-name = regexp
 ```
 
-In the grammar rules, the notation `element-name?` indicates an optional element. The notation `...` indicates repetition of the preceding non-terminal construct and the separator token. For example, `expr ',' ... ',' expr` means a sequence of one or more `expr` elements separated by commas.
+In the grammar rules, the notation `element-name?` indicates an optional element. Where the optional element requires multiple tokens, it is enclosed in parentheses `(e1 e2)?`. The notation `...` indicates repetition of the preceding non-terminal construct and the separator token. For example, `expr ',' ... ',' expr` means a sequence of one or more `expr` elements separated by commas. Literal symbols like `,` that appear in the grammer are enclosed in single quotes i.e. `','`, except the single quote character itself which is enclosed in double quotes `"'"`. Comments may be placed at the end of a line, prefixed with `--`.

spec/introduction.md

@@ -135,7 +135,7 @@ used for the name of a types, union type case, module, or namespace, the followi
 not allowed even inside double-backtick marks:
 
 ```fsgrammar
-‘.', '+', '$', '&', '[', ']', '/', '\\', '*', '\"', '`'
+'.', '+', '$', '&', '[', ']', '/', '\\', '*', '\"', '`'
 ```
 
 All input files are currently assumed to be encoded as UTF-8. See the C# specification for a list of the
@@ -178,7 +178,7 @@ The following token forms are reserved, except when they are part of a symbolic
 
 ```fsgrammar
 token reserved-ident-formats =
-    | ident-text ( '!' | '#')
+    | ident-text ( '!' | '#' )
 ```
 
 In the remainder of this specification, we refer to the token that is generated for a keyword simply

spec/lexical-analysis.md

@@ -12,7 +12,7 @@ module-signature :=
     module ident = module-signature-body
 
 module-signature-element :=
-    val mutable~opt curried-sig     -- value signature
+    val mutable? curried-sig        -- value signature
     val value-defn                  -- literal value signature
     type type-signatures            -- type(s) signature
     exception exception-signature   -- exception signature
@@ -40,21 +40,21 @@ type-signature :=
 type-signatures := type-signature ... and ... type-signature
 
 type-signature-element :=
-    attributesopt access~opt new : uncurried-sig        -- constructor signature
-    attributesopt member acces~opt member-sig           -- member signature
-    attributesopt abstract access~opt member-sig        -- member signature
-    attributesopt override member-sig                   -- member signature
-    attributesopt default member-sig                    -- member signature
-    attributes~opt static member access~opt member-sig  -- static member signature
+    attributes? access? new : uncurried-sig             -- constructor signature
+    attributes? member access? member-sig               -- member signature
+    attributes? abstract access? member-sig             -- member signature
+    attributes? override member-sig                     -- member signature
+    attributes? default member-sig                      -- member signature
+    attributes? static member access? member-sig        -- static member signature
     interface type                                      -- interface signature
 
 abbrev-type-signature := type-name '=' type
 
 union-type-signature := type-name '=' union-type-cases type-extension-elements-
-    signature~opt
+    signature?
 
 record-type-signature := type-name '=' '{' record-fields '}' type-extension-
-    elements-signature~opt
+    elements-signature?
 
 anon-type-signature := type-name '=' begin type-elements-signature end
 
@@ -194,7 +194,7 @@ values are implicit in module signatures. A signature that contains the followin
 `[A1 ... An]` for `F`:
 
 ```fsgrammar
-val F : ty11 * ... * ty1A1 - > ... -> tyn1 * ... * tynAn - > rty
+val F : ty11 '*' ... '*' ty1A1 '->' ... '->' tyn1 '*' ... '*' tynAn '->' rty
 ```
 
 Arities in a signature must be equal to or shorter than the corresponding arities in an

spec/namespace-and-module-signatures.md

@@ -16,10 +16,10 @@ namespace-decl-group :=
     namespace global module-elems           -- elements within no namespace
 
 module-defn :=
-    attributesopt module accessopt ident = module-defn-body
+    attributes? module access? ident = module-defn-body
 
 module-defn-body :=
-    begin module-elemsopt end
+    begin module-elems? end
 
 module-elem :=
     module-function-or-value-defn           -- function or value definitions
@@ -31,16 +31,16 @@ module-elem :=
     compiler-directive-decl                 -- compiler directives
 
 module-function-or-value-defn :=
-    attributesopt let function-defn
-    attributesopt let value-defn
-    attributesopt let rec opt function-or-value-defns
-    attributesopt do expr
+    attributes? let function-defn
+    attributes? let value-defn
+    attributes? let rec? function-or-value-defns
+    attributes? do expr
 
 import-decl := open long-ident
 
 module-abbrev := module ident = long-ident
 
-compiler-directive-decl := # ident string ... string
+compiler-directive-decl := '#' ident string ... string
 
 module-elems := module-elem ... module-elem
 
@@ -240,7 +240,7 @@ dogCage |> Cage.getPet |> Dog.bark
 Function and value definitionsin modules introduce named values and functions.
 
 ```fsgrammar
-let rec~opt function-or-value-defn1 and ... and function-or-value-defnn
+let rec? function-or-value-defn1 and ... and function-or-value-defnn
 ```
 
 The following example defines value `x` and functions `id` and `fib`:
@@ -354,7 +354,7 @@ A value that has the `Literal` attribute is subject to the following restriction
 
 ### Type Function Definitions in Modules
 
-Value definitions within modules may have explicit generic parameters. For example, `‘T` is a generic
+Value definitions within modules may have explicit generic parameters. For example, `'T` is a generic
 parameter to the value `empty`:
 
 ```fsharp
@@ -405,13 +405,13 @@ The elaborated form of a type function is that of a function definition that tak
 type `unit`. That is, the elaborated form of
 
 ```fsgrammar
-let ident typar-defns = expr
+let ident typar-defns '=' expr
 ```
 
 is the same as the compiled form for the following declaration:
 
 ```fsgrammar
-let ident typar-defns () = expr
+let ident typar-defns '()' '=' expr
 ```
 
 References to type functions are elaborated to invocations of such a function.
@@ -486,7 +486,7 @@ attribute.
 A module abbreviation defines a local name for a module long identifier, as follows:
 
 ```fsgrammar
-module ident = long-ident
+module ident '=' long-ident
 ```
 
 For example:

spec/namespaces-and-modules.md

@@ -7,63 +7,63 @@ in the subsequent table.
 
 ```fsgrammar
 rule :=
-    pat pattern-guard~opt -> expr       -- pattern, optional guard and action
+    pat pattern-guard? '->' expr            -- pattern, optional guard and action
 
 pattern-guard := when expr
 
 pat :=
-    const                               -- constant pattern
-    long-ident pat-param~opt pat~opt    -- named pattern
-    _ -- wildcard pattern
-    pat as ident                        -- "as" pattern
-    pat '|' pat                         -- disjunctive pattern
-    pat '&' pat                         -- conjunctive pattern
-    pat :: pat                          -- "cons" pattern
-    pat : type                          -- pattern with type constraint
-    pat , ... , pat                     -- tuple pattern
-    struct (pat , ... , pat)            -- struct tuple pattern
-    ( pat )                             -- parenthesized pattern
-    list-pat                            -- list pattern
-    array-pat                           -- array pattern
-    record-pat                          -- record pattern
-    :? atomic-type                      -- dynamic type test pattern
-    :? atomic-type as ident             -- dynamic type test pattern
-    null                                -- null-test pattern
-    attributes pat                      -- pattern with attributes
+    const                                   -- constant pattern
+    long-ident pat-param? pat?              -- named pattern
+    _                                       -- wildcard pattern
+    pat as ident                            -- "as" pattern
+    pat '|' pat                             -- disjunctive pattern
+    pat '&' pat                             -- conjunctive pattern
+    pat '::' pat                            -- "cons" pattern
+    pat ':' type                            -- pattern with type constraint
+    pat ',' ... ',' pat                     -- tuple pattern
+    struct '(' pat ',' ... ',' pat ')'      -- struct tuple pattern
+    '(' pat ')'                             -- parenthesized pattern
+    list-pat                                -- list pattern
+    array-pat                               -- array pattern
+    record-pat                              -- record pattern
+    ':?' atomic-type                        -- dynamic type test pattern
+    ':?' atomic-type as ident               -- dynamic type test pattern
+    null                                    -- null-test pattern
+    attributes pat                          -- pattern with attributes
 
 list-pat :=
-    [ ]
-    [ pat ; ... ; pat ]
+    '[' ']'
+    '[' pat ';' ... ';' pat ']'
 
 array-pat :=
-    [| |]
-    [| pat ; ... ; pat |]
+    '[|' '|]'
+    '[|' pat ';' ... ';' pat '|]'
 
 record-pat :=
-    { field-pat ; ... ; field-pat }
+    '{' field-pat ';' ... ';' field-pat '}'
 
 atomic-pat :=
     pat : one of
             const long-ident list-pat record-pat array-pat ( pat )
             :? atomic-type
             null _
 
-field-pat := long-ident = pat
+field-pat := long-ident '=' pat
 
 pat-param :=
-    | const
-    | long-ident
-    | [ pat-param ; ... ; pat-param ]
-    | ( pat-param , ..., pat-param )
-    | long-ident pat-param
-    | pat-param : type
-    | <@ expr @>
-    | <@@ expr @@>
-    | null
+    '|' const
+    '|' long-ident
+    '|' '[' pat-param ';' ... ';' pat-param ']'
+    '|' '(' pat-param ',' ... ',' pat-param ')'
+    '|' long-ident pat-param
+    '|' pat-param ':' type
+    '|' '<@' expr '@>'
+    '|' '<@@' expr '@@>'
+    '|' null
 
-pats := pat , ... , pat
-field-pats := field-pat ; ... ; field-pat
-rules := '|'~opt rule '|' ... '|' rule
+pats := pat ',' ... ',' pat
+field-pats := field-pat ';' ... ';' field-pat
+rules := '|'? rule '|' ... '|' rule
 ```
 
 Patterns are elaborated to expressions through a process called _pattern match compilation_. This
@@ -107,9 +107,9 @@ strings.
 Patterns in the following forms are _named patterns_ :
 
 ```fsgrammar
-Long-ident
-Long-ident pat
-Long-ident pat-params pat
+long-ident
+long-ident pat
+long-ident pat-params pat
 ```
 
 If `long-ident` is a single identifier that does not begin with an uppercase character, it is interpreted
@@ -355,7 +355,7 @@ In the example, if `x` is `0`, the match returns `1`. If `x` has any other value
 A disjunctive pattern matches an input value against one or the other of two patterns:
 
 ```fsgrammar
-pat | pat
+pat '|' pat
 ```
 
 At runtime, the pattern input is matched against the first pattern. If that fails, the pattern input is
@@ -381,7 +381,7 @@ pattern.
 A conjunctive pattern matches the pattern input against two patterns.
 
 ```fsgrammar
-pat1 & pat2
+pat1 '&' pat2
 ```
 
 For example:
@@ -430,7 +430,7 @@ In this example, both `result1` and `result2` are given the value `6`.
 A _type-annotated pattern_ specifies the type of the value to match to a pattern.
 
 ```fsgrammar
-pat : type
+pat ':' type
 ```
 
 For example:
@@ -452,8 +452,8 @@ static type
 _Dynamic type-test patterns_ have the following two forms:
 
 ```fsgrammar
-:? type
-:? type as ident
+':?' type
+':?' type as ident
 ```
 
 A dynamic type-test pattern matches any value whose runtime type is `type` or a subtype of `type`. For
@@ -509,7 +509,7 @@ to the results of a dynamic coercion expression `e :?> ty`.
 The following is a _record pattern_ :
 
 ```fsgrammar
-{ long-ident1 = pat1 ; ... ; long-identn = patn }
+'{' long-ident1 '=' pat1 ';' ... ';' long-identn '=' patn '}'
 ```
 
 For example:
@@ -533,7 +533,7 @@ specified in the pattern.
 An _array pattern_ matches an array of a partciular length:
 
 ```fsgrammar
-[| pat ; ... ; pat |]
+'[|' pat ';' ... ';' pat '|]'
 ```
 
 For example: