From 09b85d4e07984c7453e34585d829757f0c83cff8 Mon Sep 17 00:00:00 2001
From: s-ol <s-ol@users.noreply.github.com>
Date: Fri, 8 Jan 2021 17:03:59 +0100
Subject: add reference/arrays and reference/structs

---
 docs/reference/04-2_pure-operators.md | 31 +++++++++++++++++--------------
 docs/reference/05-1_arrays.md         | 11 +++++++++++
 docs/reference/05-2_structs.md        | 16 ++++++++++++++++
 docs/reference/index.md               |  6 ++----
 4 files changed, 46 insertions(+), 18 deletions(-)
 create mode 100644 docs/reference/05-1_arrays.md
 create mode 100644 docs/reference/05-2_structs.md

(limited to 'docs/reference')

diff --git a/docs/reference/04-2_pure-operators.md b/docs/reference/04-2_pure-operators.md
index d4a8d14..d2dc4c5 100644
--- a/docs/reference/04-2_pure-operators.md
+++ b/docs/reference/04-2_pure-operators.md
@@ -21,23 +21,26 @@ As an example, let's consider [math/+][]:
     (import* math time)
 
     (trace (+ 1 2 3))
-    #((+ num= num= num=) -> num=
-      trace (+ 1 2 3): <num= 6>)
-
     (trace (+ 1 2 (lfo 2)))
-    #((+ num= num= num~) -> num~
-      trace (+ 1 2 (lfo 2)): <num~ 4.0>
-      trace (+ 1 2 (lfo 2)): <num~ 3.9882585630406>)
-
     (trace (+ 1 2 (every 1 3)))
-    #((+ num= num= num!) -> num!
-      trace (+ 1 2 (every 2 3)): <num! 6>
-      trace (+ 1 2 (every 2 3)): <num! 6>)
-
     (trace (+ 1 (lfo 2) (every 1 3)))
-    #((+ num= num~ num!) -> num!
-      trace (+ 1 (lfo 2) (every 2 3)): <num! 4.9950529446967>
-      trace (+ 1 (lfo 2) (every 2 3)): <num! 4.9950529446967>)
+
+<div />
+
+    (+ num= num= num=) -> num=
+    trace (+ 1 2 3): <num= 6>
+
+    (+ num= num= num~) -> num~
+    trace (+ 1 2 (lfo 2)): <num~ 4.0>
+    trace (+ 1 2 (lfo 2)): <num~ 3.9882585630406>
+
+    (+ num= num= num!) -> num!
+    trace (+ 1 2 (every 2 3)): <num! 6>
+    trace (+ 1 2 (every 2 3)): <num! 6>
+
+    (+ num= num~ num!) -> num!
+    trace (+ 1 (lfo 2) (every 2 3)): <num! 4.9950529446967>
+    trace (+ 1 (lfo 2) (every 2 3)): <num! 4.9950529446967>
 
 Sometimes a *Pure Op* will require additional constraints on the *kinds* of
 some of its inputs. These will be specified in the documentation.
diff --git a/docs/reference/05-1_arrays.md b/docs/reference/05-1_arrays.md
new file mode 100644
index 0000000..cf10f1e
--- /dev/null
+++ b/docs/reference/05-1_arrays.md
@@ -0,0 +1,11 @@
+Arrays are composite types that contain a fixed number of values of the same
+type. Arrays values can be created using the [`(array …)`][:array:] builtin,
+which uses [Pure Op](04-2_pure-operators.html) semantics to construct an array
+from its parameters, all of which have to be of the same type.
+
+    (trace (array 1 2 3)) #(<num[3]= [1 2 3]>)
+
+The type notation `num[3]` designates an array of three numbers, whereas the
+value notation `[1 2 3]` is used to show the array contents.
+
+The [array][:array/:] module provides *Op*s for working with arrays.
diff --git a/docs/reference/05-2_structs.md b/docs/reference/05-2_structs.md
new file mode 100644
index 0000000..83181df
--- /dev/null
+++ b/docs/reference/05-2_structs.md
@@ -0,0 +1,16 @@
+Structs are composite types that contain values of different types associated
+with a set of string keys. The set of keys and their corresponding value types
+is fixed at *runtime*.
+
+Struct values can be created using the the [`(struct …)`][:struct:] builtin,
+which uses [Pure Op](04-2_pure-operators.html) semantics to construct a struct
+from its parameters. The keys have to be constants.
+
+    (trace (struct "a" 1 "b" 'hello world')) <{a: num b: str}= {a: 1 b: "hello world"}>
+
+The type notation `{a: num b: str}` designates a struct type with the key `a`
+mapping to a value of type `num` and the key `b` mapping to a value of type
+`str` respectively, whereas the value notation `{a: 1 b: "hello world"}` shows
+the struct contents.
+
+The [struct][:struct/:] module provides *Op*s for working with arrays.
diff --git a/docs/reference/index.md b/docs/reference/index.md
index 4d2dd40..beb6f77 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -1,5 +1,3 @@
-__This section is currently under construction.__
-
 This reference manual documents the `alv` langauge and its standard facilities
 in detail. If you are new to alive, the [getting started guide][guide] is the
 recommended place to start. If you are looking for information on adding your
@@ -23,7 +21,7 @@ own module or contributing to alive, check out the
    1. [result kinds](04-1_result-kinds.html)
    2. [pure operators](04-2_pure-operators.html)
 5. compound types
-   1. arrays
-   2. structs
+   1. [arrays](05-1_arrays.html)
+   2. [structs](05-2_structs.html)
 6. [builtin listing](builtins.html)
 7. included modules
-- 
cgit v1.2.3