From fb50e68e85cdf8acea73630886e1c3e71235ca74 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juhani=20Krekel=C3=A4?= <juhani.haverinen@gmail.com>
Date: Tue, 22 May 2018 19:39:48 +0300
Subject: [PATCH] Add documentation

---
 brainfuck.md     | 12 ++++++++
 ir.md            | 72 ++++++++++++++++++++++++++++++++++++++++++++++++
 optimizations.md | 38 +++++++++++++++++++++++++
 3 files changed, 122 insertions(+)
 create mode 100644 brainfuck.md
 create mode 100644 ir.md
 create mode 100644 optimizations.md

diff --git a/brainfuck.md b/brainfuck.md
new file mode 100644
index 0000000..e0fec39
--- /dev/null
+++ b/brainfuck.md
@@ -0,0 +1,12 @@
+Commands
+--------
+Gir brainfuck has only the base 8 commands `+-<>[].,`
+
+Tape
+----
+Gir's tape is unbounded in both directions and made out of unsigned 8-bit
+cells that wrap around
+
+IO
+--
+`.` and `,` operate on a utf-8 stream. `,` produces `0` on EOF
diff --git a/ir.md b/ir.md
new file mode 100644
index 0000000..78d5714
--- /dev/null
+++ b/ir.md
@@ -0,0 +1,72 @@
+Gir uses two types of IR, with and without offsets
+
+Without offsets
+---------------
+This is produced by `parse`. Each subsection shows the properties the
+command object of that type has in IR without offsets
+
+### add
+type  | `add`
+value | The number to add to current cell
+
+Generated on `+` and `-`
+
+### moveHead
+type  | `moveHead`
+value | The number of steps to move the tape head right
+
+Generated on `<` and `>`
+
+### writeByte
+type | `writeByte`
+
+Generated on `.`
+
+### readByte
+type | `readByte`
+
+Generated on `,`
+
+### loop
+type     | `loop`
+contents | An array of the commands making up the loop body
+
+Generated on `[`…`]`
+
+### clear
+type | `clear`
+
+Not generated by the parser directly, but generated by optimizations
+
+
+With offsets
+------------
+This is produced by the optimization pass `addOffsetProperties`. Each
+subsection shows the properties the command object of that type has in IR
+with offsets
+
+### add
+type    | `add`
+value   | The number to add to the cell
+offfset | The location of the cell relative to current tape position
+
+### moveHead
+type  | `moveHead`
+value | The number of steps to move the tape head right
+
+### writeByte
+type   | `writeByte`
+offset | The location of the cell relative to current tape position
+
+### readByte
+type   | `readByte`
+offset | The location of the cell relative to current tape position
+
+### loop
+type       | `loop`
+contents   | An array of the commands making up the loop body
+isBalanced | Whether execution of the loop body ends in same cell it started in
+
+### clear
+type   | `clear`
+offset | The location of the cell relative to current tape position
diff --git a/optimizations.md b/optimizations.md
new file mode 100644
index 0000000..7e81057
--- /dev/null
+++ b/optimizations.md
@@ -0,0 +1,38 @@
+Gir has three optimization passes.
+
+joinAdjacentOps
+---------------
+consumes         | commands without offsets
+produces         | commands without offsets
+unknown commands | passed through unmodified
+acts on          | `moveHead`, `add`
+
+`joinAdjacentOps` joins adjacent `moveHead`s and `add`s together. Normally
+`parse` joins runs of `<>` or `+-` into one command, but if the runs are
+interrupted by another character two commands get generated. `moveHead`s are
+joined first, before the pass goes over the generated commands again and
+joins `add`s.
+
+transformClearLoops
+-------------------
+consumes         | commands without offsets
+produces         | commands without offsets
+unknown commands | passed through unmodified
+acts on          | `loop` with one command, which is `add 1` or `add -1`
+
+`transformClearLoops` changes loops of the form `[-]` or `[+]` into a single
+`clear` command.
+
+addOffsetProperties
+-------------------
+consumes         | commands without offsets
+produces         | commands with offsets
+unknown commands | raise UnknownIRError
+acts on          | `moveHead`, `add`, `clear`, `writeByte`, `readByte`, `loop`
+
+`addOffsetProperties` adds an `offset` property to `add`, `clear`,
+`writeByte`, and `readByte`. The `offset` tells the offset at which from the
+current tape head location the operations are performed. It also adds an
+`isBalanced` property to loops. This property tells if execution of loop
+body ends at the same cell where it began, which is useful for performing
+further optimizations.