there can now be multiple functions with the same name. The most recently declared one will be preferred if multiple would be valid.

docs/statements.md

@@ -0,0 +1,130 @@
+# mers statements overview
+
+This is the documentation for mers statements.
+In code, statements are represented by `SStatement`, `SStatementEnum`, `RStatement`, and `RStatementEnum`.
+
+## Value
+
+A statement that always returns a certain value: `10`, `"Hello, World"`, ...
+
+## Code block
+
+Code blocks are a single statement, but they can contain any number of statements.
+They have their own scope, so local variables declared in them aren't accessible from outside.
+
+They return whatever the last statement they contain returns. Empty code blocks (ones without any statements: `{}`) return `[]`.
+
+    list := [1, 2, 3, 4 ...]
+    sum := {
+      // a temporary variable that only exists in this block
+      counter := 0
+      for elem list {
+        &counter = counter + elem
+      }
+      // the final value will be returned from the block and then assigned to sum.
+      counter
+    }
+
+## Tuple and list
+
+These statements contain any number of statements and return the returned values in order as a tuple or list.
+
+    // x is a tuple and has type [int string float]
+    x := [
+      get_num(),
+      get_text(),
+      12.5
+    ]
+    // y is a list and has type [int/string/float ...]
+    x := [
+      get_num(),
+      get_text(),
+      12.5
+    ...]
+
+## Variable
+
+These statements retrieve the value from a variable name:
+
+    x := "my value"
+    println(
+      x // <- this is a variable statement - it gets the "my value" from above so the println function can use it.
+    )
+
+They can also get references if the variable name is prefixed with the `&` symbol:
+
+    debug(&x) // type is &string
+
+This is why `&` is required to assign to a variable:
+
+    x = "something else" // can't assign to string!
+    &x = "something else" // only data behind references can be changed - we can assign to &string.
+
+## Function call
+
+Function calls give some data to a function and return the result from that function.
+
+There are 3 kinds of function calls:
+
+- calls to builtin functions
+- calls to library functions
+- calls to custom functions
+
+Anonymous functions are called using the builtin `run` function.
+
+## If statement
+
+Allow for conditional execution of code paths:
+
+    if condition() {
+      // do something
+    }
+
+    if condition() {
+      // do something
+    } else {
+      // do something else
+    }
+
+## Loop
+
+Executes code repeatedly:
+
+    counter := 0
+    loop {
+      &counter = counter + 1
+      println("c: " + counter.to_string())
+    }
+
+## For loop
+
+## Switch
+
+## Match
+
+## Enum
+
+Wrap a value in an enum: `EnumName: <statement>`
+
+# dot-chains
+
+Statements can be followed by the dot `.` character. This has different meanings depending on what comes after the dot:
+
+## A function call
+
+In this case, the statement before the dot is prepended to the function arguments:
+
+    a.func(b, c)
+    func(a, b, c)
+
+## An integer
+
+Gets the n-th thing from a tuple (uses zero-based indexing):
+
+    [1, "2", 3.0].1 == "2"
+
+If the value before the dot is a reference to a tuple, a reference to the thing inside the tuple will be obtained:
+
+    x := [1, "2", 3.0]
+    // we assign to the "2", which changes it.
+    &x.1 = "4"