add reference/result-kinds

2 files changed, 51 insertions, 1 deletions

diff --git a/docs/reference/04-1_result-kinds.md b/docs/reference/04-1_result-kinds.md
new file mode 100644
index 0000000..ed3bb05
--- /dev/null
+++ b/docs/reference/04-1_result-kinds.md
@@ -0,0 +1,50 @@
+Every expression that is evaluated at *evaltime* returns a *result*, which may
+or may not change at *runtime*. There are three *kinds* of results in `alv`.
+
+# Constants
+Constant results contain a single value that is generated at *evaltime* and do
+not change at *runtime*. Operators that involve only constants generally
+result in constants as well and are not processed at *runtime*. Literal strings
+and numbers are constants.
+
+Constants are denoted using the equals symbol (`=`) in documentation and traces, e.g:
+
+    (trace 4)
+    #(trace 4: <num= 4>)
+
+where `<num= 4>` denotes a constant of the type `num` with a value of `4`.
+
+# Signal Streams
+Signal results contain a continuous value of a given type. A signal must have a
+defined value at any given moment in time, including each *evaltime* evaluation.
+While signals are considered to be continuous, for optimizations sake they are
+processed as a series of discrete changes. Operators with signal inputs
+generally are only reevaluated at *runtime* when the signal changed.
+
+Signals are denoted using the tilde symbol (`~`) in documentation and traces, e.g.:
+
+    (import* time)
+    (trace (lfo 2))
+    #(trace (lfo 2): <num~ 0.0>
+      trace (lfo 2): <num~ 0.0016211131633209>)
+
+where `<num~ 1.0>` denotes a signal-stream of the type `num` with a current
+value of `1.0`.
+
+# Event Streams
+Event results may contain discrete values at instants in time, but are
+undefined between such occurences. All values in a single event result share
+one type. During a single tick of the `alv` scheduler, a given event result may
+contain zero or more ordered values. Operators with event inputs must operate
+each incoming event separately, as each event is considered to occur in a
+separate moment.
+
+Signals are denoted using the bang symbol (`!`) in documentation and traces, e.g.:
+
+    (import* time)
+    (trace (every 2))
+    #(trace (lfo 2): <bang! true>
+      trace (lfo 2): <bang! true>)
+
+where `<num~ 1.0>` denotes an event-stream of the type `bang` that fired with a
+value of `true`.
diff --git a/docs/reference/index.md b/docs/reference/index.md
index 7718ef8..0c5a851 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -20,7 +20,7 @@ own module or contributing to alive, check out the
    5. [loops](03-5_loops.html)
    6. [modules and loading](03-6_modules-and-loading.html)
 4. runtime
-   1. result kinds
+   1. [result kinds](04-1_result-kinds.html)
    2. pure operators
 5. compound types
    1. arrays