From 316e83980456cd460516075e41d48165e98be3be Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juhani=20Krekel=C3=A4?= <juhani.haverinen@gmail.com>
Date: Sun, 27 May 2018 13:39:43 +0300
Subject: [PATCH] Document the API

---
 README.md |  5 +--
 api.md    | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 gir.js    | 14 ++++----
 3 files changed, 108 insertions(+), 9 deletions(-)
 create mode 100644 api.md

diff --git a/README.md b/README.md
index 0e464e3..7e0c708 100644
--- a/README.md
+++ b/README.md
@@ -20,12 +20,13 @@ Gir supports following optimizations:
 
 TODO
 ----
+### gir.js
+* Move `ircbotRun()` into its own file
+
 ### gir.html
 * Implement a UI
 
 ### Documentation
-* Document the VM
-* Document the user-facing API
 * Document the overall architecture
 
 ### General
diff --git a/api.md b/api.md
new file mode 100644
index 0000000..28233d5
--- /dev/null
+++ b/api.md
@@ -0,0 +1,98 @@
+Compiling and inspecting programs
+---------------------------------
+
+### compile
+`compile(program, enableExtensions = true)`
+
+* `program`: String containing the program to compile
+* `enableExtensions`: Whether to recognize `:;#` or ignore them
+
+*Returns*: An array holding flat IR
+
+*Example*: `let compiled = compile(',[>+<,]>:');`
+
+### prettifyIR
+`prettifyIR(ir)`
+
+* `ir`: An array holding any type of IR used by Gir
+
+*Returns*: A string suitable for creating IR listings
+
+*Example*: `console.log(prettifyIR(compiled));`
+
+
+Executing programs
+------------------
+
+Gir executes the flattened IR in a simple virtual machine. `runVM()` doesn't
+mutate a state object that is passed to it but rather returns a new one.
+
+### VM state object
+
+property   | default value         | description
+-----------|-----------------------|------------
+`program`  | (set by caller)       | `compile()`d program
+`ip`       | `0`                   | Instruction pointer
+`memory`   | `Map {}`              | Tape
+`tapeHead` | `0`                   | Tape head position
+`input`    | (set by caller)       | `encodeUTF8()`d input
+`output`   | `[]`                  | Output (needs to be `decodeUTF8()`d)
+`onEof`    | `0` / (set by caller) | What to do in case of EOF¹
+
+¹ If `onEof` is null the cell will not be changed, but otherwise the cell
+  will be set to the value of `onEof`
+
+### newVM
+
+`newVM(program, input, onEof = 0)`
+
+* `program`: An array holding flat IR
+* `input`: An array of integers which is interpreted as a byte stream
+* `onEof`: See description of `onEof` field of the VM state object
+
+*Returns*: VM state object
+
+*Example*: `let vm = newVM(compile('.[,[-].]'), encodeUTF('foobar'), null);`
+
+### runVM
+
+`runVM(vm, maxCycles = null)`
+
+* `vm`: VM state object
+* `maxCycles`: Number of cycles the program is allowed to run. `null` means
+               no limit
+
+*Returns*: An object like following
+
+property          | description
+------------------|------------
+state             | VM state object of the state after `runVM()` has completed
+complete          | Boolean describing whether the program completed or not
+cycles            | How many cycles did the program run during this invocation of `runVM()`
+intParseFailed    | Boolean describing if `runVM()` exited because `;` failed to parse an int
+breakPointReached | Boolean describing if `runVM()` exited because it hit `#`
+lastIndex         | Last cell that was accessed by the VM
+
+*Example*: `let output = decodeUTF8(runVM(vm, 400000).state.output);`
+
+
+Helper functions
+----------------
+
+### encodeUTF8
+`encodeUTF8(string)`
+
+* *string*: A javascript string
+
+*Returns*: An array of integers that interpreted as bytes encode that string
+
+*Example*: `let encoded = encodeUTF8(input);`
+
+### decodeUTF8
+`decodeUTF8(encoded)`
+
+* *encoded*: An array of integers
+
+*Returns*: A string encoded by that array
+
+*Example*: `let output = decodeUTF8(result.state.output);`
diff --git a/gir.js b/gir.js
index a5559c7..f0ef54b 100644
--- a/gir.js
+++ b/gir.js
@@ -187,14 +187,14 @@ function parse(program, enableExtensions = true) {
 	return parsed;
 }
 
-// ([commandObjects/offsetCommandObjects]) → str
-function prettifyIR(parsed) {
-	// ([commandObjects/offsetCommandObjects], string) → str
-	function worker(parsed, indent = '') {
+// ([commandObjects/offsetCommandObjects/flatCommandObjects]) → str
+function prettifyIR(ir) {
+	// ([commandObjects/offsetCommandObjectsflatCommandObjects], string) → str
+	function worker(ir, indent = '') {
 		let lines = [];
 
-		for(let i = 0; i < parsed.length; i++) {
-			let command = parsed[i];
+		for(let i = 0; i < ir.length; i++) {
+			let command = ir[i];
 
 			let line = `${indent}${i} `;
 			if(command.type == add) {
@@ -267,7 +267,7 @@ function prettifyIR(parsed) {
 
 		return lines
 	}
-	return worker(parsed).join('\n');
+	return worker(ir).join('\n');
 }
 
 // ------------------------------------------------------------------