mirror of
https://github.com/dschmenk/PLASMA.git
synced 2025-01-03 19:31:10 +00:00
124 lines
4.4 KiB
Markdown
124 lines
4.4 KiB
Markdown
# FORTH PLASMA + PLFORTH !
|
|
|
|
PLFORTH represents a REPL and scripting language for the PLASMA environment. Or, what I did over the Holiday break.
|
|
|
|
The goals of PLFORTH are pretty straight forward:
|
|
**Interactivity** and **debugging**.
|
|
|
|
PLFORTH is a PLASMA module written in PLASMA itself. As a first class citizen of the PLASMA environment, it has instant access to all the PLASMA modules, from floating point to high-res graphics libraries and everything in between.
|
|
|
|
## Missing words in PLFORTH
|
|
|
|
There are quite a few missing word that a standard FORTH would have. Mostly due to deliberately keeping PLFORTH as minimal as possible to reduce the memory footpring and load time. Most of the missing words can be synthesized using existing PLASMA modules and some glue words. The double word have mostly been made avialable through PLASMA's 32 bit integer module, `INT32` by way of the `int32.4th` script. You can always petition to get your favorite FORTH word included in the default vocabulary. Speaking of `VOCABULARY`, PLFORTH only has one.
|
|
|
|
## PLFORTH built-in words
|
|
|
|
|
|
|
|
## PLFORTH specific words
|
|
|
|
### Words for looking at internal structures:
|
|
|
|
`.RS`: Displays the return stack. Note: PLFORTH uses a software defined return stack, this is not the hardware stack
|
|
|
|
### Words for tracing and single stepping execution:
|
|
|
|
`TRON`: Turn tracing on
|
|
|
|
`TROFF`: Turn tracing off (will also turn off single stepping if enabled)
|
|
|
|
`STEPON`: Turn single stepping on
|
|
|
|
`STEPOFF`: Turn single stepping off
|
|
|
|
While running code, `<CTRL-T>` will toggle tracing on and off as well
|
|
|
|
### Words for breakpoints:
|
|
|
|
`BRK`: Used inside compiled word to effect a runtime break
|
|
|
|
`BRKON xxxx`: Enable breakpoint whenever word `xxxx` is executed
|
|
|
|
`BRKOFF`: Disable the breakpoint. Note: only one breakpoint is currently supported
|
|
|
|
While running code, `<CTRL-C>` will break out and return to the interpreter.
|
|
|
|
`CONT`: Continue running from the last break point
|
|
|
|
### Words for PLASMA linkage:
|
|
|
|
`LOOKUP yyyy`: Lookup symbol `yyyy` in PLASMA symbol table and return its address
|
|
|
|
`PLASMA zzzz`: Create word `zzzz` with code address from `LOOKUP`
|
|
|
|
### Words to run a script:
|
|
|
|
`SRC`: Source filename on stack as input. Can be nested
|
|
|
|
`SRC" ssss"`: Source file `ssss` as input. Can be nested
|
|
|
|
`?ENDSRC`: End sourcing file as input if stack flag non-zero
|
|
|
|
`ENDSRC`: End sourcing file as input
|
|
|
|
### Words for compiler modes:
|
|
|
|
`PBC`: Compile into PLASMA Byte Code
|
|
|
|
`ITC`: Compile into Indirect Threaded Code
|
|
|
|
### Word for converting string to number:
|
|
|
|
`NUM?`: Convert string and length to number, returning number and valid flag
|
|
|
|
Numbers entered with a preceeding `$` will be interpreted as hex values
|
|
|
|
### Words for displaying hex numbers
|
|
|
|
`$.`: Display TOS word in hex with leading `$`
|
|
|
|
`C$.`: Display TOS byte in hex with leading `$`
|
|
|
|
## Debugging vs Performance
|
|
|
|
PLFORTH defaults to compiling using ITC (Indirect Threaded Code). This supports a list of inspection and debugging features while developing programs and scripts. However, the compiler can easily switch to PBC (PLASMA Byte Code) to greatly improve performance, but most of the debugging tools are lost. ITC compiled words and PBC compiled words can be intermingled and call each other seemlessly. PLASMA Byte Code is a direct match to many low-level FORTH constructs.
|
|
|
|
## Graphics
|
|
Due to the way the Apple II implements Hi-Res, Lo-Res and Double Lo-Res graphics, a stub loader is required to reserve the pages used.
|
|
|
|
`HRFORTH`: Reserve HGR page 1 before launching PLFORTH
|
|
|
|
`HR2FORTH`: Reserve HGR pages 1 and 2 before launching PLFORTH
|
|
|
|
`TX2FORTH`: Reserve GR and DGR pages 1 and 2 before launching PLFORTH
|
|
|
|
## Scripts
|
|
|
|
There are a few useful scripts located in the `scripts` directory. By far the most useful is `plasma.4th`
|
|
|
|
### plasma.4th useful words
|
|
|
|
`CAT`: Display files in current ProDOS directory
|
|
|
|
`CAT" pppp"`: Display files in `pppp` ProDOS directory
|
|
|
|
`PFX" pppp"`: Set current ProDOS prefix to `pppp`
|
|
|
|
`PFX.`: Display current ProDOS prefix
|
|
|
|
`EDIT" ssss"`: Edit file `ssss`
|
|
|
|
## Command line options
|
|
|
|
`-F`: Fast flag (like `PCB` as first command)
|
|
|
|
`-T`: Trace flag (like `TRON` as first command)
|
|
|
|
`SCRIPT NAME`: Soure filename to execute
|
|
|
|
## Links
|
|
|
|
Here is a (worse than usual) video running through some examples. This was a preliminary release so the final is a bit different: https://youtu.be/picPyXAk77I?si=Td2En5Z3oxVTzh0z
|
|
|
|
A pre-configured ProDOS floppy image able to run and a few utilities is available here: https://github.com/dschmenk/PLASMA/blob/master/images/apple/PLFORTH.PO
|