Merge pull request #18 from togglebyte/dev

new `either` docs

Author: togglebyte

README.md

@@ -1,3 +1,3 @@
 # Anathema guide
 
-A guide to using the Anathema TUI library.
+[The Guide](https://togglebyte.github.io/anathema-guide/) to using the Anathema TUI library.

src/SUMMARY.md

@@ -13,6 +13,7 @@
 - [Templates](./templates.md)
     - [Loops](./templates/loops.md)
     - [If / Else](./templates/if-else.md)
+    - [Either](./templates/either.md)
     - [Switch / Case](./templates/switch-case.md)
     - [With](./templates/with.md)
     - [Functions](./templates/functions.md)

src/templates.md

@@ -79,6 +79,7 @@ text "`ident` in the component attributes: " attributes.ident
 Some elements can have one or more children.
 
 Example: a border element with a text element inside
+
 ```
 border
     text "look, a border"
@@ -88,11 +89,13 @@ border
 * [If / Else](./templates/if-else.md)
 * [Switch / Case](./templates/switch-case.md)
 
-
 ## Either
 
 The `?` symbol can be used to have a fallback value.
 
+See [Either](./templates/either.md) for specifics on how this works as the
+behaviour differs between static values (defined in templates) and dynamic values (such as attributes and states).
+
 ```
 text state.maybe_value ? attributes.maybe_this ? "there was no value"
 ```

src/templates/either.md

@@ -0,0 +1,45 @@
+# Either
+
+The Either operator: `?` can be used to provide fallback values.
+
+Only dynamic values (attributes and state) are subject to truthiness
+checks; Static values (defined using `let` in a template) are never (even if they are false).
+
+```
+       Does this exist?
+       and is it truthy?
+         /  \
+        /    \
+       yes   no -------+
+        |              |
+        V              V
+text state.value ? "default"
+```
+
+## Example
+
+This will always use the static value, and print `false`:
+
+```
+text  false ? "hello"
+```
+However
+```
+text  state.maybe_false ? "hello"
+```
+
+Would print `hello` **if** `maybe_false` is any of the values in the [fallback table](./either.md#fallback-table):
+
+### Fallback table
+
+These values causes fallback.
+
+* `null`
+* `0`
+* `""`
+* `[]`
+* `{}`
+* `false`
+
+This means that any state or attribute value that resolves to a value listed
+above will use the fallback.

src/templates/switch-case.md

@@ -1 +1,14 @@
 # Switch / Case
+
+It's possible to use `switch` / `case` to determine what elements to render.
+
+The `default` branch has to be the last one, and is not required.
+
+## Example
+
+```
+switch value
+    case 1: text "one"
+    case 2: text "two"
+    default: text "default"
+```