From ca0cc6735997e301d8785debcf5ae63541eba1ff Mon Sep 17 00:00:00 2001 From: Brad Nelson Date: Fri, 12 Feb 2021 00:20:53 -0800 Subject: [PATCH] Big refactor of site. --- ueforth/Makefile | 9 +- ueforth/site/ESP32forth.html | 524 ++++++++++++ ueforth/site/app.yaml | 5 + ueforth/site/classic.html | 62 ++ ueforth/site/index.html | 764 +----------------- ueforth/site/internals.html | 94 +++ ueforth/site/linux.html | 187 +++++ .../{espforth.ino => ESP32forth-6.3.0.ino} | 0 ueforth/site/static/eforth.css | 67 ++ ueforth/site/windows.html | 197 +++++ 10 files changed, 1156 insertions(+), 753 deletions(-) create mode 100644 ueforth/site/ESP32forth.html create mode 100644 ueforth/site/classic.html create mode 100644 ueforth/site/internals.html create mode 100644 ueforth/site/linux.html rename ueforth/site/static/{espforth.ino => ESP32forth-6.3.0.ino} (100%) create mode 100644 ueforth/site/static/eforth.css create mode 100644 ueforth/site/windows.html diff --git a/ueforth/Makefile b/ueforth/Makefile index a516b7a..c1f82e4 100644 --- a/ueforth/Makefile +++ b/ueforth/Makefile @@ -265,7 +265,7 @@ $(DEPLOY): mkdir -p $@ $(DEPLOY)/app.yaml: $(ARDUINO)/ESP32forth-$(VERSION).zip \ - site/index.html \ + $(wildcard site/*.html) \ site/app.yaml \ site/eforth.go \ $(TARGETS) | $(DEPLOY) @@ -275,7 +275,14 @@ $(DEPLOY)/app.yaml: $(ARDUINO)/ESP32forth-$(VERSION).zip \ cp -r $(WINDOWS)/uEf32.exe $(DEPLOY)/static/uEf32-$(VERSION).exe cp -r $(WINDOWS)/uEf64.exe $(DEPLOY)/static/uEf64-$(VERSION).exe cp -r $(RES)/eforth.ico $(DEPLOY)/static/favicon.ico + cp -r site/static/* $(DEPLOY)/static/ + cp -r site/*.sh $(DEPLOY) cp -r site/*.go $(DEPLOY) cp -r site/*.yaml $(DEPLOY) sed 's/{{VERSION}}/$(VERSION)/g' site/index.html >$(DEPLOY)/index.html + sed 's/{{VERSION}}/$(VERSION)/g' site/ESP32forth.html >$(DEPLOY)/ESP32forth.html + sed 's/{{VERSION}}/$(VERSION)/g' site/windows.html >$(DEPLOY)/windows.html + sed 's/{{VERSION}}/$(VERSION)/g' site/linux.html >$(DEPLOY)/linux.html + cp site/internals.html $(DEPLOY)/ + cp site/classic.html $(DEPLOY)/ cp -r site/.gcloudignore $(DEPLOY) diff --git a/ueforth/site/ESP32forth.html b/ueforth/site/ESP32forth.html new file mode 100644 index 0000000..d1215be --- /dev/null +++ b/ueforth/site/ESP32forth.html @@ -0,0 +1,524 @@ + + + +ESP32forth + + + +
+

ESP32forth

+ +
+ ESP32forth + Linux + Windows + Internals + Classic +
+ +

Download

+ +

+ESP32forth-{{VERSION}}.zip + - Single .ino file ready for installation +

+ +

+http://github.com/flagxor/eforth + - Complete Source Code (under ueforth/) +

+ +

Install

+ +

+Download the Arduino IDE for your platform. +

+ +

+Go to File > Preferences.
+Under Additional Board Manager URLs enter: https://dl.espressif.com/dl/package_esp32_index.json +

+ +

+Choose these options under Tools. + +

+

+ +

ESP32forth Features

+ +

ESP32forth Specific Words

+ +
Null Terminated Strings
+

+As null terminated strings are used throughout C interfaces, +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
+
+ +
Vocabularies
+

+µEforth uses a hybrid of Forth-79 and Forth-83 style vocabularies. +By default vocabularies chain to the vocabulary in which they were defined, +as in Forth-79. However, like Forth-83, ALSO +can be used to add vocabularies to a vocabulary stack of which +CONTEXT @ is the first item. +The word ONLY clears the vocabulary stack, but as there is +no separate ONLY vocabulary, it also sets CONTEXT +to the FORTH vocabulary. +The word SEALED modifies the most recently defined vocabulary +such that it does not chain. Note, this must be done before words are added to it. +

+
+VOCABULARY ( "name" ) Create a vocabulary with the current vocabulary as parent
+FORTH ( -- ) Make the FORTH vocabulary the context vocabulary
+DEFINITIONS ( -- ) Make the context vocabulary the current vocabulary
+VLIST ( -- ) List the words in the context vocabulary (not chains)
+WORDS ( -- ) List the words in the context vocabulary (including chains)
+TRANSFER ( "name" ) Move a word from its current dictionary to the current vocabulary
+                    Useful for "hiding" built-in words
+ALSO ( -- ) Duplicate the vocabulary at the top of the vocabulary stack
+ONLY ( -- ) Reset context stack to one item, the FORTH dictionary
+            Non-standard, as there's no distinct ONLY vocabulary
+ORDER ( -- ) Print the vocabulary search order
+SEALED ( -- ) Alter the last vocabulary defined so it doesn't chain
+
+ +
Blocks
+
+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
+BLOCK ( n -- a ) Get a 1024 byte block
+BUFFER ( n -- a ) Get a 1024 byte block without regard to old contents
+UPDATE ( -- ) Mark the last block modified
+FLUSH ( -- ) Save and empty all buffers
+EMPTY-BUFFERS ( -- ) Empty all buffers
+SAVE-BUFFERS ( -- ) Save all buffers
+SCR ( -- a ) Pointer to last listed block
+
+ +
Block Editor
+These words are available inside the EDITOR vocabulary. +
+WIPE ( -- ) Blank out the current block
+L ( -- ) List 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
+P ( -- ) Move to the previous block
+N ( -- ) Move to the next block
+
+ +
Utilities
+
+SEE ( "name" -- ) Attempt to decompile a word
+ECHO ( -- a ) -- Address of flag that determines if commands are echoed
+
+ +

ESP32forth Opcodes

+ +

+Because Arduino builds a statically linked image for flashing into ESP32 devices, +all C function bindings need to be explicitly added. +This is the current collection. +Typically to reduce confusion, function names have be preserved even through verbose. +In popular cases a shorted higher level name is provided. +

+ +

+See arduino.template.ino. +

+ +
Allocation
+These words are inside the internals vocabulary. +
+MALLOC ( n -- a | 0 )   System malloc
+SYSFREE ( a -- )   System free
+REALLOC ( a n -- a | 0 )   System realloc
+
+ +
Serial
+These words are inside the Serial vocabulary. +
+Serial.begin ( baud -- )   Start serial port
+Serial.end ( -- )   End serial port
+Serial.available ( -- f )   Is serial data available
+Serial.readBytes ( a n -- n )   Read serial bytes, return number gotten
+Serial.write ( a n -- n )   Write serial bytes
+Serial.flush ( -- )   Flush serial buffer
+
+ +
Serial Bluetooth
+These words are inside the bluetooth vocabulary. +
+SerialBT.new ( -- bt )   Allocate new BT object
+SerialBT.delete ( bt -- )   Free BT object
+SerialBT.begin ( localname ismaster bt -- f )
+SerialBT.end ( bt -- )
+SerialBT.available ( bt -- f )
+SerialBT.readBytes ( a n bt -- n )
+SerialBT.write ( a n bt -- n )
+SerialBT.flush ( bt -- )
+SerialBT.hasClient ( bt -- f )
+SerialBT.enableSSP ( bt -- )
+SerialBT.setPin ( z bt -- f )
+SerialBT.unpairDevice ( addr bt -- f )
+SerialBT.connect ( remotename bt -- f )
+SerialBT.connectAddr ( addr bt -- f )
+SerialBT.disconnect ( bt -- f )
+SerialBT.connected ( timeout bt -- f )
+SerialBT.isReady ( checkMaster timeout -- f )   Default checkMaster=false, timeout=0
+
+ +
Bluetooth
+These words are inside the bluetooth vocabulary. +
+esp_bt_dev_get_address ( -- a ) addr of 6 byte mac address
+
+ +
GPIO
+
+pinMode ( pin mode -- )   Set GPIO pin mode
+digitalWrite ( pin value -- )   Set GPIO pin state
+analogRead ( pin -- n )   Analog read from 0-4095
+
+ +
ledc
+These words are inside the ledc vocabulary. +
+ledcSetup ( channel freq resolution -- freq )
+ledcAttachPin ( pin channel -- )
+ledcDetachPin ( pin -- )
+ledcRead ( channel -- n )
+ledcReadFreq ( channel -- freq )   Get frequency (x 1,000,000)
+ledcWrite ( channel duty -- )
+ledcWriteTone ( channel freq )   Write tone frequency (x 1000)
+ledcWriteNote ( channel note octave -- freq )
+
+ +
Short GPIO Names
+
+pin ( value pin# -- )   Set GPIO pin value
+adc ( pin# -- n )   Analog read pin, result 0-1023
+
+ +
System
+
+MS ( n -- )
+TERMINATE ( n -- ) Call system exit
+
+ +
Files
+
+R/O ( -- mode )
+R/W ( -- mode )
+W/O ( -- mode )
+BIN ( mode -- mode )
+CLOSE-FILE ( fh -- ior )
+OPEN-FILE ( a n mode -- fh ior )
+CREATE-FILE ( a n mode -- fh ior )
+DELETE-FILE ( a n -- ior )
+WRITE-FILE ( a n fh -- ior )
+READ-FILE ( a n fh -- n ior )
+FILE-POSITION ( fh -- n ior )
+REPOSITION-FILE ( n fh -- ior )
+FILE-SIZE ( fh -- n ior )
+
+ +
WiFi
+These words are inside the WiFi vocabulary. +
+WiFi.config ( ip dns gateway subnet -- )   Packaged a.b.c.d little-endian
+Wifi.begin ( ssid-z password-z -- )
+Wifi.disconnect ( -- )
+WiFi.status ( -- n )
+WiFi.macAddress ( a -- )
+WiFi.localIP ( -- ip )
+WiFi.mode ( mode -- ) WIFI_MODE_NULL WIFI_MODE_STA WIFI_MODE_AP WIFI_MODE_APSTA
+WiFi.setTxPower ( powerx4 -- )   Set power x4
+WiFi.getTxPower ( -- powerx4 )   Get power x4
+
+ +
mDNS
+
+MDNS.begin ( name-z -- )   Start multicast dns
+
+ +
SPIFFS
+These words are inside the SPIFFS vocabulary. +
+SPIFFS.begin ( format-on-fail path-z max-files -- f )
+SPIFFS.end ( -- )
+SPIFFS.format ( -- f )
+SPIFFS.totalBytes ( -- n )
+SPIFFS.usedBytes ( -- n )
+
+ +
WebServer
+These words are inside the WebServer vocabulary. +
+WebServer.new ( port -- ws )   Allocate new webserver object
+WebServer.delete ( ws -- )   Delete webserver object
+WebServer.begin ( port ws -- )
+WebServer.stop ( ws -- )
+WebServer.on ( path-z xt ws -- ) Set up a web path handle callback
+WebServer.handleClient ( ws -- )   Handle one client request
+WebServer.hasArg ( z ws -- f )   By name
+WebServer.arg ( z ws -- z )   By name
+WebServer.argi ( n ws -- z )   By index
+WebServer.argName ( n ws -- z)   By index
+WebServer.args ( ws -- n )   Number of args
+WebServer.setContentLength ( n ws -- )
+WebServer.sendHeader ( name-z value-z fist ws -- )
+WebServer.send ( code mimetype data ws -- )
+WebServer.sendContent ( z ws -- )
+WebServer.method ( ws -- n )   GET / POST etc.
+
+ +
Wire
+These words are inside the Wire vocabulary. +
+Wire.begin ( -- f )
+Wire.setPins ( sda scl -- f )
+Wire.setClock ( frequency -- )
+Wire.getClock ( -- frequency )
+Wire.setTimeout ( ms -- ) Default is 50ms
+Wire.getTimeout ( -- ms )
+Wire.lastError ( -- n )
+Wire.getErrorText ( n -- z )
+Wire.beginTransmission ( n -- )
+Wire.endTransmission ( sendstop -- f )
+Wire.requestFrom ( address quantity sendstop -- n )
+Wire.writeTransmission ( addr a n sendstop -- err )
+Wire.readTransmission ( addr a n sendstop acount -- err )
+Wire.write ( a n -- n )
+Wire.available ( -- f )
+Wire.read ( -- ch )
+Wire.peek ( -- ch )
+Wire.busy ( -- f )
+Wire.flush ( -- )
+
+ +
Camera
+These words are inside the camera vocabulary. +
+esp_camera_init ( config -- f )
+esp_camera_deinit ( -- f )
+esp_camera_fb_get ( -- fb )
+esp_camera_fb_return ( fb -- )
+esp_camera_sensor_get ( -- sensor )
+
+ +
SD_MMC
+These words are inside the SD_MMC vocabulary. +
+SD_MMC.begin ( mount mode1bit )   default mode1bit=false
+SD_MMC.end ( -- )
+SD_MMC.cardType ( -- n )
+SD_MMC.totalBytes ( -- n )
+SD_MMC.usedBytes ( -- n )
+
+ +

ESP32 WebUI

+ +

+A terminal over the web can be activated. +Contact at port printed or via mDNS http://ueforth/. +

+ +
+webui ( network-z password-z -- )
+
+ +

Usage:

+ +
+z" NETWORK-NAME" z" PASSWORD" webui
+
+ +

+See arduino_server.fs. +

+ +

Autoexec.fs

+ +

+The system will automatically attempt to mount SPIFFS filesystem at /spiffs. +It will then at start attempt to load /spiffs/autoexec.fs +

+ +

+One way this feature can be used to configure the Web UI to start by default. +When doing this, be sure to test your Web UI settings work well first. +

+ +
+r| z" NETWORK-NAME" z" PASSWORD" webui | s" /spiffs/autoexec.fs" dump-file
+
+ +

+To remove a previously configured autoexec.fs you will need +to be able to reboot in a mode with Forth. One way to do this is to search +for the line in the .ino file that refers to autoexec.fs +and replace it with a different name. Then run the following: +

+ +
+s" /spiffs/autoexec.fs" delete-file
+
+ +

+See autoboot.fs. +

+ +

Adding Words

+ +

+Adding words based on C functions can be done by editing the source code. +For ESP32forth arduino.template.ino is the appropriate place. +

+ +

+Because of the use of X-Macros words can be +added in as little as one line. Locate the macro called PLATFORM_OPCODE_LIST +and add your words there. +

+ +

NOTE: Be careful to end each line with a \ so the macros will chain correctly.

+ +

+To add a word containing only letters, numbers, and underscore you can use Y. +

+ +
+  Y(MY_WORD123, c_function_to_call()) \
+
+ +

+If your word name contains other characters, instead use X. +You will need to make up an alternate name for the middle parameter. +It must contain only letters, numbers, and underscore. +The name is not used anywhere else, but must be unique. +

+ +
+  X("myword!", MY_WORD_BANG, c_function_to_call()) \
+
+ +

+Values from the data stack can be accessed via +the variables tos (Top of Stack) and +sp (Pointer to the rest of the stack). +The stack has the data type cell_t. +

+ +

+You can push a value of any type to the stack with the macro PUSH: +

+ +
+  Y(MY_WORD, PUSH calculate_magic_value()) \
+
+ +

+To simplify calling C functions, you can also refer to elements on the stack +with the types positional names: +

+ +
+n10 n9 n8 n7 n6 n5 n4 n3 n2 n1 n0 - Access stack as cell_t integer values
+                   c4 c3 c2 c1 c0 - Access stack as char* values
+                   b4 b3 b2 b1 b0 - Access stack as uint8_t* byte values
+                   a4 a3 a2 a1 a0 - Access stack as void* values
+
+Examples:
+  void send_message(const char *message, int code);
+  ...
+  X("send-message", SEND_MESSAGE, send_message(c1, n0)) \
+
+ +

+ You can always replace the top item on the stack with SET: +

+ +
+  Y(DECODE, SET decode_func(n0)) \
+
+ +

+ You can drop elements from the stack with DROP + or DROPn(number). + You can nip elements from below top of the stack with NIP + or NIPn(number). + Be aware that like PUSH this will cause stack indices to change. +

+ +
+  int my_cool_function(char *foo, int bar, uint8_t *baz);
+  ...
+  Y(MY_FUNC, n0 = my_cool_function(c2, n1, b0); NIPn(2)) \
+
+ +

+Multiple C statements can be included in the code area of a word, +but care must be taken to generally avoid {}s. +If you find you need nesting, a separate function is recommended. +

+ +

+New variables can be declared in each word and are scoped to that word. +

+ +
+  Y(MY_WORD, cell_t foo = n0; DROP; char *x = c0; DROP; \
+             PUSH my_func(foo, x)) \
+
+ diff --git a/ueforth/site/app.yaml b/ueforth/site/app.yaml index c3ad430..550c43c 100644 --- a/ueforth/site/app.yaml +++ b/ueforth/site/app.yaml @@ -18,6 +18,11 @@ handlers: upload: index.html secure: always +- url: /(.*).html + static_files: \1.html + upload: *.html + secure: always + - url: /static static_dir: static secure: always diff --git a/ueforth/site/classic.html b/ueforth/site/classic.html new file mode 100644 index 0000000..ce1b090 --- /dev/null +++ b/ueforth/site/classic.html @@ -0,0 +1,62 @@ + + + +Classic EForth + + + +

Classic EForth

+ +
+ ESP32forth + Linux + Windows + Internals + Classic +
+ +

+EForth is a delightfully minimalist approach to Forth originated by Bill Muench and Dr. C. H. Ting. +

+ +

Classic ESP32forth

+ +

+ESP32forth - Version 6.3 for NodeMCU ESP32S - Tweaked for the Web +

+ + + +

Classic EForth Quirks

+ +

+EForth exclusively uses FOR..NEXT in favor of DO..LOOP. +Details +

+ +

+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/ueforth/site/index.html b/ueforth/site/index.html index df4ac17..32e434a 100644 --- a/ueforth/site/index.html +++ b/ueforth/site/index.html @@ -2,761 +2,21 @@ EForth - +

EForth

+ +
+ ESP32forth + Linux + Windows + Internals + Classic +

-EForth is a delightfully minimalist approach to Forth originated by Bill Muench and Dr. C. H. Ting. -

- -

Downloads

- -

µEforth

- -

-A reduced cross-platform EForth version -

- - -

-http://github.com/flagxor/eforth - - Complete Source Code (under ueforth) -

- -

µEforth

- -

µEforth Specific Words

- -
Null Terminated Strings
-

-As null terminated strings are used by virtually all platforms, -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
-
- -
Vocabularies
-

-µEforth uses a hybrid of Forth-79 and Forth-83 style vocabularies. -By default vocabularies chain to the vocabulary in which they were defined, -as in Forth-79. However, like Forth-83, ALSO -can be used to add vocabularies to a vocabulary stack of which -CONTEXT @ is the first item. -The word ONLY clears the vocabulary stack, but as there is -no separate ONLY vocabulary, it also sets CONTEXT -to the FORTH vocabulary. -The word SEALED modifies the most recently defined vocabulary -such that it does not chain. Note, this must be done before words are added to it. -

-
-VOCABULARY ( "name" ) Create a vocabulary with the current vocabulary as parent
-FORTH ( -- ) Make the FORTH vocabulary the context vocabulary
-DEFINITIONS ( -- ) Make the context vocabulary the current vocabulary
-VLIST ( -- ) List the words in the context vocabulary (not chains)
-WORDS ( -- ) List the words in the context vocabulary (including chains)
-TRANSFER ( "name" ) Move a word from its current dictionary to the current vocabulary
-                    Useful for "hiding" built-in words
-ALSO ( -- ) Duplicate the vocabulary at the top of the vocabulary stack
-ONLY ( -- ) Reset context stack to one item, the FORTH dictionary
-            Non-standard, as there's no distinct ONLY vocabulary
-ORDER ( -- ) Print the vocabulary search order
-SEALED ( -- ) Alter the last vocabulary defined so it doesn't chain
-
- -
Blocks
-
-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
-BLOCK ( n -- a ) Get a 1024 byte block
-BUFFER ( n -- a ) Get a 1024 byte block without regard to old contents
-UPDATE ( -- ) Mark the last block modified
-FLUSH ( -- ) Save and empty all buffers
-EMPTY-BUFFERS ( -- ) Empty all buffers
-SAVE-BUFFERS ( -- ) Save all buffers
-SCR ( -- a ) Pointer to last listed block
-
- -
Block Editor
-These words are available inside the EDITOR vocabulary. -
-WIPE ( -- ) Blank out the current block
-L ( -- ) List 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
-P ( -- ) Move to the previous block
-N ( -- ) Move to the next block
-
- -
Utilities
-
-SEE ( "name" -- ) Attempt to decompile a word
-ECHO ( -- a ) -- Address of flag that determines if commands are echoed
-
- -

ESP32 Arduino

- -

ESP32 Arduino Opcodes

- -

-Because Arduino builds a statically linked image for flashing into ESP32 devices, -all C function bindings need to be explicitly added. -This is the current collection. -Typically to reduce confusion, function names have be preserved even through verbose. -In popular cases a shorted higher level name is provided. -

- -

-See arduino.template.ino. -

- -
Allocation
-These words are inside the internals vocabulary. -
-MALLOC ( n -- a | 0 )   System malloc
-SYSFREE ( a -- )   System free
-REALLOC ( a n -- a | 0 )   System realloc
-
- -
Serial
-These words are inside the Serial vocabulary. -
-Serial.begin ( baud -- )   Start serial port
-Serial.end ( -- )   End serial port
-Serial.available ( -- f )   Is serial data available
-Serial.readBytes ( a n -- n )   Read serial bytes, return number gotten
-Serial.write ( a n -- n )   Write serial bytes
-Serial.flush ( -- )   Flush serial buffer
-
- -
Serial Bluetooth
-These words are inside the bluetooth vocabulary. -
-SerialBT.new ( -- bt )   Allocate new BT object
-SerialBT.delete ( bt -- )   Free BT object
-SerialBT.begin ( localname ismaster bt -- f )
-SerialBT.end ( bt -- )
-SerialBT.available ( bt -- f )
-SerialBT.readBytes ( a n bt -- n )
-SerialBT.write ( a n bt -- n )
-SerialBT.flush ( bt -- )
-SerialBT.hasClient ( bt -- f )
-SerialBT.enableSSP ( bt -- )
-SerialBT.setPin ( z bt -- f )
-SerialBT.unpairDevice ( addr bt -- f )
-SerialBT.connect ( remotename bt -- f )
-SerialBT.connectAddr ( addr bt -- f )
-SerialBT.disconnect ( bt -- f )
-SerialBT.connected ( timeout bt -- f )
-SerialBT.isReady ( checkMaster timeout -- f )   Default checkMaster=false, timeout=0
-
- -
Bluetooth
-These words are inside the bluetooth vocabulary. -
-esp_bt_dev_get_address ( -- a ) addr of 6 byte mac address
-
- -
GPIO
-
-pinMode ( pin mode -- )   Set GPIO pin mode
-digitalWrite ( pin value -- )   Set GPIO pin state
-analogRead ( pin -- n )   Analog read from 0-4095
-
- -
ledc
-These words are inside the ledc vocabulary. -
-ledcSetup ( channel freq resolution -- freq )
-ledcAttachPin ( pin channel -- )
-ledcDetachPin ( pin -- )
-ledcRead ( channel -- n )
-ledcReadFreq ( channel -- freq )   Get frequency (x 1,000,000)
-ledcWrite ( channel duty -- )
-ledcWriteTone ( channel freq )   Write tone frequency (x 1000)
-ledcWriteNote ( channel note octave -- freq )
-
- -
Short GPIO Names
-
-pin ( value pin# -- )   Set GPIO pin value
-adc ( pin# -- n )   Analog read pin, result 0-1023
-
- -
System
-
-MS ( n -- )
-TERMINATE ( n -- ) Call system exit
-
- -
Files
-
-R/O ( -- mode )
-R/W ( -- mode )
-W/O ( -- mode )
-BIN ( mode -- mode )
-CLOSE-FILE ( fh -- ior )
-OPEN-FILE ( a n mode -- fh ior )
-CREATE-FILE ( a n mode -- fh ior )
-DELETE-FILE ( a n -- ior )
-WRITE-FILE ( a n fh -- ior )
-READ-FILE ( a n fh -- n ior )
-FILE-POSITION ( fh -- n ior )
-REPOSITION-FILE ( n fh -- ior )
-FILE-SIZE ( fh -- n ior )
-
- -
WiFi
-These words are inside the WiFi vocabulary. -
-WiFi.config ( ip dns gateway subnet -- )   Packaged a.b.c.d little-endian
-Wifi.begin ( ssid-z password-z -- )
-Wifi.disconnect ( -- )
-WiFi.status ( -- n )
-WiFi.macAddress ( a -- )
-WiFi.localIP ( -- ip )
-WiFi.mode ( mode -- ) WIFI_MODE_NULL WIFI_MODE_STA WIFI_MODE_AP WIFI_MODE_APSTA
-WiFi.setTxPower ( powerx4 -- )   Set power x4
-WiFi.getTxPower ( -- powerx4 )   Get power x4
-
- -
mDNS
-
-MDNS.begin ( name-z -- )   Start multicast dns
-
- -
SPIFFS
-These words are inside the SPIFFS vocabulary. -
-SPIFFS.begin ( format-on-fail path-z max-files -- f )
-SPIFFS.end ( -- )
-SPIFFS.format ( -- f )
-SPIFFS.totalBytes ( -- n )
-SPIFFS.usedBytes ( -- n )
-
- -
WebServer
-These words are inside the WebServer vocabulary. -
-WebServer.new ( port -- ws )   Allocate new webserver object
-WebServer.delete ( ws -- )   Delete webserver object
-WebServer.begin ( port ws -- )
-WebServer.stop ( ws -- )
-WebServer.on ( path-z xt ws -- ) Set up a web path handle callback
-WebServer.handleClient ( ws -- )   Handle one client request
-WebServer.hasArg ( z ws -- f )   By name
-WebServer.arg ( z ws -- z )   By name
-WebServer.argi ( n ws -- z )   By index
-WebServer.argName ( n ws -- z)   By index
-WebServer.args ( ws -- n )   Number of args
-WebServer.setContentLength ( n ws -- )
-WebServer.sendHeader ( name-z value-z fist ws -- )
-WebServer.send ( code mimetype data ws -- )
-WebServer.sendContent ( z ws -- )
-WebServer.method ( ws -- n )   GET / POST etc.
-
- -
Wire
-These words are inside the Wire vocabulary. -
-Wire.begin ( -- f )
-Wire.setPins ( sda scl -- f )
-Wire.setClock ( frequency -- )
-Wire.getClock ( -- frequency )
-Wire.setTimeout ( ms -- ) Default is 50ms
-Wire.getTimeout ( -- ms )
-Wire.lastError ( -- n )
-Wire.getErrorText ( n -- z )
-Wire.beginTransmission ( n -- )
-Wire.endTransmission ( sendstop -- f )
-Wire.requestFrom ( address quantity sendstop -- n )
-Wire.writeTransmission ( addr a n sendstop -- err )
-Wire.readTransmission ( addr a n sendstop acount -- err )
-Wire.write ( a n -- n )
-Wire.available ( -- f )
-Wire.read ( -- ch )
-Wire.peek ( -- ch )
-Wire.busy ( -- f )
-Wire.flush ( -- )
-
- -
Camera
-These words are inside the camera vocabulary. -
-esp_camera_init ( config -- f )
-esp_camera_deinit ( -- f )
-esp_camera_fb_get ( -- fb )
-esp_camera_fb_return ( fb -- )
-esp_camera_sensor_get ( -- sensor )
-
- -
SD_MMC
-These words are inside the SD_MMC vocabulary. -
-SD_MMC.begin ( mount mode1bit )   default mode1bit=false
-SD_MMC.end ( -- )
-SD_MMC.cardType ( -- n )
-SD_MMC.totalBytes ( -- n )
-SD_MMC.usedBytes ( -- n )
-
- -

ESP32 WebUI

- -

-A terminal over the web can be activated. -Contact at port printed or via mDNS http://ueforth/. -

- -
-webui ( network-z password-z -- )
-
- -

Usage:

- -
-z" NETWORK-NAME" z" PASSWORD" webui
-
- -

-See arduino_server.fs. -

- -

Autoexec.fs

- -

-The system will automatically attempt to mount SPIFFS filesystem at /spiffs. -It will then at start attempt to load /spiffs/autoexec.fs -

- -

-One way this feature can be used to configure the Web UI to start by default. -When doing this, be sure to test your Web UI settings work well first. -

- -
-r| z" NETWORK-NAME" z" PASSWORD" webui | s" /spiffs/autoexec.fs" dump-file
-
- -

-To remove a previously configured autoexec.fs you will need -to be able to reboot in a mode with Forth. One way to do this is to search -for the line in the .ino file that refers to autoexec.fs -and replace it with a different name. Then run the following: -

- -
-s" /spiffs/autoexec.fs" delete-file
-
- -

-See autoboot.fs. -

- -

Adding Words

- -

-Adding words based on C functions can be done by editing the source code. -For ESP32 Arduino arduino.template.ino is the appropriate place. -

- -

-Because of the use of X-Macros words can be -added in as little as one line. Locate the macro called PLATFORM_OPCODE_LIST -and add your words there. -

- -

NOTE: Be careful to end each line with a \ so the macros will chain correctly.

- -

-To add a word containing only letters, numbers, and underscore you can use Y. -

- -
-  Y(MY_WORD123, c_function_to_call()) \
-
- -

-If your word name contains other characters, instead use X. -You will need to make up an alternate name for the middle parameter. -It must contain only letters, numbers, and underscore. -The name is not used anywhere else, but must be unique. -

- -
-  X("myword!", MY_WORD_BANG, c_function_to_call()) \
-
- -

-Values from the data stack can be accessed via -the variables tos (Top of Stack) and -sp (Pointer to the rest of the stack). -The stack has the data type cell_t. -

- -

-You can push a value of any type to the stack with the macro PUSH: -

- -
-  Y(MY_WORD, PUSH calculate_magic_value()) \
-
- -

-To simplify calling C functions, you can also refer to elements on the stack -with the types positional names: -

- -
-n10 n9 n8 n7 n6 n5 n4 n3 n2 n1 n0 - Access stack as cell_t integer values
-                   c4 c3 c2 c1 c0 - Access stack as char* values
-                   b4 b3 b2 b1 b0 - Access stack as uint8_t* byte values
-                   a4 a3 a2 a1 a0 - Access stack as void* values
-
-Examples:
-  void send_message(const char *message, int code);
-  ...
-  X("send-message", SEND_MESSAGE, send_message(c1, n0)) \
-
- -

- You can always replace the top item on the stack with SET: -

- -
-  Y(DECODE, SET decode_func(n0)) \
-
- -

- You can drop elements from the stack with DROP - or DROPn(number). - You can nip elements from below top of the stack with NIP - or NIPn(number). - Be aware that like PUSH this will cause stack indices to change. -

- -
-  int my_cool_function(char *foo, int bar, uint8_t *baz);
-  ...
-  Y(MY_FUNC, n0 = my_cool_function(c2, n1, b0); NIPn(2)) \
-
- -

-Multiple C statements can be included in the code area of a word, -but care must be taken to generally avoid {}s. -If you find you need nesting, a separate function is recommended. -

- -

-New variables can be declared in each word and are scoped to that word. -

- -
-  Y(MY_WORD, cell_t foo = n0; DROP; char *x = c0; DROP; \
-             PUSH my_func(foo, x)) \
-
- -

Windows

- -

Windows Opcodes

- -

-The wealth of Windows .DLL and system functionality can be -accessed via the dynamic loading interface. -A handle to a library is obtained with LOADLIBRARYA, -and then individual symbols are accessed with GETPROCADDRESS. -

- -
-LOADLIBRARYA ( dllname-z -- module )
-GETPROCADDRESS ( module name-z -- fn )
-
- -

-And assembly version of */MOD is provided to allow the EXE to build without -including MSVCRT. -

- -

-See windows_main.c. -

- -

-Native functions all called with CALL(n) (see Windows & Linux Calling below). -

- -

Windows Imports

- -

-Various Win32 calls are imported in -windows.fs. -In addition, a terminal that responds to ANSI escape codes is created and connected to -TYPE and KEY. -

- -

Linux

- -

Linux Opcodes

- -

-Linux libraries and the operating system can be accessed via the use -of the DLSYM word. Functions can be requested by name from -particular modules. As the dynamic linking module is already loaded initially, -a 0 for the module allows the library loading function (dlopen) -to be loaded from Forth. -

- -
-DLSYM ( module name-z -- fn )
-
- -

-See posix_main.c. -

- -

-Native functions all called with CALL(n) (see Windows & Linux Calling below). -

- -

Linux Imports

- -

-Various Linux calls including Xlib are imported in -posix.fs and -xlib.fs. -In addition, TYPE and KEY are connected to -stdin and stdout. -

- -

Windows & Linux Calling

- -

-As unfortunately both Windows and Linux have system and library calls with -as many as 10 parameters (for example XCreateImage), -a collection of calling thunks is required. -A single varidic thunk would be ideal, but is hard to do without per platform -assembly language. -

- -
-CALL0 ( fn -- n )
-CALL1 ( n fn -- n )
-CALL2 ( n n fn -- n )
-CALL3 ( n n n fn -- n )
-CALL4 ( n n n n fn -- n )
-CALL5 ( n n n n n fn -- n )
-CALL6 ( n n n n n n fn -- n )
-CALL7 ( n n n n n n n fn -- n )
-CALL7 ( n n n n n n n n fn -- n )
-CALL9 ( n n n n n n n n n fn -- n )
-CALL10 ( n n n n n n n n n n fn -- n )
-
- -

-See calling.h. -

- -

Web

- -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
-CURRENT   --- Pointer to pointer to last word of current vocabulary
-CONTEXT   --- Pointer to pointer to last word of context vocabulary
-
-'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

- -

-esp32Forth - Version 6.3 for NodeMCU ESP32S - Tweaked for the Web -

- - - -

Classic EForth Quirks

- -

-EForth uses FOR..NEXT in favor of DO..LOOP. -Details -

- -

-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. +Choose you platform above.

diff --git a/ueforth/site/internals.html b/ueforth/site/internals.html new file mode 100644 index 0000000..a75c0ca --- /dev/null +++ b/ueforth/site/internals.html @@ -0,0 +1,94 @@ + + + +ESP32forth + + + +

µEforth Internals

+ +
+ ESP32forth + Linux + Windows + Internals + Classic +
+ +

+µ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
+CURRENT   --- Pointer to pointer to last word of current vocabulary
+CONTEXT   --- Pointer to pointer to last word of context vocabulary
+
+'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. +

+ diff --git a/ueforth/site/linux.html b/ueforth/site/linux.html new file mode 100644 index 0000000..dc93882 --- /dev/null +++ b/ueforth/site/linux.html @@ -0,0 +1,187 @@ + + + +Linux + + + +

µEforth Linux

+ +
+ ESP32forth + Linux + Windows + Internals + Classic +
+ +

Download

+ +

+ueforth-{{VERSION}}.linux + - Linux 64-bit Executable µEforth +

+ +

+http://github.com/flagxor/eforth + - Complete Source Code (under ueforth) +

+ +

µEforth

+ +

µEforth Specific Words

+ +
Null Terminated Strings
+

+As null terminated strings are used by virtually all platforms, +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
+
+ +
Vocabularies
+

+µEforth uses a hybrid of Forth-79 and Forth-83 style vocabularies. +By default vocabularies chain to the vocabulary in which they were defined, +as in Forth-79. However, like Forth-83, ALSO +can be used to add vocabularies to a vocabulary stack of which +CONTEXT @ is the first item. +The word ONLY clears the vocabulary stack, but as there is +no separate ONLY vocabulary, it also sets CONTEXT +to the FORTH vocabulary. +The word SEALED modifies the most recently defined vocabulary +such that it does not chain. Note, this must be done before words are added to it. +

+
+VOCABULARY ( "name" ) Create a vocabulary with the current vocabulary as parent
+FORTH ( -- ) Make the FORTH vocabulary the context vocabulary
+DEFINITIONS ( -- ) Make the context vocabulary the current vocabulary
+VLIST ( -- ) List the words in the context vocabulary (not chains)
+WORDS ( -- ) List the words in the context vocabulary (including chains)
+TRANSFER ( "name" ) Move a word from its current dictionary to the current vocabulary
+                    Useful for "hiding" built-in words
+ALSO ( -- ) Duplicate the vocabulary at the top of the vocabulary stack
+ONLY ( -- ) Reset context stack to one item, the FORTH dictionary
+            Non-standard, as there's no distinct ONLY vocabulary
+ORDER ( -- ) Print the vocabulary search order
+SEALED ( -- ) Alter the last vocabulary defined so it doesn't chain
+
+ +
Blocks
+
+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
+BLOCK ( n -- a ) Get a 1024 byte block
+BUFFER ( n -- a ) Get a 1024 byte block without regard to old contents
+UPDATE ( -- ) Mark the last block modified
+FLUSH ( -- ) Save and empty all buffers
+EMPTY-BUFFERS ( -- ) Empty all buffers
+SAVE-BUFFERS ( -- ) Save all buffers
+SCR ( -- a ) Pointer to last listed block
+
+ +
Block Editor
+These words are available inside the EDITOR vocabulary. +
+WIPE ( -- ) Blank out the current block
+L ( -- ) List 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
+P ( -- ) Move to the previous block
+N ( -- ) Move to the next block
+
+ +
Utilities
+
+SEE ( "name" -- ) Attempt to decompile a word
+ECHO ( -- a ) -- Address of flag that determines if commands are echoed
+
+ +

Linux

+ +

Linux Opcodes

+ +

+Linux libraries and the operating system can be accessed via the use +of the DLSYM word. Functions can be requested by name from +particular modules. As the dynamic linking module is already loaded initially, +a 0 for the module allows the library loading function (dlopen) +to be loaded from Forth. +

+ +
+DLSYM ( module name-z -- fn )
+
+ +

+See posix_main.c. +

+ +

+Native functions all called with CALL(n) (see Windows & Linux Calling below). +

+ +

Linux Imports

+ +

+Various Linux calls including Xlib are imported in +posix.fs and +xlib.fs. +In addition, TYPE and KEY are connected to +stdin and stdout. +

+ +

Windows & Linux Calling

+ +

+As unfortunately both Windows and Linux have system and library calls with +as many as 10 parameters (for example XCreateImage), +a collection of calling thunks is required. +A single varidic thunk would be ideal, but is hard to do without per platform +assembly language. +

+ +
+CALL0 ( fn -- n )
+CALL1 ( n fn -- n )
+CALL2 ( n n fn -- n )
+CALL3 ( n n n fn -- n )
+CALL4 ( n n n n fn -- n )
+CALL5 ( n n n n n fn -- n )
+CALL6 ( n n n n n n fn -- n )
+CALL7 ( n n n n n n n fn -- n )
+CALL7 ( n n n n n n n n fn -- n )
+CALL9 ( n n n n n n n n n fn -- n )
+CALL10 ( n n n n n n n n n n fn -- n )
+
+ +

+See calling.h. +

diff --git a/ueforth/site/static/espforth.ino b/ueforth/site/static/ESP32forth-6.3.0.ino similarity index 100% rename from ueforth/site/static/espforth.ino rename to ueforth/site/static/ESP32forth-6.3.0.ino diff --git a/ueforth/site/static/eforth.css b/ueforth/site/static/eforth.css new file mode 100644 index 0000000..f7b0dc5 --- /dev/null +++ b/ueforth/site/static/eforth.css @@ -0,0 +1,67 @@ +body { + max-width: 800px; + margin-top: 0px; +} +h1 { + border-top: 3px solid #777; + background-color: #111; + color: #eee; + padding: 10px; + margin: 0px; +} +h2 { + border-top: 2px solid #777; + background-color: #ccc; + padding: 10px; +} +h3 { + border-top: 1px solid #777; + background-color: #eee; + padding: 10px; +} +h5 { + margin: 2px; +} +a:link { + color: #00c; +} +a:visited { + color: #00c; +} +a:active { + color: #0f0; +} +a:hover { + color: #0f0; +} +.menu { + background-color: #333; + border-top: 3px solid #777; + padding: 10px; +} +.menu span { + margin: 0px; + padding: 10px; +} +.menu a:link { + color: #fff; +} +.menu a:visited { + color: #fff; +} +.menu a:active { + color: #0f0; +} +.menu a:hover { + color: #0f0; +} +.menu .picked { + background-color: #070; +} +.menu .picked a:active { + color: #fff; +} +.menu .picked a:hover { + color: #fff; +} + diff --git a/ueforth/site/windows.html b/ueforth/site/windows.html new file mode 100644 index 0000000..133dd8f --- /dev/null +++ b/ueforth/site/windows.html @@ -0,0 +1,197 @@ + + + +EForth + + + +

µEforth Windows

+ +
+ ESP32forth + Linux + Windows + Internals + Classic +
+ +

Download

+ +

+uEf32-{{VERSION}}.exe + - Window 32-bit EXE µEforth +

+ +

+uEf64-{{VERSION}}.exe + - Window 64-bit EXE µEforth +

+ +

+http://github.com/flagxor/eforth + - Complete Source Code (under ueforth) +

+ +

µEforth

+ +

µEforth Specific Words

+ +
Null Terminated Strings
+

+As null terminated strings are used by virtually all platforms, +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
+
+ +
Vocabularies
+

+µEforth uses a hybrid of Forth-79 and Forth-83 style vocabularies. +By default vocabularies chain to the vocabulary in which they were defined, +as in Forth-79. However, like Forth-83, ALSO +can be used to add vocabularies to a vocabulary stack of which +CONTEXT @ is the first item. +The word ONLY clears the vocabulary stack, but as there is +no separate ONLY vocabulary, it also sets CONTEXT +to the FORTH vocabulary. +The word SEALED modifies the most recently defined vocabulary +such that it does not chain. Note, this must be done before words are added to it. +

+
+VOCABULARY ( "name" ) Create a vocabulary with the current vocabulary as parent
+FORTH ( -- ) Make the FORTH vocabulary the context vocabulary
+DEFINITIONS ( -- ) Make the context vocabulary the current vocabulary
+VLIST ( -- ) List the words in the context vocabulary (not chains)
+WORDS ( -- ) List the words in the context vocabulary (including chains)
+TRANSFER ( "name" ) Move a word from its current dictionary to the current vocabulary
+                    Useful for "hiding" built-in words
+ALSO ( -- ) Duplicate the vocabulary at the top of the vocabulary stack
+ONLY ( -- ) Reset context stack to one item, the FORTH dictionary
+            Non-standard, as there's no distinct ONLY vocabulary
+ORDER ( -- ) Print the vocabulary search order
+SEALED ( -- ) Alter the last vocabulary defined so it doesn't chain
+
+ +
Blocks
+
+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
+BLOCK ( n -- a ) Get a 1024 byte block
+BUFFER ( n -- a ) Get a 1024 byte block without regard to old contents
+UPDATE ( -- ) Mark the last block modified
+FLUSH ( -- ) Save and empty all buffers
+EMPTY-BUFFERS ( -- ) Empty all buffers
+SAVE-BUFFERS ( -- ) Save all buffers
+SCR ( -- a ) Pointer to last listed block
+
+ +
Block Editor
+These words are available inside the EDITOR vocabulary. +
+WIPE ( -- ) Blank out the current block
+L ( -- ) List 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
+P ( -- ) Move to the previous block
+N ( -- ) Move to the next block
+
+ +
Utilities
+
+SEE ( "name" -- ) Attempt to decompile a word
+ECHO ( -- a ) -- Address of flag that determines if commands are echoed
+
+ +

Windows

+ +

Windows Opcodes

+ +

+The wealth of Windows .DLL and system functionality can be +accessed via the dynamic loading interface. +A handle to a library is obtained with LOADLIBRARYA, +and then individual symbols are accessed with GETPROCADDRESS. +

+ +
+LOADLIBRARYA ( dllname-z -- module )
+GETPROCADDRESS ( module name-z -- fn )
+
+ +

+And assembly version of */MOD is provided to allow the EXE to build without +including MSVCRT. +

+ +

+See windows_main.c. +

+ +

+Native functions all called with CALL(n) (see Windows & Linux Calling below). +

+ +

Windows Imports

+ +

+Various Win32 calls are imported in +windows.fs. +In addition, a terminal that responds to ANSI escape codes is created and connected to +TYPE and KEY. +

+ +

Windows & Linux Calling

+ +

+As unfortunately both Windows and Linux have system and library calls with +as many as 10 parameters (for example XCreateImage), +a collection of calling thunks is required. +A single varidic thunk would be ideal, but is hard to do without per platform +assembly language. +

+ +
+CALL0 ( fn -- n )
+CALL1 ( n fn -- n )
+CALL2 ( n n fn -- n )
+CALL3 ( n n n fn -- n )
+CALL4 ( n n n n fn -- n )
+CALL5 ( n n n n n fn -- n )
+CALL6 ( n n n n n n fn -- n )
+CALL7 ( n n n n n n n fn -- n )
+CALL7 ( n n n n n n n n fn -- n )
+CALL9 ( n n n n n n n n n fn -- n )
+CALL10 ( n n n n n n n n n n fn -- n )
+
+ +

+See calling.h. +

+