Extends documentation

README.md

@@ -5,8 +5,151 @@ The base of language; a language designed to be just a compiler for other langua
 
 And you probably won't write _your_ custom language in lang0, but in a system language built in lang0.
 
+The language
+---
+
+lang0 is designed for building small compilers. As such, it has a number of primitives specific for that.
+
+### Examples
+
+See `example0.lang0`:
+```
+main:
+	declare char
+	declare isa
+	declare isnota
+	calc char peek
+	calc isa eq char "a"
+	calc isnota not isa
+	if isa
+		emit "Got a"
+		emit eol
+	/
+	if isnota
+		emit "Did not get a"
+		emit eol
+	/
+	return
+/
+```
+
+```sh
+make it2
+cat example0.lang0 | ./it2-out > example0.c
+gcc example0.c -o example0
+echo 'a' | ./example0
+# Got a
+echo 'b' | ./example0
+# Did not get a
+```
+
+### Formatting
+
+Indentation is done using tabs.
+
+### Parsing
+
+### Variables
+
+#### calc var func args*
+
+Calls func with args and stores the output in var.
+
+#### declare var
+
+Pre-declares var.
+
+#### set var "const"
+
+Sets var to "const".
+
+### Flow control
+
+#### break
+
+Exits the deepest `forever` loop.
+
+#### if arg
+
+Evaluates arg. If found to be true, descends in the block. Otherwise, skips the block
+
+#### forever
+
+Repeats the block until `break`  or `return` is called.
+
+#### return var?
+
+Returns the given value. You can not give an argument if your function is never used in `call`.
+
+#### func args*
+
+Calls the given function with the given arguments. The result, if any, is ignored.
+
+### Builtins
+
+#### emit arg
+
+Writes the given string to standard output.
+
+? Does this need to be a builtin ?
+
+#### skipchar
+
+? Does this need to be a builtin ?
+
+#### trace
+
+? Does this need to be a builtin ?
+
+#### Standard library functions
+
+#### eq a b
+
+Return true if the given strings are the same.
+
+#### lt a b
+
+Return true if a would sort before b.
+
+#### addstringchar a b
+
+b is expected to have length 1.
+
+Creates a new string with b appended to a.
+
+#### peek
+
+Checks stdin for the next character and returns it.
+
+#### skip
+
+Advances stdin a single character.
+
+### Typing
+
+Every variable is of type string. Every function gets a number of strings as output, and returns another string.
+The `if` statement accept all non-empty strings as true, and the empty string as false.
+
+Notes
+---
+
+You can declare variables and functions ahead of time. This is necessary for some interpreters.
+
+Bootstrap stairs
+---
+
+The first iteration is written by hand, both the compiler and the compiler compiler.
+It targets python3 as an interpreter.
+
+The second version only has the compile written by hand, with the compiler compiler being the output of iteration 1.
+It targets gcc as interpreter.
+
+We compile every iteration 3 times, to ensure that the the compiler round trips properly.
+
+![A graph of the build setup](t-diagram.png)
+
 How to run
-===
+---
 
 Install python3 and make