parse brackets, improve docs

1 files changed, 46 insertions, 1 deletions

diff --git a/twasm/README.md b/twasm/README.md
index 83dab90..b414770 100644
--- a/twasm/README.md
+++ b/twasm/README.md
@@ -129,7 +129,7 @@ supported tokens are listed below
 | cr8   | 0x004E | |
 | hlt   | 0x004F | |
 | int3  | 0x0050 | |
-| [     | 0x0051 | |
+| [     | 0x0051 | open bracket placeholder; 0x10XX should be used in contexts where the surrounding tokens can be known |
 | ]     | 0x0052 | |
 | xor   | 0x0053 | |
 | inc   | 0x0054 | |
@@ -150,5 +150,50 @@ supported tokens are listed below
 | -     | 0x0063 | |
 | *     | 0x0064 | |
 | /     | 0x0065 | |
+| [     | 0x10XX | open bracket with `XX` bytes until the closing bracket |
 |       | 0xFEXX | token terminator byte as token, where `XX` is the byte |
 |       | 0xFFFF | unrecognised token |
+
+### example program
+
+#### program in assembly
+
+this program doesn't do anything useful, it's just a test
+
+```nasm
+xor eax, eax
+inc rax
+mov [ rax ], rdx
+hlt
+
+```
+
+#### tokenization
+
+```nasm
+0x0053 ; xor
+0xFE20 ; space
+0x0010 ; eax
+0xFE2C ; comma
+0xFE20 ; space
+0x0010 ; eax
+0xFE0A ; newline
+0x0054 ; inc
+0xFE20 ; space
+0x0000 ; rax
+0xFE0A ; newline
+0x0056 ; mov
+0xFE20 ; space
+0x1004 ; open bracket (4)
+0xFE20 ; space         |1
+0x0000 ; rax           |2
+0xFE20 ; space         |3
+0x0052 ; close bracket |4
+0xFE2C ; comma
+0xFE20 ; space
+0x0003 ; rdx
+0xFE0A ; newline
+0x004F ; hlt
+0xFE0A ; newline
+0xFE00 ; null terminator
+```