From adacc891438396b69a9a01d1d08434a4d4812500 Mon Sep 17 00:00:00 2001
From: dtb <trinity@trinity.moe>
Date: Sat, 10 Dec 2022 22:56:17 -0500
Subject: [PATCH] more reference

---
 README.md                      | 92 ++++++++++++++++++++++++++++++++++
 example/meta_programming.blang | 18 +++++++
 2 files changed, 110 insertions(+)
 create mode 100644 example/meta_programming.blang

diff --git a/README.md b/README.md
index dd624ba..eef1149 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,98 @@ the bang language
 
 Public domain. 2022 DTB.
 
+## Glossary
+
+### chart
+
+The listing of the program currently running.
+This can be modified during runtime.
+
+### command
+
+A character that indicates what the bang language executor should do next.
+
+### hand
+
+The general-purpose register.
+
+### catch
+
+To set the hand to a value.
+
+### throw
+
+To set a value to the contents of the hand.
+
+## Reference
+
+All operations are one character long.
+When an unknown operation is executed the resulting behavior is undefined
+(and maliciously so; for example, execution can stop or garbage can be written to the chart).
+
+### `'!'`
+
+No-op. Does nothing.
+`' '`, `'\n'`, `'\r'`, `'\t'`, and `'\v'` are all also no-ops
+\- keep this in mind when styling code that contains `'?'`!
+
+### `';'`
+
+Denotes a comment.
+A comment starts with a semicolon (or `'#'`, for compatibility with shebangs)
+and ends with a bang (`'!'`) or line feed (`'\n'`).
+
+### `'%'`
+
+Throws at the current location in the program listing to which chart points.
+
+### `'^'`
+
+Catches the constant `0`.
+
+### `'&'` and `'*'`
+
+`'&'` (ampersand) palms the chart. `'*'` (splat) throws the chart.
+
+The following program rewrites itself during runtime using ampersand and splat:
+
+```
+^{?>!&++*<!%&++*<<%&+*<
+%&+*<>%&+*<^%<!}
+
+^;	zero out hand
+{?>;	set return point; if hand is non-zero, print hand
+!&++*;	palm the chart; add 2 to palm; splat the new chart
+<!%;	write '!' to the new chart position
+&++*;	palm the chart; add 2 to palm; splat the new chart
+<<%;	write '<' to the new chart position
+&+*;	advance the chart one space
+<
+%;	write '\n' to the new chart position
+&+*;	advance the chart one space
+<>%;	write '>' to the new chart position
+&+*;	advance the chart one space
+<^%;	write '^' to the new chart position
+<!;	palm '!'
+};	return
+```
+
+Right before the final `'}'`, the chart is the following:
+
+```
+^{!><
+>^*<!%&++*<<%&+*<
+%&+*<>%&+*<^%<!}
+
+^;	zero out hand
+{!>;	print hand
+<
+>;	palm `'\n'`; print hand
+^*;	splat zero to chart
+
+The rest of the program isn't executed.
+```
+
 ## Examples
 
 ### true(1)
diff --git a/example/meta_programming.blang b/example/meta_programming.blang
new file mode 100644
index 0000000..f289adb
--- /dev/null
+++ b/example/meta_programming.blang
@@ -0,0 +1,18 @@
+^{?>!&++*<!%&++*<<%&+*<
+%&+*<>%&+*<^%<!}
+
+^;      zero out hand
+{?>;    set return point; if hand is non-zero, print hand
+!&++*;  palm the chart; add 2 to palm; splat the new chart
+<!%;    write '!' to the new chart position
+&++*;   palm the chart; add 2 to palm; splat the new chart
+<<%;    write '<' to the new chart position
+&+*;    advance the chart one space
+<
+%;      write '\n' to the new chart position
+&+*;    advance the chart one space
+<>%;    write '>' to the new chart position
+&+*;    advance the chart one space
+<^%;    write '^' to the new chart position
+<!;     palm '!'
+};      return