RPS interpreter

1 files changed, 41 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1f085b1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,41 @@
+# Reverse Polish Scheme
+
+A continuation-passing-style stack-based programming language vaguely
+based off of FORTH but really just Scheme in disguise. With the exception
+of quotation (which is syntax), everything is RPN.
+
+## Core
+
+Writing a number, a string, `#t`, `#f`, or `#nil` will push that literal
+value onto the stack. Strings are equivalent to Scheme symbols. `#nil`
+is the name of a value, NOT the symbol `"nil"`!
+
+A linked list is a 2-vector whose second pair is either `#nil` or
+another linked list.
+
+A subroutine is a linked list whose first slot is unused and whose code
+starts in the second slot.
+
+* `n alloc`: Allocate a memory region of `n` pointers.
+* `{ ... }`: Reads all data up to the matching `{` as data. The data
+  is stored as a linked list.
+* `n v ref`: Get the nth element of `v`.
+* `value n v set!`: Set the nth element of `v`.
+* `sr jump`: Jump to a subroutine.
+* `conditional on-false on-true if`: If `conditional` is truthy, jump
+  to `on-true`. Otherwise jump to `on-false`.
+* `keep-bot keep-top push-cc`: Push the *continuation* of the call to
+  `push-cc`. The continuation object saves the last `keep-top` objects
+  on the stack along with the bottom `keep-bot` values on the stack. If
+  either is `#f`, then the entire stack is saved.
+
+  When `m cc jump` is called (where `cc` is the object returned by
+  `push-cc`), the `m` values currently on the stack are pushed to the top
+  of `n` values saved by `cc`, and control returns to the next location.
+* `dir? n dig`: When `dir?` is false, move the `n`th value relative to the
+  top of the stack to the top of the stack. When `dir?` is true, move the
+  `n`th value relative to the bottom of the stack to the top of the stack.
+* `dir? n bury`: When `dir?` is false, move the top value on the stack to
+  the `n`th value relative to the top of the stack. When `dir?` is true,
+  move the top of the stack to `n`th value relative to the bottom of
+  the stack.