From 034c7b991f4f41741c66ae2fb4a652b28bc9f1b1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ond=C5=99ej=20Hru=C5=A1ka?= <ondra@ondrovo.com>
Date: Thu, 8 Oct 2020 00:56:59 +0200
Subject: [PATCH] improve readme and example of the stdio module

---
 README.md          | 30 ++++++++++++++++++++++++++++++
 examples/stdio.csn | 12 ++++++++++--
 2 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index ae62df1..2cc1c50 100644
--- a/README.md
+++ b/README.md
@@ -449,3 +449,33 @@ such as animations.
 ; 0-left, 1-right, 2-middle
 (sc-mbtn PRESSED BTN)
 ```
+
+## Stdio module
+
+- This module currently defines two global handles: `@stdin` and `@stdout`.
+- You can think of these handles as streams or SFRs (special function registers).
+  To use them, simply load data to or from the handles (e.g. `(ld r0 @stdin)`).
+- They operate over unicode code points, which are a superset of ASCII.
+
+You can use these special handles in almost all instructions:
+
+```
+(cmp @stdin 'y' 
+    (eq? (ld @stdout '1'))
+    (ne? (ld @stdout '0')))
+```
+
+When you compile a program using such handles, you will get a strange looking assembly:
+
+```
+0000 : (ld @0x6372736e00000001 72)
+0001 : (ld @0x6372736e00000001 101)
+0002 : (ld @0x6372736e00000001 108)
+```
+
+These are unique constants assigned to the streams at compile time. They are not meant to be used
+directly, but the value can be obtained by simply leaving out the '@' sign: `(ld r0 stdin)`. 
+That can be useful when these stream handles need to be passed to a function. Obviously this makes
+more sense when there are different kinds of streams available, not just these two default ones.
+
+.
diff --git a/examples/stdio.csn b/examples/stdio.csn
index 8757637..764cf13 100644
--- a/examples/stdio.csn
+++ b/examples/stdio.csn
@@ -6,12 +6,20 @@
 
     (:loop)
     (ld r0 @stdin)
+
+    ; exit by pressing 'q'
+    (cmp r0 'q'
+        (=? (ld @stdout '\n')
+            (halt)))
+
+    ; uppercase ASCII
     (cmp r0 'a' (<? (j :badchar)))
     (cmp r0 'z' (>? (j :badchar)))
-    (sub r0 32) ; to uppercase
+    (sub r0 32)
     (ld @stdout r0)
     (j :loop)
+
     (:badchar)
-    (ld @stdout '🐈')
+    (ld @stdout '🐈') ; show a kitty if not ASCII
     (j :loop)
 )