c4a: a Forth system for PCs and Arduino, inspired by ColorForth and Tachyon

ColorForth's influence on c4a

• c4a supports control characters (tags) in the whitespace that change the state.
• c4a has 4 states: INTERPRET, COMPILE, DEFINE, AND COMMENT.
• c4a also supports the standard state-change words.
• c4a has a built-in editor. It has a VI-like feel.
• • For details, see the Editor documentation.
• c4a has 'a', 'b', and 't' words.
• c4a reads 'blocks.fth' into memory on load.
• • This is what it uses to edit and load blocks.

Tags

NOTE: In the DEFINE state, c4a changes the state to COMPILE after adding the next word.
NOTE: Unlike ColorForth, ';' compiles EXIT and then changes the state to INTERPRET.

Tachyon's influence on c4a

• In c4a, a program is a sequence of WORD-CODEs.
  
• A WORD-CODE is a 16-bit unsigned number.
  
• Primitives are assigned numbers sequentially from 0 to [BYE].
  
• If a WORD-CODE is less than or equal to [BYE], it is a primitive.
  
• If the top 4 bits are set, it is 13-bit unsigned literal, 0-$0FFF.
  
• If it is between 'BYE' and $F000, it is the code address of a word to execute.
  

Development board considerations

• c4a is intended to be used with development boards via the Arduino IDE.
• However, it can be built for PCs as well for testing.
• I am not aware of 64-bit dev boards.
• So a CELL in c4a is 32-bits.
• C4A has many built-in primitives, for the following reasons:
• • Program flash is often quite large, so why not use it?
• • To give C4A more functionality out of the box.
• • C4A also runs faster because of it.

Building c4a

PCs - Windows and Linux, and probably others

• Windows: there is a c4a.sln file for Visual Studio
  • only the x86 target (32-bit) is supported.
• Linux: there is a makefile.
  • only the 32-bit configuration (-m32) is supported.
• Others:
  • c4a is simple enough that it should be easy to migrate it to any platform.

Development boards via the Arduino IDE:

• I use the Arduino IDE v2.x
• There is a c4a.ino file
• File 'c4a.h' controls parameters for the target board
• Edit the section where IS_BOARD is defined to set the configuration for the board
• Use #define FILE_NONE to disable support for blocks and LittleFS
• For the RPI Pico:
  • Use the arduino-pico from earlephilhower (https://github.com/earlephilhower/arduino-pico)
  • The version must be 4.2.0 or later. Versions older than 4.0.0 do not support boards using the RP2350 microcontroller.
  • Use #define FILE_PICO to include support for LittleFS
• For the Teensy-4.x:
  • Use #define FILE_TEENSY to include support for LittleFS

c4a memory areas

c4a provides a single memory area. See 'mem-sz' (MEM_SZ in c4a.h) for its size.

• It is broken into 3 areas: CODE, VARS, and DICTIONARY.
• The CODE area is an aray of WORD-CODEs starting at the beginning of the memory.
  • here is an offset into the CODE area.
  • The size of the CODE area is code-sz. See CODE_SZ in c4a.h.
  • NOTE: Use wc@ and wc! to get and set 16-bit values in the code area.
  • NOTE: Use cv@ and cv! to get and set 32-bit values in the code area.
  • NOTE: CODE slots 0-25 (0 wc@ .. 25 wc@) are reserved for c4a system values.
  • NOTE: CODE slots 26-(BYE) are unused by c4a.
  • NOTE: Using wc@ and wc!, c4a provides storage space for many 16-bit variables.
  • NOTE: Using cv@ and cv!, c4a provides storage space for many 32-bit variables.
  • NOTE: These are free for the user/application to use as desired.
• The VARS area is defined to begin at address code-sz wc-sz * memory +.
  • vhere is the absolute address of the first free byte the VARS area.
• The DICTIONARY is at the end of the memory. 'last' grows toward the beginning of the memory.
  • last is the address of the most recently created word.
  • A dictionary entry is [xt:2][flags:1][len:1][name:NAME_LEN][0:1]
  • The default NAME_LEN is 11 (see c4a.h), so 'de-sz' is 16.
• Use ->memory to turn an offset into an address.

c4a Strings

Strings in c4a are NULL-terminated with no count byte.

Format specifiers in ftype and ."

Similar to the printf() function in C, c4a supports formatted output using '%'.
For example : ascii dup dup dup ." char: %c, decimal: #%d, binary: %%%b, hex: $%x%n" ;.

The editor

c4a has a built-in editor. It colorizes the code based on tags in the text.
For details, see the Editor documentation.
NOTE: Saving a block updates the block in the RAM-disk.
NOTE: It does NOT automatically write that block to disk.
NOTE: Use 'flush' to write it back to disk/flash.

The A, B, and T stacks

c4a includes A, B, and T stacks.
These are somewhat similar to ColorForth's operations for a and b, but in c4a, they are stacks.
The size of the stacks is configurable (see stk-sz).
The words below are available for all 3 stacks.
Note that there are also additional words r! r@+ and r@- for the return stack.

Temporary words

c4a provides 10 temporary words, 't0' .. 't9'.

• They are case-sensitive.
• • 't0' is a temporary word; 'T0' is NOT.
• They do not take valuable dictionary space.
• They can be used to improve factoring, or as variable or constant names.
• t0:t5 are normal words, t6:t9 are INLINE.

Tasks

• c4a supports a simple cooperative multi-tasking system.
• The task system is not preemptive.
• Words add-task (xt--n), yield (--), del-task (n--) are provided.
• Each task has its own data stack, return stack, and loop stack.
• The A, B, and T stacks are shared by all tasks.

c4a WORD-CODE primitives

NOTE: Since c4a is intended for dev boards, it has many more primitives than C4.
This is primarily because there is more program memory than RAM.
It provides more built-in functionality.
And the system is faster.

The primitives in c4a:

c4a default words

Default/built-in words are defined in function sys_load() in file sys-load.cpp.
For details, or to add or change the default words, modify that function.