add reference/pure-operators

3 files changed, 55 insertions, 6 deletions

diff --git a/docs/reference/04-1_result-kinds.md b/docs/reference/04-1_result-kinds.md
index ed3bb05..f1747b9 100644
--- a/docs/reference/04-1_result-kinds.md
+++ b/docs/reference/04-1_result-kinds.md
@@ -7,21 +7,23 @@ 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:
+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 Streams (~-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.:
+Signals are denoted using the tilde symbol (`~`) in documentation and traces,
+e.g.:
 
     (import* time)
     (trace (lfo 2))
@@ -31,7 +33,10 @@ Signals are denoted using the tilde symbol (`~`) in documentation and traces, e.
 where `<num~ 1.0>` denotes a signal-stream of the type `num` with a current
 value of `1.0`.
 
-# Event Streams
+Constants can be passed in place of signals and will be treated like signals
+that never change.
+
+# Event Streams (!-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
@@ -39,7 +44,8 @@ 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.:
+Event streams are denoted using the bang symbol (`!`) in documentation and
+traces, e.g.:
 
     (import* time)
     (trace (every 2))
diff --git a/docs/reference/04-2_pure-operators.md b/docs/reference/04-2_pure-operators.md
new file mode 100644
index 0000000..d4a8d14
--- /dev/null
+++ b/docs/reference/04-2_pure-operators.md
@@ -0,0 +1,43 @@
+The semantics of each operator with regard to its input and output *result
+kinds* vary. However there is a large set of operators that share common
+semantics. These Operators are called *Pure Operator*s and identified as such
+in documentation and reference.
+
+*Pure Op*s only change when any of their inputs change and are often
+equivalent to a pure mathematical function. The inputs of a *Pure Op* can be
+mixed between all kinds of results, subject to the following rules:
+
+- If any of the inputs is a !-stream, the output is also an !-stream and will
+  only fire when the input stream does. All other inputs will be sampled at
+  that moment. At most one !-stream is allowed as an input.
+- Otherwise, if there are one more ~-streams in the inputs, the output will
+  also be a ~-stream and will be updated whenever any of the inputs changes.
+- Otherwise the output is a constant.
+
+The input and output *types* are defined by the concrete Op.
+
+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>)
+
+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/index.md b/docs/reference/index.md
index 0c5a851..4d2dd40 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -21,7 +21,7 @@ own module or contributing to alive, check out the
    6. [modules and loading](03-6_modules-and-loading.html)
 4. runtime
    1. [result kinds](04-1_result-kinds.html)
-   2. pure operators
+   2. [pure operators](04-2_pure-operators.html)
 5. compound types
    1. arrays
    2. structs