[hemmerling] FORTH 7/7 - H2oForth

Related pages:

• Textual and Graphical Modeling by Domain Specific Languages.
• Embedded Systems.
• FORTH 1/7.
• FORTH 2/7 - Hardware, Commercial Products & Services, Intellectual Property ( IP ).
• FORTH 3/7.
• FORTH 4/7.
• FORTH 5/7.
• FORTH 6/7.
• Virtual Machines, P-Code & Byte-Code Interpreters.
• WebAssembly ( WASM ).

1. Chameleon FORTH.
2. Dolly FORTH ( from EN.Wikipedia "Dolly (sheep)".
3. Clone FORTH.

• Implementation & Host environment:
  • Single C file, with some configurable include files. So you don´t need a linker file nor a make file, nor an IDE project. I.e. easy compilation and execution file generation, on any host, for any target.
  • Host operating systems: MSDOS, Windows, Linux.
    • Therefore, just filenames according to 8+3 naming convention are used. No exceptions! No excuse!
• Targets:
  • Operating systems with file i/o:
    • MSDOS, Windows, x86 / amd64 Linux.
  • Embedded bare-metal systems:
    • Arduino hardware platform, with Atmel AVR MCUs.
    • ...
• Configuration at compile time:
  • You may select one word list among word lists of several popular FORTH implementations ( Personal computers of the early 1980th with FORTH as first and single or additional programming language, FORTH ROMs for personal computers of the late 1970th and early 1980th, figFORTH-, FORTH79- and FORTH83 implementations, minimal FORTH systems,...).
    • If I was able to run the FORTH implementation on my computer, e.g. on an emulator, or if I was able to ask a Forther who is running the FORTH implementation on own machine, I took the original word list order as printed by FORTH words like “VLIST” or “WORDS”, for my own wordlist implementation. Usually, the order of the words as printed by FORTH words like “VLIST” or “WORDS” shows the reverse dependancy of the FORTH words: First words in the FORTH word list depend on FORTH words printed later.
    • Just in a few cases, where I had just printed documentation but no running FORTH, I used the order as printed in the documentation.
• Configuration at runtime:
  • Optional terminal input and keyboard input.
    • If just terminal input in enabled, CTRL-Z closes the application, after the next RETURN.
    • If just keyboard input in enabled, CTRL-Z closes the application, immediately.
    • If first terminal input, later keyboard input: CTRL-Z switches from terminal input to keyboard input, after the next return. If you then type CTRL-Z at keyboard input, the application is closed immediately.
  • Output redirection ( by terminal output ).
  • Input redirection ( if terminal input is active ).

1. Supported Architectures: Support for both the common “Von Neumann architecture” EN.Wikipedia "Von Neumann architecture" and the rare “Harvard architecture” ( EN.Wikipedia "Harvard architecture" ).
   • With “Harvard architecture”, read-only data, e.g. struct tables and strings, is stored in ( Flash ) ROM. For the ARDUINO AVR C/C++ compiler, this is achieved by adding the keyword “PROGMEM” to such read-only data. To access the data, special code is necessary, e.g. “pgm_read_ptr()”.
2. Planned support for a large number of wordsets of historical FORTH implementations, if possible ( Note that not yet all wordsets are implemented, i.e. all FORTH wordsets after FORTH83 & VolksForth are not yet implemented ).
   1. #define AIM65_FORTH 1
   2. #define ATARICOINUP_FORTH 2
   3. #define BBCMICRO_FORTH 3
   4. #define BIG_FORTH 4
   5. #define CAMEL_FORTH 5
   6. #define COLOR_FORTH 6
   7. #define E_FORTH 7
   8. #define FIG_FORTH 8
   9. #define FORTH79 9
   10. #define FORTH79_REQ_DBL_ASM_EXP_REF 10
   11. #define FORTH79_NUC_INTERP_COMP 11
   12. #define FPC_FORTH 12
   13. #define GNU_FORTH 13
   14. #define HECTOR_FORTH 14
   15. #define JUPITER_FORTH 15
   16. #define KNAGGSBENNET_FORTH 16
   17. #define LAXONPERRY_FORTH 17
   18. #define LAXONPERRY_PC_FORTH 18
   19. #define LAXONPERRY_CPM_FORTH 19
   20. #define LAXONPERRY_CPM68K_FORTH 20
   21. #define LMI_FORTH 21
   22. #define LMI_MSDOS_FORTH 22
   23. #define LMI_WIN_FORTH 23
   24. #define MECRISP_FORTH 24
   25. #define MVP_FORTH 25
   26. #define NELSON_FORTH 26
   27. #define NELSON_ESP_FORTH 27
   28. #define NELSON_UE_FORTH 28
   29. #define PATEL_FORTH 29
   30. #define Q_FORTH 30
   31. #define RCAMICRO_FORTH 31
   32. #define RSC_FORTH 32
   33. #define SECTOR_FORTH 33
   34. #define TERSE_FORTH 34
   35. #define VOLK_FORTH 35
   36. #define VOLK_C64_FORTH 36
   37. #define VOLK_ST_FORTH 37
   38. #define VOLK_CPM_FORTH 38
   39. #define VOLK_PC_FORTH 39
   40. #define WIN32_FORTH 40
3. Providing of the original error messages of historical FORTH implementations ( if available as list, e.g. printed in a manual ).
4. Option for “DoublePrecision Integer” ( just if sizeof(LONG_LONG)>sizeof(int). Not available with Arduino AVR C/C++ and Borland C++ 5.5.1 ).
5. Option for “Float” ( So far, Brad Nelson's “ESP32Forth v.7.05” and “Jupiter Ace” the only FORTH implementation with built-in Float words, for which I implemented a FORTH wordlist )
6. Planned support of several C architectures ( XXYYZZBit = Int=XX, PTR=YY, Long(Long)=ZZ ):
   1. #define SYSTEM_ARCHITECTURE_HOST 0
   2. #define SYSTEM_ARCHITECTURE_081616BIT 1
   3. #define SYSTEM_ARCHITECTURE_161632BIT 2
   4. #define SYSTEM_ARCHITECTURE_323232BIT 3
   5. #define SYSTEM_ARCHITECTURE_326464BIT 4
   6. #define SYSTEM_ARCHITECTURE_646464BIT 5
   7. #define SYSTEM_ARCHITECTURE_6464128BIT 6

*MinGW - Minimalist GNU for Windows”, version 6.3 - My choice, as this is the development system for Lua 6.3. *Sourceforge "MinGW - Minimalist GNU for Windows".

• For proper download and installation, you MUST use “mingw-get-setup.exe” of Sourceforge "MinGW - Minimalist GNU for Windows" - "Installer".
  • Install:
    1. mingw-developer-tookit.
    2. mingw32-base.
    3. mingw32-gcc-g++.
    4. mingw32-gcc-objc.
    5. msys-base.
• To test if you properly installed MinGW, use Windows CMD, not Powershell. CMD reports missing DLLs ( “The code execution cannot proceed because XXX.dll was not found. Reinstalling the program may fix this problem” ), while Powershell quits without notice .
• The IDE Visual Studio Code ( VSC ).
  • VSC plugin Visual Studio Marketplace, Microsoft "C/C++".
• The Public Domain OpenSource database SQlite.

• See Software Development Tools ⇒ “Microsoft Visual Studio Code”.
• Create a VSC workspace file ( “C:\Users\<user>\AppData\Roaming\Code\Workspaces\<id>\workspace.json” ) ???
• ”.gitignore”:

  # Batch files
  # No need to synchronize batch files?
  #**/*.bat
  
  # VisualStudio Code
  # Just synchronize ".vscode/launch.json" and ".vscode/tasks.json".
  
  # MinGW 6.3.0
  # No need to synchronize executable files (*.exe)
  **/*.exe
  
  # VisualStudio 2019 Community Edition
  # Just synchronize the solution "*.sln" and project files "*.vcxproj", ".vcxproj.filters", ".vcxproj.user"
  # No need to synchronize the DEBUG and .vs directories
  **/DEBUG
  **/.vs
  
  # OpenWATCOM-C/C++ 1.9
  # Just synchonize IDE project "*.wpj" and compilation target "*.tgt"  
  **/*.err
  **/*.exe
  **/*.lk1
  **/*.map
  **/*.mk
  **/*.mk1
  **/*.obj
  **/*.sym
  
  # Borland C/C++ 5.5 commandline tools
  # Just synchonize the configuration file "bcc32.cfg"
  **/*.exe
  **/*.obj
  **/*.tds
  
  # Borland C/C++ 5.02
  # Just synchonize the configuration file "*.ide"
  **/*.exe
  **/*.obj
  **/*.csm
  **/*.~de
  **/*.DSW
  **/*.mbt
  **/*.mrt
  **/*.r$p
  
  # DJGPP 2.05 on MSDOS, DJGPP 10.20 Cross Compiler on Windows
  **/*.exe
  **/*.out
  **/*.ilc
  **/*.ild
  **/*.ilf
  **/*.ils
  
  # Digital Mars, Datalight C, Zorland C, Zortech C and Zortech C++, Symantec C++ 
  **/*.exe
  **/*.map
  **/*.obj
  

• Read characters from terminal and keyboard.

• Read characters from according to command line interface options, i.e. from terminal, keyboard, file, block file...

• Collect wordlists of popular FORTH implementations and FORTH norms.
• Implement several alternative or additive FORTH tables with a structure which includes
  1. Name of a FORTH Word.
  2. WordID - a unique number of each FORTH word.
  3. Pointer to the function which represents the code of the FORTH word.
• Implement dummy ( = empty ) C functions for each word.

• Implement a few words and functions in C, so that you can add 2 numbers of any base. Let words to be executed by function pointer.
  1. ”+”, ”.”, ”.S”.
  2. “DECIMAL”, “OCTAL”, “HEX”, “BASE”, ”!”, ”@”, “C!”, “C@”.
  3. “R!”, “R@”, “R.S” (?).
  4. Internal function: Display a number in a given base.

• Implement some code in C, so that you can handle errors.
• Implement the word “Error”.

• Porting of the project to a Havard Architecture hardware ( EN.Wikipedia "Harvard architecture", DE.Wikipedia "Harvard-Architektur" ), i.e. to Atmel AVR C/C++ compiler for Arduino boards.
  1. Add the PROGMEM attribut to all read-only ( string & typedef ) data, so that it is put into Flash ROM. Note that read-only is not 100% equivalent to the C attributes “static constant”.
  2. Modify the C code so that properly addresses the PROGMEM data.

• Extend the FORTH vocabulary record for a FORTH word by:
  1. Unique ID of a Forth word.
  2. Start Index of the FORTH word implementation, in the FORTH word definition space.
  3. Number of instructions occupied in the FORTH word definition space, for this FORTH word.
• Number each FORTH word of any given FORTH vocabulary with a unique ID. If you have several FORTH vocabularies, pass blocks of numbers to each vocabulary.
  • Start with ID 0 with first FORTH vocabulary, with ID 1000 with next vocabulary.
  • Note that FORTH words of alternative FORTH vocabularies are given WordIDs by the same block of numbers.
• Create FORTH word definition list with name of FORTH word, FORTH word definition space with the list of FORTH WordIDs for each defined FORTH Word.
• Create a statically defined FORTH word, as a set of instructions which add a FORTH word to the FORTH word definition list and implement action by linking a set of WordIDs stored in the FORTH word definition space, to that FORTH word definition.
  • Example:
    • The new FORTH word “PLUS”, defined in the FORTH word definition list, points to a special section of the FORTH word definition space, where the WordID of the permanent FORTH word ”+” is stored.
    • The new FORTH word “PLUSPLUS”, defined in the FORTH word definition list, points to a special section of the FORTH word definition space, where 2 times, the WordID of the permanent FORTH word ”+” is stored.
• Let words to be executed by WordID.

• Separate outer interpreter ( the input parser, feed by the command line interface ) from the inner interpreter ( the Forth virtual machine ).

• Create the words ”:”, ”;”, “LIT”, “LITERAL”, ”[”, ”]” “QUIT” and the internal word “NEXT”.
• Implement the option to create FORTH words dynamically, at runtime.