Merge pull request #27 from togglebyte/dev

document locals and globals

Author: togglebyte

src/SUMMARY.md

@@ -16,6 +16,7 @@
     - [Either](./templates/either.md)
     - [Switch / Case](./templates/switch-case.md)
     - [With](./templates/with.md)
+    - [Variables](./templates/variables.md)
     - [Functions](./templates/functions.md)
         - [Custom functions](./templates/functions/custom.md)
     - [Elements](./templates/elements.md)

src/templates.md

@@ -99,43 +99,3 @@ behaviour differs between static values (defined in templates) and dynamic value
 ```
 text state.maybe_value ? attributes.maybe_this ? "there was no value"
 ```
-
-## Constants / Globals
-
-Constants are global and regardless of where in a template they are declared
-they will be hoisted to the top.
-
-### Example
-
-The following example will print `1`
-```
-text glob
-
-let glob = 1
-```
-
-The following example will print `1` then `2`, as the `inner` component will override the
-outer components global.
-```
-// main.aml
-let glob = 1
-vstack
-    text glob
-    @inner
-
-// inner.aml
-let glob = 2
-text glob
-```
-
-The following example will print `2`, as the `inner` component will override the
-outer components global.
-```
-// main.aml
-let glob = glob
-@inner
-
-// inner.aml
-let glob = 2
-text glob
-```

src/templates/variables.md

@@ -0,0 +1,76 @@
+# Variables
+
+Template variables are closer to constants than variables, since they can not be reassigned.
+
+There are two kinds: 
+* Global
+* Local
+
+A local value will always shadow a global value with the same name, and `with` / `for` will always shadow local values.
+
+## Global
+
+Globals are defined using the `global` keyword: `global <ident> = <expression>`.
+
+Once a global is defined it can not be re-defined.
+Trying to define a global twice will result in an error.
+
+### Example
+
+```
+global value = 1
+text value
+```
+
+### Notes 
+
+Global values can be defined anywhere in the template, but it's best practice to
+place them at the to of the template.
+
+## Local
+
+<small><i>The old `let` keyword is now an alias for `local`.</i></small>
+
+Locals are defined using the `local` keyword: `local <ident> = <expression>`.
+
+A `local` value is never accessible outside the current component, and is scoped
+to the parent element.
+
+### Example
+
+```
+local value = 1
+text value
+```
+
+### Notes
+
+Unlike `global`s the placement within the template is relevant for `local`s.
+
+The following will display `1`:
+```
+local x = 1
+vstack
+    text x
+```
+
+The following template
+
+```
+local x = 1
+vstack
+    text x
+    vstack
+        local x = 2
+        text x
+    text x
+```
+
+will display
+
+```
+1
+2
+1
+```
+