From 03b2d11bc780346fdba1cc5e628f30326cfb8aa7 Mon Sep 17 00:00:00 2001 From: Brad Nelson Date: Wed, 27 Jan 2021 12:01:28 -0800 Subject: [PATCH] Fixup docs --- ueforth/site/index.html | 198 +++++++++++++++++++++++++--------------- 1 file changed, 123 insertions(+), 75 deletions(-) diff --git a/ueforth/site/index.html b/ueforth/site/index.html index 6e74c97..46a774e 100644 --- a/ueforth/site/index.html +++ b/ueforth/site/index.html @@ -80,84 +80,54 @@ A reduced cross-platform EForth version

µEforth

+

µEforth Specific Words

+ +
Null Terminated Strings

-µEforth (micro-Eforth) simplifies EForth even futher, by building just enough -of the core of the system in C to allow the rest to be be built in proper Forth. -

- -

-A handful of "tricky" words that involve internal loops or many steps are built in their own -functions: -

- -
-FIND ( a n -- xt | 0 )
-PARSE ( ch -- a n )
-S>NUMBER? ( a n -- n f | 0 )
-CREATE ( "name" -- )
-EVALUATE1 ( -- )
-
- -

-This includes EVALUATE1 which parses a single word and -interprets or compiles it (reusing PARSE, -FIND, and S>NUMBER?). -

- -

-See core.h. -

- -

-A few global variables connect parsing and compilation state between -C and Forth (by way of a memory region accessed via 'SYS): -

- -
-'TIB      --- Pointer to the Translation Input Buffer
-#TIB      --- Length of the Translation Input Buffer
->IN       --- Number of characters consumed from TIB
-
-BASE      --- Numeric base for printing and parsing
-
-STATE     --- State of compiling, -1 for compiling, 0 for interpreting
-LAST      --- Execution token of last word defined
-
-'NOTFOUND --- Execution token of a handler to call on word not found
-
- -

-Error handling is routed via a deferred callback in 'NOTFOUND -used when a word is absent from the dictionary. -This is eventually directed to an error routing that prints -a proper error, once I/O and exceptions are available. -

- -

-X-Macros -are then used to build up a small set of core opcodes defined in 1-3 lines each: -

- -
-0= 0< + U/MOD */MOD   AND OR XOR
-DUP SWAP OVER DROP    @ L@ C@ ! L! C!
-SP@ SP! RP@ RP!       >R R> R@   : ; EXIT
-EXECUTE BRANCH 0BRANCH DONEXT DOLIT
-ALITERAL CELL DOES> IMMEDIATE 'SYS
-
- -

-See opcodes.h. -

- -

-I/O and access to systems outside Forth are connected via a few per platform words. -Typically this set of words should be minimal, while still allowing relevant parts -of the host system to be available to Forth. As null terminated strings are used by virtually all platforms, -their use is supported in Forth by way of -Z", Z>S, and S>Z. +their use is supported in Forth by way of several non-standard +words with the convention of using Z/z to refer to such strings +in names and stack comments.

+
+Z" ( "string" -- z ) Creates a null terminated string on the heap
+Z>S ( z -- a n ) Convert a null terminated string to a counted string
+S>Z ( a n -- z ) Conver a counted string string to null terminated (copies string to heap)
+
+ +
Raw Strings
+

+Raw strings are provided better support using a string +for the duration of the current command, without consuming heap memory. +

+
+R" ( "string" -- a n ) Creates a temporary counted string
+R| ( string| -- a n ) Creates a temporary counted string ending with |
+
+ +
Utilities
+
+DUMP ( a n -- ) Dump a memory region
+SEE ( "name" -- ) Attempt to decompile a word
+VARIABLE ECHO -- Determines if commands are echoed
+
+ +
Block Editor
+
+USE ( "name" -- ) Use "name" as the blockfile, e.g. USE /spiffs/foo
+OPEN-BLOCKS ( a n -- ) Open a file as the block file
+LOAD ( n -- ) Evaluate a block
+THRU ( a b -- ) Load blocks a thru b
+LIST ( n -- ) List a block
+L ( -- ) List the current block
+WIPE ( -- ) Blank out the current block
+D ( n -- ) Delete a line in the current block
+E ( n -- ) Clear a line in the current block
+R ( n "text" -- ) Replace a line in the current block
+A ( n "text" -- ) Add (insert) a line in the current block
+SEE ( "name" -- ) Attempt to decompile a word
+VARIABLE ECHO -- Determines if commands are echoed
+

ESP32 Arduino

@@ -474,6 +444,84 @@ See Work in Progress - Coming Soon +

µEforth Internals

+ +

+µEforth (micro-Eforth) simplifies EForth even futher, by building just enough +of the core of the system in C to allow the rest to be be built in proper Forth. +

+ +

+A handful of "tricky" words that involve internal loops or many steps are built in their own +functions: +

+ +
+FIND ( a n -- xt | 0 )
+PARSE ( ch -- a n )
+S>NUMBER? ( a n -- n f | 0 )
+CREATE ( "name" -- )
+EVALUATE1 ( -- )
+
+ +

+This includes EVALUATE1 which parses a single word and +interprets or compiles it (reusing PARSE, +FIND, and S>NUMBER?). +

+ +

+See core.h. +

+ +

+A few global variables connect parsing and compilation state between +C and Forth (by way of a memory region accessed via 'SYS): +

+ +
+'TIB      --- Pointer to the Translation Input Buffer
+#TIB      --- Length of the Translation Input Buffer
+>IN       --- Number of characters consumed from TIB
+
+BASE      --- Numeric base for printing and parsing
+
+STATE     --- State of compiling, -1 for compiling, 0 for interpreting
+LAST      --- Execution token of last word defined
+
+'NOTFOUND --- Execution token of a handler to call on word not found
+
+ +

+Error handling is routed via a deferred callback in 'NOTFOUND +used when a word is absent from the dictionary. +This is eventually directed to an error routing that prints +a proper error, once I/O and exceptions are available. +

+ +

+X-Macros +are then used to build up a small set of core opcodes defined in 1-3 lines each: +

+ +
+0= 0< + U/MOD */MOD   AND OR XOR
+DUP SWAP OVER DROP    @ L@ C@ ! L! C!
+SP@ SP! RP@ RP!       >R R> R@   : ; EXIT
+EXECUTE BRANCH 0BRANCH DONEXT DOLIT
+ALITERAL CELL DOES> IMMEDIATE 'SYS
+
+ +

+See opcodes.h. +

+ +

+I/O and access to systems outside Forth are connected via a few per platform words. +Typically this set of words should be minimal, while still allowing relevant parts +of the host system to be available to Forth. +

+

Classic esp32Forth