:memo: added reference for required instructions

README.md

@@ -9,8 +9,8 @@ programming language. Implement a very basic evaluator for a small subset of For
 
 Your evaluator has to support the following words:
 
- * `+`, `-`, `*`, `/` (integer arithmetic)
- * `DUP`, `DROP`, `SWAP`, `OVER` (stack manipulation)
+* `+`, `-`, `*`, `/` (integer arithmetic)
+* `DUP`, `DROP`, `SWAP`, `OVER` (stack manipulation)
 
 Your evaluator also has to support defining new words using the customary syntax:
 
@@ -25,3 +25,86 @@ a word is a sequence of one or more letters, digits, symbols or punctuation that
 (Forth probably uses slightly different rules, but this is close enough.)
 
 Words are case-insensitive.
+
+## Reference
+
+Forth runs on an imaginary machine having only a stack (virtually infinite) of values.
+All instructions modify this stack in a way.
+Some instructions require the stack to have at least a certain amount of values.
+
+### Numbers
+
+**Minimum required values on the stack: 0**
+
+Numbers just push the given value on the stack.
+
+```c
+23   // Stack is [23]
+42   // Stack is [42, 23]
+1337 // Stack is [1337, 42, 23]
+```
+
+### `+`, `-`, `*`, `/`
+
+**Minimum required values on the stack: 2**
+
+The arithmetic instructions all take the top 2 values from the stack, calculate the result,
+and then put the result on the stack.
+
+Example:
+
+```c
+23 // Stack is [23]
+42 // Stack is [42, 23]
++  // Stack is [65]
+```
+
+For `-` and `/` the order is relevant.
+
+```c
+23 // Stack is [23]
+42 // Stack is [42, 23]
+-  // Stack is [19]
+
+4  // Stack is [4, 19]
+64 // Stack is [64, 4, 19]
+/  // Stack is [16, 19]
+```
+
+### `DUP` - Duplicate the top value on the stack
+
+**Minimum required values on the stack: 1**
+
+```c
+1337 // Stack is [1337]
+DUP  // Stack is [1337, 1337]
+```
+
+### `DROP` - Remove the top value from the stack
+
+**Minimum required values on the stack: 1**
+
+```c
+1337 // Stack is [1337]
+DROP // Stack is []
+```
+
+### `SWAP` - Swap the two top values on the stack
+
+**Minimum required values on the stack: 2**
+
+```c
+23   // Stack is [23]
+42   // Stack is [42, 23]
+SWAP // Stack is [23, 42]
+```
+
+### `OVER` - Duplicate the second to top value on the stack
+
+**Minimum required values on the stack: 2**
+
+```c
+23   // Stack is [23]
+42   // Stack is [42, 23]
+OVER // Stack is [23, 42, 23]
+```