[PATCH] fixup! docs: spec: add variables and constants specification

[ricardo_kagawa@disroot.org]

From: Ricardo Kagawa <ricardo_kagawa@disroot.org>

> subject to semantic checks. Attempting to bypass these checks to
> reassign a global constant will result in a segmentation fault
> (SEGFAULT) and will be accepted at the function level.

I would be careful with the wording here. Are you absolutely sure you
can enforce this rule in case of a bypass attempt? If not, use something
like "should" or "may" instead of "will".

In the current version of the specification, it would be impossible to
bypass the `const` check, and it would be possible to enforce it at
compile-time. But depending on what you are planning to add to the
language, it might become impossible to do so later.

> Since this patch adds support to assignments, lets also add support to
> all assignment operators like "-=" "+=" "<<=" and so on.

I disagree. Support for those assignment operators should only be added
when both assignments and operators are defined, and none of these
operators are defined yet.

> This patch lacks support to the following valid assignment expression
> (which I think adds flexibility to the language):
> 
>     var x: u32 = a = b = c = 1

Personally, I don't like this idiom, but I wouldn't stop you from adding
it. Johnny's patch actually already enables this, and also the
following (for clarity, of course the `if` statement does not exist yet,
but it is included here as an example of what might come in the future):

```
var x
if (x = next()) {
  return x
}
```

Which is something I don't like either, just as much.

> > > We don't need to define twice the variable-definition for "var" and
> > > "const", let's combine both in a single rule.
> > 
> > I don't know if you noticed, but variables has an optional assignment
> > while const has required assignment.
> 
> Sure, I noticed.  I took a look to how C solve this problem and seems
> like it allows defining a const without assignment  (I don't know why...).
> 
> I would do the same to keep the gramma simple. And if we really want to
> advice the developer about weird declaration, we could warning message
> during semantics checking phase.

I agree with Carlos, unless you have plans to allow constants to be
initialized later (or not even initialized), which I don't like.

I don't know what your plans for the future are, but in the case of the
C language, I guess they didn't have a choice but allow for
uninitialized constants. The compiler can validate the immutability of
the constant, _as long as it is strictly accessed through its binding_.

But the C language allows for pointer arithmetics and inline assembly,
which allows the program to access memory positions in other ways
besides references to the variable name. So the immutability of `const`
variables is not a hard guarantee, but more like an advice, in this
case.

The compiler simply cannot make that many assumptions on what pointers
point to, or where your assembly code writes things to. This is so bad
that in legacy operating systems, it was possible to override kernel
instructions, as long as you knew where they were in the physical
memory.

In modern operating systems, processes never have access to physical
memory addresses, but they still have full access to their own memory.
In other words, a pointer can still mutate constant variables, and even
literal values in instructions (or the instructions themselves, which
means macros are not immune to mutation either).

Other languages can make stronger assumptions about constant variables,
as they do not allow for direct memory manipulation.

So, in my opinion, the decision should hinge on the compiler's ability
to properly validate the constant's immutability, and whether or not
late initialization should be allowed (complicating semantic checks).

> I believe we may need two non-terminals, one for assignment which is
> just the '=' and other for reassignments.

I sort of agree here. But I guess the non-terminal names are bit
confusing. The `=` sign in `const` and `var` declarations is _not_ an
assignment operation, but declares an initializer. The semantics are
subtly different, but still different, so assignment operators should
not be allowed in variable/constant declarations.

---
Discussions:

- Are you planning to hoist declarations, or are declarations required
  to be placed before their use?
- Are you planning to include type inference for variable declarations?
  If so, the variable type in variable and constant declarations could
  be made optional.

-- >8 --

- Moved statements common to the translation unit and function bodies to
  their own non-terminal.
- Restored Carlos' definition of variable and constant definitions, as
  they are not quite the same, structurally and semantically.
  Personally, I'd rather constants to be initialized immediately, but
  you may have a different opinion on this.
- Moved some non-terminals from the "Statements" section to the
  "Functions" section, as there will be some statements that are
  function-body specific, some that are translation-unit specific, and
  some that are common to both.
- Renamed "assign" to "assignment", for better wording.
- Renamed <variable-assign> from Carlos' patch to
  <variable-initializer> (must not be used in <assignment-expression>).

Signed-off-by: Ricardo Kagawa <ricardo_kagawa@disroot.org>
---
 docs/pages/language-specification.md | 36 ++++++++++------------------
 1 file changed, 13 insertions(+), 23 deletions(-)

diff --git a/docs/pages/language-specification.md b/docs/pages/language-specification.md
index 2650dd9..b218462 100644
--- a/docs/pages/language-specification.md
+++ b/docs/pages/language-specification.md
@@ -24,15 +24,14 @@ language.
 (* Entry Point *)
 <translation-unit>     ::= (<ows> <external-declaration> <ows> (<end-of-statement> | <end-of-file>))*
 
-<external-declaration> ::= <function-definition> 
-                         | <variable-definition>
-                         | <assign-expression>
+(* Translation Unit *)
+<external-declaration>  ::= <common-statement> | <function-definition>
 
 (* Variables *)
-<variable-definition>  ::= <variable-qualifier> <ws> <variable-name> <ows> ':' <ows> <type> (<ows> <assign-operator> <ows> <expression>)?
-<variable-qualifier>   ::= 'var'
-                         | 'const'
-<variable-name>        ::= <identifier>
+<variable-definition>   ::= 'var' <ws> <variable-name> <ows> ':' <ows> <type> <ows> <variable-initializer>?
+<const-definition>      ::= 'const' <ws> <variable-name> <ows> ':' <ows> <type> <ows> <variable-initializer>
+<variable-name>         ::= <identifier>
+<variable-initializer>  ::= '=' <ows> <expression>
 
 (* Functions *)
 <function-definition> ::= 'fn' <ws> <function-name> <ows> <function-parameters> <ows> ':' <ows> <return-type> <ows> <function-body>
@@ -40,27 +39,18 @@ language.
 <function-parameters> ::= '(' <ows> ')'
 <return-type>         ::= <type>
 <function-body>       ::= <block>
+<block>               ::= '{' <ows> <statement> <ows> (<end-of-statement> <ows> <statement> <ows>)* <end-of-statement>? <ows> '}'
+<statement>           ::= <common-statement> | <return-statement>
+<return-statement>    ::= 'return' <ws> <expression>
 
 (* Statements *)
-<block>               ::= '{' <ows> <statement> <ows> (<end-of-statement> <ows> <statement> <ows>)* <end-of-statement>? <ows> '}'
 <end-of-statement>    ::= ';' | <line-break>
-<statement>           ::= <return-statement> | <variable-definition> | <assign-expression>
-<return-statement>    ::= 'return' <ws> <expression>
+<common-statement>    ::= <variable-definition> | <const-definition> | <assignment-expression>
 
 (* Expressions *)
-<expression>          ::= <integer> | <identifier> | <assign-expression>
-<assign-expression>   ::= <variable-name> <ows> <assign-operator> <ows> <expression>
-<assign-operator>     ::= '='
-                        | '*='
-                        | '/='
-                        | '%='
-                        | '+='
-                        | '-='
-                        | '<<='
-                        | '>>='
-                        | '&='
-                        | '^='
-                        | '|='
+<expression>            ::= <integer> | <variable-name> | <assignment-expression>
+<assignment-expression> ::= <variable-name> <ows> <assignment-operator> <ows> <expression>
+<assignment-operator>   ::= '='
 
 (* Identifiers *)
 <type>                ::= 'u32'
-- 
2.44.0