more reference

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)

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