[PATCH olang v1 2/2] docs: spec: add variables and constants specification

[Carlos Maniero <carlos@maniero.me>]

This commit introduces the specification for variables and constants. A
valid program under this specification is as follows:

  var x: u32 = 1
  const y: u32 = 2
  x = 2

  fn main(): u32 {
    var x: u32 = 1; const y: u32 = 2
    return x
  }

Variables and Linkage:
----------------------

Variables can be defined globally or within a function. Variables
defined globally are added to the *.data* section. On the other hand,
variables defined within a function utilize the stack. Currently, the
specification does not provide a keyword for external linkage yet, hence
variables cannot be accessed outside their translation unit.

Constants and Linkage:
----------------------

Constants behave similarly to variables. Constants defined at the file
level are added to the *.rodata* section. Constants within functions are
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.

Example of bypassing semantic checks in C:

  int a = 1;
  const int b = 2;
  int *c = &a + 1;
  *c = 3;
  assert(b == 3); // its true

Static variables in function level
----------------------------------

In C, static variables can be defined within the scope of a function.
These variables are added to the `*.data*` segment and are only
accessible within the function where they are defined. This is a unique
behavior of C that some might find unusual.

However, olang does not support this feature. In olang, if you need a
variable that retains its value across function calls (like a static
variable in C), you must define it at the file level.

Signed-off-by: Carlos Maniero <carlos@maniero.me>
---
 docs/pages/language-specification.md | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/docs/pages/language-specification.md b/docs/pages/language-specification.md
index 4541ba8..708b679 100644
--- a/docs/pages/language-specification.md
+++ b/docs/pages/language-specification.md
@@ -24,7 +24,15 @@ language.
 (* Entry Point *)
 <translation-unit>    ::= <ows> (<global-statements> <end-of-statement>)*
 
-<global-statements>   ::= <function-definition>
+<global-statements>   ::= <function-definition> | <variable-definition> | <variable-reassign> | <const-definition>
+
+(* Variables *)
+<variable-definition> ::= 'var' <ws> <variable-name> <ows> ':' <ows> <type> <ows> <variable-assign>?
+<const-definition>    ::= 'const' <ws> <variable-name> <ows> ':' <ows> <type> <ows> <variable-assign>
+
+<variable-name>       ::= <identifier>
+<variable-assign>     ::= '=' <ows> <expression>
+<variable-reassign>   ::= <variable-name> <ows> <variable-assign> <end-of-statement>
 
 (* Functions *)
 <function-definition> ::= 'fn' <ws> <function-name> <ows>
@@ -38,11 +46,11 @@ language.
 <block>               ::= '{' <ows> <statement> <ows> (<end-of-statement>
 <ows> <statement> <ows>)* <end-of-statement>? <ows> '}'
 <end-of-statement>    ::= ';' | <line-break> | <end-of-file>
-<statement>           ::= <return-statement>
+<statement>           ::= <return-statement> | <variable-definition> | <variable-reassign> | <const-definition>
 <return-statement>    ::= 'return' <ws> <expression>
 
 (* Expressions *)
-<expression>          ::= <integer>
+<expression>          ::= <integer> | <identifier>
 
 (* Identifiers *)
 <type>                ::= 'u32'
-- 
2.34.1