From f382cff852e532fe0bb1d1ff00f0b4aaa10fbfa2 Mon Sep 17 00:00:00 2001
From: Brad Nelson <flagxor@gmail.com>
Date: Wed, 30 Dec 2020 12:51:05 -0800
Subject: [PATCH] Document

---
 .gitignore                             |  2 +-
 Makefile                               |  6 -----
 README.md                              | 33 ++++++++++++++++++++++++++
 circleforth/README.md                  |  6 +++++
 circle.fs => circleforth/circle.fs     |  0
 compound.fs => circleforth/compound.fs |  0
 eforth.fs => reference/eforth.fs       |  2 ++
 ueforth/Makefile                       | 12 ++++++++++
 forth.c => ueforth/ueforth.c           | 24 +++++++++----------
 9 files changed, 66 insertions(+), 19 deletions(-)
 delete mode 100644 Makefile
 create mode 100644 README.md
 create mode 100644 circleforth/README.md
 rename circle.fs => circleforth/circle.fs (100%)
 rename compound.fs => circleforth/compound.fs (100%)
 rename eforth.fs => reference/eforth.fs (99%)
 create mode 100644 ueforth/Makefile
 rename forth.c => ueforth/ueforth.c (100%)

diff --git a/.gitignore b/.gitignore
index 774ae26..718c43f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1 @@
-forth
+ueforth/out
diff --git a/Makefile b/Makefile
deleted file mode 100644
index 3375de7..0000000
--- a/Makefile
+++ /dev/null
@@ -1,6 +0,0 @@
-forth: forth.c
-
-CFLAGS=-O2 -Wall -Werror
-
-clean:
-	rm -f forth
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b9c3af5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,33 @@
+# The many faces of EForth
+
+EForth is delightfully minimalist approach to Forth originated by Bill Muench and Dr. C. H. Ting.
+
+In its original form metacompilation is avoided.
+
+## Directories
+
+* reference/ - EForth Reference Material
+* circleforth/ - A minimalist Forth modeled after toy Lisps.
+* ueforth/ - micro EForth - EForth refactored to allow source boostraping.
+
+## EForth Quirks
+
+EForth uses `FOR..NEXT` in favor of `DO..LOOP`:
+[FOR/NEXT](https://github.com/TG9541/stm8ef/wiki/eForth-FOR-..-NEXT).
+
+This construct has the odd property that it iterates one "extra" time for zero.
+
+```
+: FOO 10 FOR R@ . NEXT ; FOO
+ 10 9 8 7 6 5 4 3 2 1 0  ok
+```
+
+To permit a more ordinary loop the `AFT` word is used in the sequence `FOR..AFT..THEN..NEXT`.
+
+```
+: FOO 10 FOR ( 1st time only ) AFT R@ . THEN NEXT ; FOO
+ 9 8 7 6 5 4 3 2 1 0  ok
+```
+
+The even more enigmatic `FOR..WHILE..NEXT..ELSE..THEN` is used in place of `DO..LEAVE..LOOP`.
+It allows a while condition to early out of a counted loop.
diff --git a/circleforth/README.md b/circleforth/README.md
new file mode 100644
index 0000000..8e0211d
--- /dev/null
+++ b/circleforth/README.md
@@ -0,0 +1,6 @@
+# Circleforth
+
+Created as an example of a minimalist Forth in the style of typical "toy" Lisp implementations.
+
+Similar to classic "Eval-Apply" style Lisps, the core problem of reimplementing the core interpreter
+is approached on top of an existing Forth. Primitives are reused, and crucially parsing is reused.
diff --git a/circle.fs b/circleforth/circle.fs
similarity index 100%
rename from circle.fs
rename to circleforth/circle.fs
diff --git a/compound.fs b/circleforth/compound.fs
similarity index 100%
rename from compound.fs
rename to circleforth/compound.fs
diff --git a/eforth.fs b/reference/eforth.fs
similarity index 99%
rename from eforth.fs
rename to reference/eforth.fs
index 6d5e715..b995dc9 100644
--- a/eforth.fs
+++ b/reference/eforth.fs
@@ -1,3 +1,5 @@
+( EForth High Level Definitions )
+
 ( Variables and User Variables )
 
 : doVAR ( -- a ) R> ;
diff --git a/ueforth/Makefile b/ueforth/Makefile
new file mode 100644
index 0000000..193df91
--- /dev/null
+++ b/ueforth/Makefile
@@ -0,0 +1,12 @@
+all: out/ueforth
+
+out:
+	mkdir -p out
+
+out/ueforth: ueforth.c | out
+	$(CC) $(CFLAGS) $< -o $@
+
+CFLAGS=-O2 -Wall -Werror
+
+clean:
+	rm -rf out/
diff --git a/forth.c b/ueforth/ueforth.c
similarity index 100%
rename from forth.c
rename to ueforth/ueforth.c
index 0c7884d..3bcf2f2 100644
--- a/forth.c
+++ b/ueforth/ueforth.c
@@ -198,18 +198,6 @@ static const char boot[] =
 " : throw   handler @ rp! r> handler ! r> swap >r sp! drop r> ; "
 " ' throw 'throw ! "
 
-// Examine Dictionary
-" : >name ( xt -- a n ) 3 cells - dup @ swap over aligned - swap ; "
-" : >link ( xt -- a ) 2 cells - @ ; "
-" : >body ( xt -- a ) cell+ ; "
-" : see. ( xt -- ) >name type space ; "
-" : see-one ( xt -- xt+1 ) "
-"    dup @ dup ['] DOLIT = if drop cell+ dup @ . else see. then cell+ ; "
-" : exit= ( xt -- ) ['] exit = ; "
-" : see-loop   >body begin see-one dup @ exit= until ; "
-" : see   cr ['] : see.  ' dup see.  see-loop drop  ['] ; see.  cr ; "
-" : words   last @ begin dup see. >link dup 0= until drop cr ; "
-
 // Numeric Output
 " variable hld "
 " : pad ( -- a ) here 80 + ; "
@@ -234,6 +222,18 @@ static const char boot[] =
 " : $@   r@ dup cell+ swap @ r> dup @ aligned + cell+ >r ; "
 " : s\"   [char] \" parse postpone $@ dup , 0 do dup c@ c, 1+ loop drop align ; immediate "
 
+// Examine Dictionary
+" : >name ( xt -- a n ) 3 cells - dup @ swap over aligned - swap ; "
+" : >link ( xt -- a ) 2 cells - @ ; "
+" : >body ( xt -- a ) cell+ ; "
+" : see. ( xt -- ) >name type space ; "
+" : see-one ( xt -- xt+1 ) "
+"    dup @ dup ['] DOLIT = if drop cell+ dup @ . else see. then cell+ ; "
+" : exit= ( xt -- ) ['] exit = ; "
+" : see-loop   >body begin see-one dup @ exit= until ; "
+" : see   cr ['] : see.  ' dup see.  see-loop drop  ['] ; see.  cr ; "
+" : words   last @ begin dup see. >link dup 0= until drop cr ; "
+
 // ( Input )
 " : accept ( a n -- n ) 0 swap begin 2dup < while "
 "    key dup nl = if 2drop nip exit then "