1 files changed, 59 insertions, 0 deletions
diff --git a/modal/ocaml/REF.txt b/modal/ocaml/REF.txt
new file mode 100644
index 0000000..9b60128
--- /dev/null
+++ b/modal/ocaml/REF.txt
@@ -0,0 +1,59 @@
+Modal Reference
+
+Program model
+- Program: ordered rules; first match applies.
+- Data: atoms and lists (S-expr). Numbers can be encoded as unary parentheses or decimal/hex for devices.
+- Registers: ?name binds a subtree in left-hand side and substitutes on the right.
+
+Syntax
+- Rule define: (<>) (left) (right)
+- Rule undefine: (><) (left) (right)
+- Device calls: (?: ...), (?_), (?~), (?^ x), (?. x), (?* x)
+- Input lines (loader convenience): lines starting with ".." are expressions appended to the input tree.
+
+Evaluation
+1. Scan tree left-to-right (preorder over the AST).
+2. At each node:
+   a) Dynamic forms: devices and (<>)/ (><) evaluated first.
+   b) Rules: try rules in order; on first match, rewrite.
+3. After rewrite, restart scanning from root. Halt after a full pass with no rewrites or cycle cap exhaustion.
+
+Matching
+- Atom vs atom: equal string.
+- List vs list: same arity; element-wise match.
+- Register (?x): first occurrence binds; subsequent occurrences must equal the bound value.
+
+Devices
+- (?: args...)
+  - ALU: (?: op n0 n1 ...), op in + - * / % & ^ | = ! > < ; numbers decimal or #hex.
+  - Print: otherwise concatenates args (atoms/lists flattened to string) to stdout; returns ().
+- (?_ path)
+  - If access allowed: reads file; returns parsed AST if possible else atom of contents; otherwise returns NAF.
+- (?~)
+  - If access allowed: read stdin; else EOF.
+- (?^ x) : join tokens of x (atoms from leaves) → atom.
+- (?. x) : unwrap list x → elements of x.
+- (?* x) : explode x. If atom, returns list of its characters as atoms. If list, returns x unchanged.
+
+CLI
+- -q : quiet (suppress device print output traces except final tree)
+- -a : allow access (enables (?_), (?~))
+- -n : no cap (large cycle cap)
+
+Notes
+- Rule order is significant.
+- Dynamic rules enable self-modifying programs.
+- Termination is not guaranteed.
+
+Examples
+  Rules:
+    (<>) (copy ?a) (?a ?a)
+    (<>) (swap ?x ?y) (?y ?x)
+
+  Input:
+    (copy cat) (swap bat rat)
+
+  Result:
+    (cat cat) (rat bat)
+
+