[ABNF] Improve documentation and layout.

Explain better variable and constant declarations.

Leave one blank line between the rules for variable and constant declarations
(not necessary for ABNF, but consistent with the rest of the file and actually
expected by the ABNF-to-LaTeX converter).

Limit lines to 80 columns, by putting the rules for variable and constant
declarations over two lines each, with proper indentation.
This commit is contained in:
Alessandro Coglio 2021-04-29 18:16:30 -07:00
parent c16dad0580
commit 2060d0d249
2 changed files with 64 additions and 46 deletions

View File

@ -466,7 +466,7 @@ described above.
newline = line-feed / carriage-return / carriage-return line-feed
```
Go to: _[carriage-return](#user-content-carriage-return), [line-feed](#user-content-line-feed)_;
Go to: _[line-feed](#user-content-line-feed), [carriage-return](#user-content-carriage-return)_;
Line terminators form whitespace, along with spaces and horizontal tabs.
@ -476,7 +476,7 @@ Line terminators form whitespace, along with spaces and horizontal tabs.
whitespace = space / horizontal-tab / newline
```
Go to: _[horizontal-tab](#user-content-horizontal-tab), [newline](#user-content-newline), [space](#user-content-space)_;
Go to: _[space](#user-content-space), [newline](#user-content-newline), [horizontal-tab](#user-content-horizontal-tab)_;
There are two kinds of comments in Leo, as in other languages.
@ -494,7 +494,7 @@ the ones used in the Java language reference.
comment = block-comment / end-of-line-comment
```
Go to: _[end-of-line-comment](#user-content-end-of-line-comment), [block-comment](#user-content-block-comment)_;
Go to: _[block-comment](#user-content-block-comment), [end-of-line-comment](#user-content-end-of-line-comment)_;
<a name="block-comment"></a>
@ -521,7 +521,7 @@ rest-of-block-comment-after-star = "/"
/ not-star-or-slash rest-of-block-comment
```
Go to: _[rest-of-block-comment-after-star](#user-content-rest-of-block-comment-after-star), [not-star-or-slash](#user-content-not-star-or-slash), [rest-of-block-comment](#user-content-rest-of-block-comment)_;
Go to: _[not-star-or-slash](#user-content-not-star-or-slash), [rest-of-block-comment](#user-content-rest-of-block-comment), [rest-of-block-comment-after-star](#user-content-rest-of-block-comment-after-star)_;
<a name="end-of-line-comment"></a>
@ -596,7 +596,7 @@ lowercase-letter = %x61-7A ; a-z
letter = uppercase-letter / lowercase-letter
```
Go to: _[lowercase-letter](#user-content-lowercase-letter), [uppercase-letter](#user-content-uppercase-letter)_;
Go to: _[uppercase-letter](#user-content-uppercase-letter), [lowercase-letter](#user-content-lowercase-letter)_;
An identifier is a non-empty sequence of letters, digits, and underscores,
@ -639,7 +639,7 @@ format-string-element = not-double-quote-or-open-brace
/ format-string-container
```
Go to: _[not-double-quote-or-open-brace](#user-content-not-double-quote-or-open-brace), [not-double-quote-or-close-brace](#user-content-not-double-quote-or-close-brace), [format-string-container](#user-content-format-string-container)_;
Go to: _[not-double-quote-or-open-brace](#user-content-not-double-quote-or-open-brace), [format-string-container](#user-content-format-string-container), [not-double-quote-or-close-brace](#user-content-not-double-quote-or-close-brace)_;
<a name="format-string"></a>
@ -764,7 +764,7 @@ atomic-literal = untyped-literal
/ address-literal
```
Go to: _[signed-literal](#user-content-signed-literal), [untyped-literal](#user-content-untyped-literal), [field-literal](#user-content-field-literal), [product-group-literal](#user-content-product-group-literal), [boolean-literal](#user-content-boolean-literal), [address-literal](#user-content-address-literal), [unsigned-literal](#user-content-unsigned-literal)_;
Go to: _[product-group-literal](#user-content-product-group-literal), [unsigned-literal](#user-content-unsigned-literal), [signed-literal](#user-content-signed-literal), [untyped-literal](#user-content-untyped-literal), [field-literal](#user-content-field-literal), [boolean-literal](#user-content-boolean-literal), [address-literal](#user-content-address-literal)_;
After defining the (mostly) alphanumeric tokens above,
@ -809,7 +809,7 @@ token = keyword
/ symbol
```
Go to: _[keyword](#user-content-keyword), [atomic-literal](#user-content-atomic-literal), [package-name](#user-content-package-name), [annotation-name](#user-content-annotation-name), [symbol](#user-content-symbol), [format-string](#user-content-format-string), [identifier](#user-content-identifier)_;
Go to: _[symbol](#user-content-symbol), [format-string](#user-content-format-string), [package-name](#user-content-package-name), [identifier](#user-content-identifier), [keyword](#user-content-keyword), [atomic-literal](#user-content-atomic-literal), [annotation-name](#user-content-annotation-name)_;
@ -845,7 +845,7 @@ signed-type = %s"i8" / %s"i16" / %s"i32" / %s"i64" / %s"i128"
integer-type = unsigned-type / signed-type
```
Go to: _[signed-type](#user-content-signed-type), [unsigned-type](#user-content-unsigned-type)_;
Go to: _[unsigned-type](#user-content-unsigned-type), [signed-type](#user-content-signed-type)_;
The integer types, along with the field and group types,
@ -866,7 +866,7 @@ group-type = %s"group"
arithmetic-type = integer-type / field-type / group-type
```
Go to: _[integer-type](#user-content-integer-type), [field-type](#user-content-field-type), [group-type](#user-content-group-type)_;
Go to: _[integer-type](#user-content-integer-type), [group-type](#user-content-group-type), [field-type](#user-content-field-type)_;
The arithmetic types, along with the boolean and address types,
@ -887,7 +887,7 @@ address-type = %s"address"
scalar-type = boolean-type / arithmetic-type / address-type
```
Go to: _[boolean-type](#user-content-boolean-type), [arithmetic-type](#user-content-arithmetic-type), [address-type](#user-content-address-type)_;
Go to: _[boolean-type](#user-content-boolean-type), [address-type](#user-content-address-type), [arithmetic-type](#user-content-arithmetic-type)_;
Circuit types are denoted by identifiers and the keyword `Self`.
@ -904,7 +904,7 @@ self-type = %s"Self"
circuit-type = identifier / self-type
```
Go to: _[self-type](#user-content-self-type), [identifier](#user-content-identifier)_;
Go to: _[identifier](#user-content-identifier), [self-type](#user-content-self-type)_;
A tuple type consists of zero, two, or more component types.
@ -927,7 +927,7 @@ or a tuple of one or more dimensions.
array-type = "[" type ";" array-dimensions "]"
```
Go to: _[array-dimensions](#user-content-array-dimensions), [type](#user-content-type)_;
Go to: _[type](#user-content-type), [array-dimensions](#user-content-array-dimensions)_;
<a name="array-dimensions"></a>
@ -948,7 +948,7 @@ i.e. types whose values contain (sub-)values
aggregate-type = tuple-type / array-type / circuit-type
```
Go to: _[tuple-type](#user-content-tuple-type), [array-type](#user-content-array-type), [circuit-type](#user-content-circuit-type)_;
Go to: _[circuit-type](#user-content-circuit-type), [tuple-type](#user-content-tuple-type), [array-type](#user-content-array-type)_;
Scalar and aggregate types form all the types.
@ -958,7 +958,7 @@ Scalar and aggregate types form all the types.
type = scalar-type / aggregate-type
```
Go to: _[scalar-type](#user-content-scalar-type), [aggregate-type](#user-content-aggregate-type)_;
Go to: _[aggregate-type](#user-content-aggregate-type), [scalar-type](#user-content-scalar-type)_;
The lexical grammar given earlier defines product group literals.
@ -1036,7 +1036,7 @@ primary-expression = identifier
/ circuit-expression
```
Go to: _[expression](#user-content-expression), [tuple-expression](#user-content-tuple-expression), [array-expression](#user-content-array-expression), [literal](#user-content-literal), [circuit-expression](#user-content-circuit-expression), [identifier](#user-content-identifier)_;
Go to: _[expression](#user-content-expression), [array-expression](#user-content-array-expression), [identifier](#user-content-identifier), [literal](#user-content-literal), [tuple-expression](#user-content-tuple-expression), [circuit-expression](#user-content-circuit-expression)_;
Tuple expressions construct tuples.
@ -1089,7 +1089,7 @@ Go to: _[expression](#user-content-expression)_;
array-repeat-construction = "[" expression ";" array-dimensions "]"
```
Go to: _[array-dimensions](#user-content-array-dimensions), [expression](#user-content-expression)_;
Go to: _[expression](#user-content-expression), [array-dimensions](#user-content-array-dimensions)_;
<a name="array-construction"></a>
@ -1125,7 +1125,7 @@ circuit-construction = circuit-type "{"
"}"
```
Go to: _[circuit-inline-element](#user-content-circuit-inline-element), [circuit-type](#user-content-circuit-type)_;
Go to: _[circuit-type](#user-content-circuit-type), [circuit-inline-element](#user-content-circuit-inline-element)_;
<a name="circuit-inline-element"></a>
@ -1133,7 +1133,7 @@ Go to: _[circuit-inline-element](#user-content-circuit-inline-element), [circuit
circuit-inline-element = identifier ":" expression / identifier
```
Go to: _[expression](#user-content-expression), [identifier](#user-content-identifier)_;
Go to: _[identifier](#user-content-identifier), [expression](#user-content-expression)_;
<a name="circuit-expression"></a>
@ -1184,7 +1184,7 @@ postfix-expression = primary-expression
/ postfix-expression "[" [expression] ".." [expression] "]"
```
Go to: _[expression](#user-content-expression), [primary-expression](#user-content-primary-expression), [identifier](#user-content-identifier), [function-arguments](#user-content-function-arguments), [circuit-type](#user-content-circuit-type), [postfix-expression](#user-content-postfix-expression), [natural](#user-content-natural)_;
Go to: _[function-arguments](#user-content-function-arguments), [postfix-expression](#user-content-postfix-expression), [natural](#user-content-natural), [circuit-type](#user-content-circuit-type), [expression](#user-content-expression), [identifier](#user-content-identifier), [primary-expression](#user-content-primary-expression)_;
Unary operators have the highest operator precedence.
@ -1198,7 +1198,7 @@ unary-expression = postfix-expression
/ "-" unary-expression
```
Go to: _[unary-expression](#user-content-unary-expression), [postfix-expression](#user-content-postfix-expression)_;
Go to: _[postfix-expression](#user-content-postfix-expression), [unary-expression](#user-content-unary-expression)_;
Next in the operator precedence is exponentiation,
@ -1212,7 +1212,7 @@ exponential-expression = unary-expression
/ unary-expression "**" exponential-expression
```
Go to: _[unary-expression](#user-content-unary-expression), [exponential-expression](#user-content-exponential-expression)_;
Go to: _[exponential-expression](#user-content-exponential-expression), [unary-expression](#user-content-unary-expression)_;
Next in precedence come multiplication and division, both left-associative.
@ -1224,7 +1224,7 @@ multiplicative-expression = exponential-expression
/ multiplicative-expression "/" exponential-expression
```
Go to: _[exponential-expression](#user-content-exponential-expression), [multiplicative-expression](#user-content-multiplicative-expression)_;
Go to: _[multiplicative-expression](#user-content-multiplicative-expression), [exponential-expression](#user-content-exponential-expression)_;
Then there are addition and subtraction, both left-assocative.
@ -1236,7 +1236,7 @@ additive-expression = multiplicative-expression
/ additive-expression "-" multiplicative-expression
```
Go to: _[multiplicative-expression](#user-content-multiplicative-expression), [additive-expression](#user-content-additive-expression)_;
Go to: _[additive-expression](#user-content-additive-expression), [multiplicative-expression](#user-content-multiplicative-expression)_;
Next in the precedence order are ordering relations.
@ -1264,7 +1264,7 @@ equality-expression = ordering-expression
/ equality-expression "!=" ordering-expression
```
Go to: _[ordering-expression](#user-content-ordering-expression), [equality-expression](#user-content-equality-expression)_;
Go to: _[equality-expression](#user-content-equality-expression), [ordering-expression](#user-content-ordering-expression)_;
Next come conjunctive expressions, left-associative.
@ -1299,7 +1299,7 @@ conditional-expression = disjunctive-expression
":" conditional-expression
```
Go to: _[disjunctive-expression](#user-content-disjunctive-expression), [conditional-expression](#user-content-conditional-expression), [expression](#user-content-expression)_;
Go to: _[expression](#user-content-expression), [disjunctive-expression](#user-content-disjunctive-expression), [conditional-expression](#user-content-conditional-expression)_;
Those above are all the expressions.
@ -1332,7 +1332,7 @@ statement = expression-statement
/ block
```
Go to: _[constant-declaration](#user-content-constant-declaration), [variable-declaration](#user-content-variable-declaration), [console-statement](#user-content-console-statement), [block](#user-content-block), [assignment-statement](#user-content-assignment-statement), [return-statement](#user-content-return-statement), [loop-statement](#user-content-loop-statement), [conditional-statement](#user-content-conditional-statement), [expression-statement](#user-content-expression-statement)_;
Go to: _[return-statement](#user-content-return-statement), [assignment-statement](#user-content-assignment-statement), [conditional-statement](#user-content-conditional-statement), [variable-declaration](#user-content-variable-declaration), [constant-declaration](#user-content-constant-declaration), [expression-statement](#user-content-expression-statement), [loop-statement](#user-content-loop-statement), [console-statement](#user-content-console-statement), [block](#user-content-block)_;
<a name="block"></a>
@ -1361,21 +1361,31 @@ return-statement = %s"return" expression ";"
Go to: _[expression](#user-content-expression)_;
There are two kinds of variable definition statements,
There are variable declarations and constant declarations,
which only differ in the starting keyword.
The variables are either a single one or a tuple of two or more;
These declarations are also statements.
The names of the variables or constants are
either a single one or a tuple of two or more;
in all cases, there is just one optional type
and just one initializing expression.
<a name="variable-declaration"></a>
```abnf
variable-declaration = %s"let" identifier-or-identifiers [ ":" type ] "=" expression ";"
constant-declaration = %s"const" identifier-or-identifiers [ ":" type ] "=" expression ";"
variable-declaration = %s"let" identifier-or-identifiers [ ":" type ]
"=" expression ";"
```
Go to: _[identifier-or-identifiers](#user-content-identifier-or-identifiers), [type](#user-content-type), [expression](#user-content-expression)_;
<a name="constant-declaration"></a>
```abnf
constant-declaration = %s"const" identifier-or-identifiers [ ":" type ]
"=" expression ";"
```
Go to: _[expression](#user-content-expression), [identifier-or-identifiers](#user-content-identifier-or-identifiers), [type](#user-content-type)_;
<a name="identifier-or-identifiers"></a>
```abnf
@ -1397,7 +1407,7 @@ Note that blocks are required in all branches, not merely statements.
branch = %s"if" expression block
```
Go to: _[block](#user-content-block), [expression](#user-content-expression)_;
Go to: _[expression](#user-content-expression), [block](#user-content-block)_;
<a name="conditional-statement"></a>
@ -1407,7 +1417,7 @@ conditional-statement = branch
/ branch %s"else" conditional-statement
```
Go to: _[block](#user-content-block), [branch](#user-content-branch), [conditional-statement](#user-content-conditional-statement)_;
Go to: _[branch](#user-content-branch), [conditional-statement](#user-content-conditional-statement), [block](#user-content-block)_;
A loop statement implicitly defines a loop variable
@ -1419,7 +1429,7 @@ The body is a block.
loop-statement = %s"for" identifier %s"in" expression ".." expression block
```
Go to: _[expression](#user-content-expression), [block](#user-content-block), [identifier](#user-content-identifier)_;
Go to: _[expression](#user-content-expression), [identifier](#user-content-identifier), [block](#user-content-block)_;
An assignment statement is straightforward.
@ -1436,7 +1446,7 @@ assignment-operator = "=" / "+=" / "-=" / "*=" / "/=" / "**="
assignment-statement = expression assignment-operator expression ";"
```
Go to: _[expression](#user-content-expression), [assignment-operator](#user-content-assignment-operator)_;
Go to: _[assignment-operator](#user-content-assignment-operator), [expression](#user-content-expression)_;
Console statements start with the `console` keyword,
@ -1463,7 +1473,7 @@ console-call = assert-call
/ print-call
```
Go to: _[assert-call](#user-content-assert-call), [print-call](#user-content-print-call)_;
Go to: _[print-call](#user-content-print-call), [assert-call](#user-content-assert-call)_;
<a name="assert-call"></a>
@ -1505,7 +1515,7 @@ annotation = annotation-name
[ "(" identifier *( "," identifier ) ")" ]
```
Go to: _[identifier](#user-content-identifier), [annotation-name](#user-content-annotation-name)_;
Go to: _[annotation-name](#user-content-annotation-name), [identifier](#user-content-identifier)_;
A function declaration defines a function.
@ -1522,7 +1532,7 @@ function-declaration = *annotation %s"function" identifier
block
```
Go to: _[block](#user-content-block), [type](#user-content-type), [identifier](#user-content-identifier), [function-parameters](#user-content-function-parameters)_;
Go to: _[block](#user-content-block), [function-parameters](#user-content-function-parameters), [type](#user-content-type), [identifier](#user-content-identifier)_;
<a name="function-parameters"></a>
@ -1553,7 +1563,7 @@ Go to: _[function-input](#user-content-function-input)_;
function-input = [ %s"const" ] identifier ":" type
```
Go to: _[type](#user-content-type), [identifier](#user-content-identifier)_;
Go to: _[identifier](#user-content-identifier), [type](#user-content-type)_;
A circuit member variable declaration consists of an identifier and a type.
@ -1573,7 +1583,7 @@ Go to: _[member-function-declaration](#user-content-member-function-declaration)
member-variable-declaration = identifier ":" type
```
Go to: _[identifier](#user-content-identifier), [type](#user-content-type)_;
Go to: _[type](#user-content-type), [identifier](#user-content-identifier)_;
<a name="member-function-declaration"></a>
@ -1622,10 +1632,12 @@ package-path = "*"
/ "(" package-path *( "," package-path ) [","] ")"
```
Go to: _[identifier](#user-content-identifier), [package-path](#user-content-package-path), [package-name](#user-content-package-name)_;
Go to: _[package-path](#user-content-package-path), [package-name](#user-content-package-name), [identifier](#user-content-identifier)_;
Finally, we define a file as a sequence of zero or more declarations.
We allow constant declarations at the top level, for global constants.
Currently variable declarations are disallowed at the top level.
<a name="declaration"></a>
```abnf
@ -1635,7 +1647,7 @@ declaration = import-declaration
/ constant-declaration
```
Go to: _[function-declaration](#user-content-function-declaration), [import-declaration](#user-content-import-declaration), [circuit-declaration](#user-content-circuit-declaration), [constant-declaration](#user-content-constant-declaration)_;
Go to: _[import-declaration](#user-content-import-declaration), [circuit-declaration](#user-content-circuit-declaration), [constant-declaration](#user-content-constant-declaration), [function-declaration](#user-content-function-declaration)_;
<a name="file"></a>

View File

@ -845,15 +845,19 @@ expression-statement = expression ";"
return-statement = %s"return" expression ";"
; There are two kinds of variable definition statements,
; There are variable declarations and constant declarations,
; which only differ in the starting keyword.
; The variables are either a single one or a tuple of two or more;
; These declarations are also statements.
; The names of the variables or constants are
; either a single one or a tuple of two or more;
; in all cases, there is just one optional type
; and just one initializing expression.
variable-declaration = %s"let" identifier-or-identifiers [ ":" type ] "=" expression ";"
constant-declaration = %s"const" identifier-or-identifiers [ ":" type ] "=" expression ";"
variable-declaration = %s"let" identifier-or-identifiers [ ":" type ]
"=" expression ";"
constant-declaration = %s"const" identifier-or-identifiers [ ":" type ]
"=" expression ";"
identifier-or-identifiers = identifier
/ "(" identifier 1*( "," identifier ) ")"
@ -969,6 +973,8 @@ package-path = "*"
/ "(" package-path *( "," package-path ) [","] ")"
; Finally, we define a file as a sequence of zero or more declarations.
; We allow constant declarations at the top level, for global constants.
; Currently variable declarations are disallowed at the top level.
declaration = import-declaration
/ function-declaration