document functions, break template docs into smaller parts

Author: togglebyte

src/SUMMARY.md

@@ -3,8 +3,6 @@
 - [Introduction](./introduction.md)
 - [Getting started](./getting-started.md)
 - [Components](./components.md)
-    %% - [User model](./templates/usermodel.md)
-    %% - [Data Context](./templates/data-ctx.md)
     - [State](./components/state.md)
     - [Event handling](./components/events.md)
     - [Messaging](./components/messages.md)
@@ -13,6 +11,11 @@
 - [Runtime](./runtime.md)
 - [Backend](./backend.md)
 - [Templates](./templates.md)
+    - [Loops](./templates/loops.md)
+    - [If / Else](./templates/if-else.md)
+    - [Switch / Case](./templates/switch-case.md)
+    - [Functions](./templates/functions.md)
+        - [Custom functions](./templates/functions/custom.md)
     - [Elements](./templates/elements.md)
         - [text](./templates/elements/text.md)
         - [span](./templates/elements/span.md)

src/introduction.md

@@ -11,6 +11,9 @@ By separating the layout from the rest of the application, reducing the amount o
 code needed to express your design, and featuring hot reloading it becomes incredibly fast 
 to iterate over the design.
 
+Do note that AML is a markup language with some basic control flow and is not a
+reactive programming language.
+
 ## Why
 
 * Templates can be shipped with the application, giving the end user the ability

src/templates.md

@@ -4,6 +4,9 @@ Anathema has a template language to describe user interfaces.
 This makes it possible to ship the template(s) together with the compiled binary so the
 application can be customised without having to be recompiled.
 
+Do note that AML (Anathema Markup Language) is **not** a programming language,
+therefore control flow is limited.
+
 The element syntax looks as follows: `<element> <attributes> <value>`
 
 ```
@@ -81,128 +84,55 @@ border
     text "look, a border"
 ```
 
-## Loops
-
-It's possible to loop over the elements of a collection.
-The syntax for loops are `for <element> in <collection>`.
-
-Example: looping over static values
-```
-for value in [1, 2, "hello", 3]
-    text value
-```
+* [Loops](./templates/loops.md)
+* [If / Else](./templates/if-else.md)
+* [Switch / Case](./templates/switch-case.md)
 
-Elements generated by the loop can be thought of as belonging to the parent
-element as the loop it self is not a element.
-See example below.
 
-Example: mixing loops and elements
-```
-vstack
-    text "start"
-    for val in [1, 2, 3]
-        text "some value: " val "."
-    text "end"
-```
-The above example would render:
-```
-start
-some value: 1.
-some value: 2.
-some value: 3.
-end
-```
+## Either
 
-For-loops also expose a `loop` variable that is set to the current loop iteration.
+The `?` symbol can be used to have a fallback value.
 
-Example: `loop` variable
 ```
-vstack
-    for val in ["a", "b", "c", "d"]
-        text "#" loop ": " val
-```
-The above example would render:
-```
-#0: a
-#1: b
-#2: c
-#3: d
+text state.maybe_value ? attributes.maybe_this ? "there was no value"
 ```
 
-Note: For-loops do not work inside attributes, and can only produce
-elements.
+## Constants / Globals
 
-## If / Else
+Constants are global and regardless of where in a template they are declared
+they will be hoisted to the top.
 
-It's possible to use `if` and `else` to determine what to layout.
+### Example
 
-Example:
-```
-if true
-    text "It's true!"
-    
-if value > 10
-    text "Larger than ten"
-else if value > 5
-    text "Larger than five but less than ten"
-else
-    text "It's a small value..."
+The following example will print `1`
 ```
+text glob
 
-### Conditional theming
-
-Changing colors and style depending on a condition can be achieved by declaring
-a constant. All constants are global.
-
+let glob = 1
 ```
-let THEME = {
-    enabled: { bg: "grey" },
-    disabled: { bg: "reset" },
-}
 
-text [background: THEME["disabled"].bg] "Hello, tea"
+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
 
-Since boolean values can translate to numbers it's also possible to use
-them as index lookups.
-
+// inner.aml
+let glob = 2
+text glob
 ```
-let THEME = [
-    // False
-    { bg: "grey" },
-    // True
-    { bg: "reset" },
-]
 
-text [background: THEME[state.some_bool].bg] "Hello, tea"
+The following example will print `2`, as the `inner` component will override the
+outer components global.
 ```
+// main.aml
+let glob = glob
+@inner
 
-### Operators
-
-* Equality `==` 
-* Greater than `>`
-* Greater than or equals `>=`
-* Less than `<`
-* Less than or equals `<=`
-* And `&&`
-* Or `||`
-* Addition `+`
-* Subtraction `-`
-* Multiplication `*`
-* Division `/`
-* Remainder (Modulo) `%`
-* Negation `!`
-* Either `?` (Uses the right value if the left value does not exist)
-
-Note: just like for-loops it's not possible to use if / else with attributes.
-
-To determine the value of an attribute depending on some condition this should
-be handled by the state.
-
-## Either
-
-The `?` symbol can be used to have a fallback value.
-
-```
-text state.maybe_value ? attributes.maybe_this ? "there was no value"
+// inner.aml
+let glob = 2
+text glob
 ```

src/templates/functions.md

@@ -0,0 +1,117 @@
+# Functions
+
+AML have a few functions built-in and it's possible to add custom functions.
+
+A function can either be called as a member function: `"string".to_upper()` or a
+free function: `to_upper("string")`
+
+Do note that calling a function as a member function on a collection
+
+## `to_upper(string)`
+
+Convert a string to upper case.
+
+### Example
+
+```
+text "It's teatime".to_upper()
+```
+
+Will output: "IT'S TEATIME".
+
+## `to_lower(string)`
+
+Convert a string to lower case.
+
+### Example
+
+```
+text "It's teatime".to_lower()
+```
+
+Will output: "it's teatime".
+
+## `to_str(arg)`
+
+Convert any value to a string representation.
+
+### Example
+
+```
+let greetings = {
+    "1": "Hello",
+    "2": "Hi",
+}
+
+text greetings[to_str(2)]
+```
+
+Will output: "Hi".
+
+## `to_int(arg)`
+
+Try to convert any value to an integer.
+
+Boolean `true` will convert to `1`, and `false` will convert to `0`.
+
+Floating point values will be truncated. 
+`to_int(1.99999)` will be converted to `1`.
+
+### Example
+
+```
+let greetings = [
+    "Hello",
+    "Hi",
+]
+
+text greetings[to_int(true)]
+```
+
+Will output: "Hi".
+
+## `round(number, decimal_count=0)`
+
+Round a floating point value. 
+Trying to round any other type will return null.
+
+If no `decimal_count` is provided `0` is the default.
+
+### Example
+
+```
+vstack
+    text round(1.1234, 2)
+    text round(1.1234)
+```
+
+Will output: 
+```
+1.12
+1
+```
+
+This function will pad with zeroes:
+```
+    text round(1.12, 5)
+```
+
+Will output: `1.12000`
+
+## `contains(haystack, needle)`
+
+Returns true if the haystack contains the needle.
+
+### Example
+
+```
+vstack
+    text contains([1, 2, 3], 2)
+    text "hello world".contains("lo")
+```
+
+Will output: 
+```
+true
+true
+```

src/templates/functions/custom.md

@@ -0,0 +1,48 @@
+# Adding custom functions
+
+It's possible to add custom functions to the runtime.
+
+All function have the same signature in Rust:
+
+```rust, ignore
+fn contains<'a>(args: &[ValueKind<'a>]) -> ValueKind<'a> {
+    ... 
+}
+```
+
+## Example
+
+A function that adds two values
+
+```rust, ignore
+use anathema::resolver::ValueKind;
+
+fn add<'a>(args: &[ValueKind<'a>]) -> ValueKind<'a> {
+    if args.len() != 2 {
+        return ValueKind::Null;
+    }
+    
+    let args = args[0].to_int().zip(args[1].to_int());
+    match args {
+        Some((lhs, rhs)) => ValueKind::Int(lhs + rhs),
+        None => ValueKind::Null
+    }
+}
+```
+
+## Adding the function to the runtime
+
+Use the `register_function` method on the runtime to add your custom function.
+
+It is not possible to overwrite existing functions, and trying to do so will
+return an error.
+
+### Example 
+
+```rust,ignore
+builder.register_function("add", add).unwrap();
+```
+In the template:
+```
+text add(1, 2)
+```