From 08821005264fe436cd2a594b77f6716eae8631cd Mon Sep 17 00:00:00 2001 From: Alessandro Coglio Date: Tue, 27 Apr 2021 22:45:27 -0700 Subject: [PATCH] [ABNF] Trim some documentation. The removed text is more of an internal discussion that actual documentation, so it seems best to keep things slightly more concise. --- grammar/README.md | 88 ++++++++++++++-------------------------- grammar/abnf-grammar.txt | 16 -------- 2 files changed, 30 insertions(+), 74 deletions(-) diff --git a/grammar/README.md b/grammar/README.md index 7d5fe66a6c..d89cbb700b 100644 --- a/grammar/README.md +++ b/grammar/README.md @@ -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)_; @@ -521,7 +521,7 @@ rest-of-block-comment-after-star = "/" / not-star-or-slash rest-of-block-comment ``` -Go to: _[rest-of-block-comment](#user-content-rest-of-block-comment), [not-star-or-slash](#user-content-not-star-or-slash), [rest-of-block-comment-after-star](#user-content-rest-of-block-comment-after-star)_; +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)_; @@ -596,7 +596,7 @@ lowercase-letter = %x61-7A ; a-z letter = uppercase-letter / lowercase-letter ``` -Go to: _[uppercase-letter](#user-content-uppercase-letter), [lowercase-letter](#user-content-lowercase-letter)_; +Go to: _[lowercase-letter](#user-content-lowercase-letter), [uppercase-letter](#user-content-uppercase-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-close-brace](#user-content-not-double-quote-or-close-brace), [format-string-container](#user-content-format-string-container), [not-double-quote-or-open-brace](#user-content-not-double-quote-or-open-brace)_; +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)_; @@ -764,7 +764,7 @@ atomic-literal = untyped-literal / address-literal ``` -Go to: _[signed-literal](#user-content-signed-literal), [field-literal](#user-content-field-literal), [product-group-literal](#user-content-product-group-literal), [unsigned-literal](#user-content-unsigned-literal), [untyped-literal](#user-content-untyped-literal), [boolean-literal](#user-content-boolean-literal), [address-literal](#user-content-address-literal)_; +Go to: _[unsigned-literal](#user-content-unsigned-literal), [address-literal](#user-content-address-literal), [field-literal](#user-content-field-literal), [boolean-literal](#user-content-boolean-literal), [untyped-literal](#user-content-untyped-literal), [signed-literal](#user-content-signed-literal), [product-group-literal](#user-content-product-group-literal)_; After defining the (mostly) alphanumeric tokens above, @@ -780,34 +780,6 @@ even though it includes letters, it seems appropriate to still consider it a symbol, particularly since it starts with a proper symbol. -We could give names to all of these symbols, -via rules such as - - - -``` -equality-operator = "==" -``` - - - -and defining `symbol` in terms of those - - - -``` -symbol = ... / equality-operator / ... -``` - - - -This may or may not make the grammar more readable, -but it would help establish a terminology in the grammar, -namely the exact names of some of these token. -On the other hand, at least some of them are perhaps simple enough -that they could be just described in terms of their symbols, -e.g. double dot, question mark, etc. - ```abnf symbol = "!" / "&&" / "||" @@ -837,7 +809,7 @@ token = keyword / symbol ``` -Go to: _[package-name](#user-content-package-name), [format-string](#user-content-format-string), [symbol](#user-content-symbol), [identifier](#user-content-identifier), [atomic-literal](#user-content-atomic-literal), [annotation-name](#user-content-annotation-name), [keyword](#user-content-keyword)_; +Go to: _[annotation-name](#user-content-annotation-name), [symbol](#user-content-symbol), [format-string](#user-content-format-string), [identifier](#user-content-identifier), [keyword](#user-content-keyword), [package-name](#user-content-package-name), [atomic-literal](#user-content-atomic-literal)_; @@ -873,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, @@ -894,7 +866,7 @@ group-type = %s"group" arithmetic-type = integer-type / field-type / group-type ``` -Go to: _[group-type](#user-content-group-type), [field-type](#user-content-field-type), [integer-type](#user-content-integer-type)_; +Go to: _[field-type](#user-content-field-type), [integer-type](#user-content-integer-type), [group-type](#user-content-group-type)_; The arithmetic types, along with the boolean and address types, @@ -915,7 +887,7 @@ address-type = %s"address" scalar-type = boolean-type / arithmetic-type / address-type ``` -Go to: _[address-type](#user-content-address-type), [arithmetic-type](#user-content-arithmetic-type), [boolean-type](#user-content-boolean-type)_; +Go to: _[arithmetic-type](#user-content-arithmetic-type), [boolean-type](#user-content-boolean-type), [address-type](#user-content-address-type)_; Circuit types are denoted by identifiers and the keyword `Self`. @@ -955,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)_; @@ -976,7 +948,7 @@ i.e. types whose values contain (sub-)values aggregate-type = tuple-type / array-type / circuit-type ``` -Go to: _[array-type](#user-content-array-type), [circuit-type](#user-content-circuit-type), [tuple-type](#user-content-tuple-type)_; +Go to: _[circuit-type](#user-content-circuit-type), [array-type](#user-content-array-type), [tuple-type](#user-content-tuple-type)_; Scalar and aggregate types form all the types. @@ -986,7 +958,7 @@ Scalar and aggregate types form all the types. type = scalar-type / aggregate-type ``` -Go to: _[aggregate-type](#user-content-aggregate-type), [scalar-type](#user-content-scalar-type)_; +Go to: _[scalar-type](#user-content-scalar-type), [aggregate-type](#user-content-aggregate-type)_; The lexical grammar given earlier defines product group literals. @@ -1045,7 +1017,7 @@ of operators and other expression constructs, and the (left or right) associativity of binary operators. The primary expressions are self-contained in a way, -i.e. they have clear deliminations: +i.e. they have clear delimitations: Some consist of single tokens, while others have explicit endings. Primary expressions also include parenthesized expressions, @@ -1064,7 +1036,7 @@ primary-expression = identifier / circuit-expression ``` -Go to: _[array-expression](#user-content-array-expression), [identifier](#user-content-identifier), [expression](#user-content-expression), [literal](#user-content-literal), [tuple-expression](#user-content-tuple-expression), [circuit-expression](#user-content-circuit-expression)_; +Go to: _[tuple-expression](#user-content-tuple-expression), [circuit-expression](#user-content-circuit-expression), [array-expression](#user-content-array-expression), [expression](#user-content-expression), [literal](#user-content-literal), [identifier](#user-content-identifier)_; Tuple expressions construct tuples. @@ -1117,7 +1089,7 @@ Go to: _[expression](#user-content-expression)_; array-repeat-construction = "[" expression ";" array-dimensions "]" ``` -Go to: _[expression](#user-content-expression), [array-dimensions](#user-content-array-dimensions)_; +Go to: _[array-dimensions](#user-content-array-dimensions), [expression](#user-content-expression)_; @@ -1125,7 +1097,7 @@ Go to: _[expression](#user-content-expression), [array-dimensions](#user-content array-construction = array-inline-construction / array-repeat-construction ``` -Go to: _[array-repeat-construction](#user-content-array-repeat-construction), [array-inline-construction](#user-content-array-inline-construction)_; +Go to: _[array-inline-construction](#user-content-array-inline-construction), [array-repeat-construction](#user-content-array-repeat-construction)_; @@ -1212,7 +1184,7 @@ postfix-expression = primary-expression / postfix-expression "[" [expression] ".." [expression] "]" ``` -Go to: _[identifier](#user-content-identifier), [function-arguments](#user-content-function-arguments), [natural](#user-content-natural), [circuit-type](#user-content-circuit-type), [primary-expression](#user-content-primary-expression), [postfix-expression](#user-content-postfix-expression), [expression](#user-content-expression)_; +Go to: _[function-arguments](#user-content-function-arguments), [identifier](#user-content-identifier), [circuit-type](#user-content-circuit-type), [postfix-expression](#user-content-postfix-expression), [primary-expression](#user-content-primary-expression), [natural](#user-content-natural), [expression](#user-content-expression)_; Unary operators have the highest operator precedence. @@ -1240,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. @@ -1264,7 +1236,7 @@ additive-expression = multiplicative-expression / additive-expression "-" multiplicative-expression ``` -Go to: _[additive-expression](#user-content-additive-expression), [multiplicative-expression](#user-content-multiplicative-expression)_; +Go to: _[multiplicative-expression](#user-content-multiplicative-expression), [additive-expression](#user-content-additive-expression)_; Next in the precedence order are ordering relations. @@ -1314,7 +1286,7 @@ disjunctive-expression = conjunctive-expression / disjunctive-expression "||" conjunctive-expression ``` -Go to: _[conjunctive-expression](#user-content-conjunctive-expression), [disjunctive-expression](#user-content-disjunctive-expression)_; +Go to: _[disjunctive-expression](#user-content-disjunctive-expression), [conjunctive-expression](#user-content-conjunctive-expression)_; Finally we have conditional expressions. @@ -1359,7 +1331,7 @@ statement = expression-statement / block ``` -Go to: _[return-statement](#user-content-return-statement), [loop-statement](#user-content-loop-statement), [assignment-statement](#user-content-assignment-statement), [expression-statement](#user-content-expression-statement), [console-statement](#user-content-console-statement), [block](#user-content-block), [conditional-statement](#user-content-conditional-statement), [variable-definition-statement](#user-content-variable-definition-statement)_; +Go to: _[expression-statement](#user-content-expression-statement), [return-statement](#user-content-return-statement), [conditional-statement](#user-content-conditional-statement), [loop-statement](#user-content-loop-statement), [assignment-statement](#user-content-assignment-statement), [variable-definition-statement](#user-content-variable-definition-statement), [console-statement](#user-content-console-statement), [block](#user-content-block)_; @@ -1401,7 +1373,7 @@ variable-definition-statement = ( %s"let" / %s"const" ) [ ":" type ] "=" expression ";" ``` -Go to: _[type](#user-content-type), [identifier-or-identifiers](#user-content-identifier-or-identifiers), [expression](#user-content-expression)_; +Go to: _[identifier-or-identifiers](#user-content-identifier-or-identifiers), [type](#user-content-type), [expression](#user-content-expression)_; @@ -1424,7 +1396,7 @@ Note that blocks are required in all branches, not merely statements. branch = %s"if" expression block ``` -Go to: _[expression](#user-content-expression), [block](#user-content-block)_; +Go to: _[block](#user-content-block), [expression](#user-content-expression)_; @@ -1434,7 +1406,7 @@ conditional-statement = branch / branch %s"else" conditional-statement ``` -Go to: _[block](#user-content-block), [conditional-statement](#user-content-conditional-statement), [branch](#user-content-branch)_; +Go to: _[branch](#user-content-branch), [block](#user-content-block), [conditional-statement](#user-content-conditional-statement)_; A loop statement implicitly defines a loop variable @@ -1446,7 +1418,7 @@ The body is a block. loop-statement = %s"for" identifier %s"in" expression ".." expression block ``` -Go to: _[block](#user-content-block), [expression](#user-content-expression), [identifier](#user-content-identifier)_; +Go to: _[block](#user-content-block), [identifier](#user-content-identifier), [expression](#user-content-expression)_; An assignment statement is straightforward. @@ -1463,7 +1435,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, @@ -1519,7 +1491,7 @@ Go to: _[format-string](#user-content-format-string)_; print-call = print-function print-arguments ``` -Go to: _[print-arguments](#user-content-print-arguments), [print-function](#user-content-print-function)_; +Go to: _[print-function](#user-content-print-function), [print-arguments](#user-content-print-arguments)_; An annotation consists of an annotation name (which starts with `@`) @@ -1549,7 +1521,7 @@ function-declaration = *annotation %s"function" identifier block ``` -Go to: _[type](#user-content-type), [block](#user-content-block), [identifier](#user-content-identifier), [function-parameters](#user-content-function-parameters)_; +Go to: _[type](#user-content-type), [block](#user-content-block), [function-parameters](#user-content-function-parameters), [identifier](#user-content-identifier)_; @@ -1592,7 +1564,7 @@ member-declaration = member-variable-declaration / member-function-declaration ``` -Go to: _[member-variable-declaration](#user-content-member-variable-declaration), [member-function-declaration](#user-content-member-function-declaration)_; +Go to: _[member-function-declaration](#user-content-member-function-declaration), [member-variable-declaration](#user-content-member-variable-declaration)_; @@ -1661,7 +1633,7 @@ declaration = import-declaration / circuit-declaration ``` -Go to: _[function-declaration](#user-content-function-declaration), [circuit-declaration](#user-content-circuit-declaration), [import-declaration](#user-content-import-declaration)_; +Go to: _[function-declaration](#user-content-function-declaration), [import-declaration](#user-content-import-declaration), [circuit-declaration](#user-content-circuit-declaration)_; diff --git a/grammar/abnf-grammar.txt b/grammar/abnf-grammar.txt index 672ee27239..847aba2ffa 100644 --- a/grammar/abnf-grammar.txt +++ b/grammar/abnf-grammar.txt @@ -533,22 +533,6 @@ atomic-literal = untyped-literal ; it seems appropriate to still consider it a symbol, ; particularly since it starts with a proper symbol. -; We could give names to all of these symbols, -; via rules such as -; -; equality-operator = "==" -; -; and defining `symbol` in terms of those -; -; symbol = ... / equality-operator / ... -; -; This may or may not make the grammar more readable, -; but it would help establish a terminology in the grammar, -; namely the exact names of some of these token. -; On the other hand, at least some of them are perhaps simple enough -; that they could be just described in terms of their symbols, -; e.g. double dot, question mark, etc. - symbol = "!" / "&&" / "||" / "==" / "!=" / "<" / "<=" / ">" / ">="