Common Lisp implementation of the Forth 2012 Standard, CL-Forth
CL-Forth is fully supported by CCL v1.12.2-82 or later.
CL-Forth is fully supported by SBCL 2.1.0 or later.
CL-Forth supports LispWorks 8.0.1 or later. However, at present, the word RESIZE-FILE
will always return an error indication,
resulting in 7 failures in the File-Access word set tests.
CL-Forth compiles under ECL 24.5.10 but crashes running the Forth test suite.
CL-Forth is supported on macOS, Linux, and Windows.
On macOS, it has been verified to run on macOS Ventura or later.
On Linux, it has been verified to run on distributions with 5.10.162 kernels or later.
On Windows, it has been verified to run on Windows 10 or later.
CL-Forth is made available under the terms of the MIT License.
CL-Forth is defined using ASDF and is dependent on the CFFI and trivial-gray-streams libraries.
To fetch a copy of CL-Forth and the Forth 2012 Test Suite configured to only run tests for those word sets implemented by CL-Forth.
git clone https://github.com/gmpalter/cl-forth.git --recurse-submodules
To load CL-Forth into Lisp
(require '#:asdf)
(load "cl-forth.asd")
(asdf:load-system '#:cl-forth)
You can run the Forth 2012 Test Suite
(asdf:test-system '#:cl-forth)
To start the CL-Forth interpreter loop
(forth:run)
CL-Forth is case-insensitive.
You can build a standalone CL-Forth application.
Launch Lisp and evaluate the forms
(require '#:asdf)
(load "cl-forth.asd")
(asdf:load-system '#:cl-forth/application)
(forth-app:save-application "cl-forth")
This will create an executable named cl-forth
. When you run cl-forth
, it will startup directly into the Forth interpreter
loop.
./cl-forth
CL-Forth Version 1.3
Running under Clozure Common Lisp Version 1.13 (v1.13) DarwinX8664
1 1 + .
2 OK.
: hello-world ." Hello World!" cr ;
OK.
hello-world
Hello World!
OK.
see hello-world
Source code for hello-world:
(DEFUN FORTH-WORDS::HELLO-WORLD (FS &REST PARAMETERS)
(DECLARE (IGNORABLE PARAMETERS))
(WITH-FORTH-SYSTEM (FS)
(TAGBODY (WRITE-STRING "Hello World!")
(TERPRI)
:EXIT)))
OK.
bye
In this session:
1 definition created
240 bytes of object code generated
The application recognizes these command line arguments
‑‑interpret EXPR , ‑i EXPR |
Evaluate EXPR before entering the Forth interpreter loop. EXPR may need to be quoted to avoid interpretation by the shell. This argument may be used multiple times. |
‑‑transcript PATH |
Record a timestamped transcript of this session in the file PATH |
‑‑help , ‑h |
Display the available command line arguments and exit |
‑‑version , ‑V |
Display the version of CL-Forth and exit |
CL-Forth does not implement the optional Block word set.
CL-Forth does not implement the optional Extended-Character word set.
CL-Forth does not implement KEY
which is part of the Core word set.
The following words that are part of the optional Facility and Facility extensions word set are not implemented.
AT-XY |
KEY? |
PAGE |
EKEY |
EKEY>CHAR |
EKEY>FKEY |
EKEY? |
EMIT? |
K-ALT-MASK |
K-CTRL-MASK |
K-DELETE |
K-DOWN |
K-END |
K-F1 |
K-F10 |
K-F11 |
K-F12 |
K-F2 |
K-F3 |
K-F4 |
K-F5 |
K-F6 |
K-F7 |
K-K8 |
K-F9 |
K-HOME |
K-INSERT |
K-LEFT |
K-NEXT |
K-PRIOR |
K-RIGHT |
K-SHIFT-MASK |
K-UP |
CL-Forth includes a foreign function interface (FFI) loosely based on the External Library Interface in SwiftForth. See FFI.md for details.
CL-Forth includes an experimental optimizer which tries to simplify the code generated by CL-Forth by eliminating as much
use of the data stack as possible. There are additional optimizations applied to eliminate unnecessary validity checks when
those checks can be shown to be redundant. (E.g, checking that the character count given to TYPE
is not negative.)
The optimizer is controlled by a boolean flag whose address is stored in the OPTIMIZER
variable. You change the value of
this flag using the words ON
and OFF
.
To turn the optimizer on, execute OPTIMIZER ON
and to turn it off, execute OPTIMIZER OFF
.
By default, the optimizer is off.
Under SBCL, the Forth test suite runs approximately 33% faster and generates approximately 25% less object code.
Some examples of the optimizer's effect on code generated by CL-Forth follows.
CL-Forth Version 1.4.1
Running under Clozure Common Lisp Version 1.13 (v1.13) DarwinX8664
show-code on
OK.
variable x variable y variable z
OK.
optimizer off
OK.
: test1 x @ y @ 256 + + z ! ;
Source code for test1:
(DEFUN FORTH-WORDS::TEST1 (FS PARAMETERS)
(DECLARE (IGNORABLE PARAMETERS))
(WITH-FORTH-SYSTEM (FS)
(TAGBODY (STACK-PUSH DATA-STACK 4503599627370496)
(STACK-PUSH DATA-STACK (CELL-SIGNED (MEMORY-CELL MEMORY (STACK-POP DATA-STACK))))
(STACK-PUSH DATA-STACK 4503599627370504)
(STACK-PUSH DATA-STACK (CELL-SIGNED (MEMORY-CELL MEMORY (STACK-POP DATA-STACK))))
(STACK-PUSH DATA-STACK 256)
(STACK-PUSH DATA-STACK
(CELL-SIGNED (+ (CELL-SIGNED (STACK-POP DATA-STACK))
(CELL-SIGNED (STACK-POP DATA-STACK)))))
(STACK-PUSH DATA-STACK
(CELL-SIGNED (+ (CELL-SIGNED (STACK-POP DATA-STACK))
(CELL-SIGNED (STACK-POP DATA-STACK)))))
(STACK-PUSH DATA-STACK 4503599627370512)
(SETF (MEMORY-CELL MEMORY (STACK-POP DATA-STACK)) (STACK-POP DATA-STACK))
:EXIT)))
OK.
optimizer on
OK.
: test1opt x @ y @ 256 + + z ! ;
Source code for test1opt:
(DEFUN FORTH-WORDS::TEST1OPT (FS PARAMETERS)
(DECLARE (IGNORABLE PARAMETERS))
(WITH-FORTH-SYSTEM (FS)
(TAGBODY (SETF (MEMORY-CELL MEMORY 4503599627370512)
(CELL-SIGNED (+ (CELL-SIGNED (+ 256
(CELL-SIGNED (MEMORY-CELL
MEMORY
4503599627370504))))
(CELL-SIGNED (MEMORY-CELL MEMORY 4503599627370496)))))
:EXIT)))
OK.
optimizer off
OK.
: test2 x 128 type cr ;
Source code for test2:
(DEFUN FORTH-WORDS::TEST2 (FS PARAMETERS)
(DECLARE (IGNORABLE PARAMETERS))
(WITH-FORTH-SYSTEM (FS)
(TAGBODY (STACK-PUSH DATA-STACK 4503599627370496)
(STACK-PUSH DATA-STACK 128)
(LET ((COUNT (STACK-POP DATA-STACK)) (ADDRESS (STACK-POP DATA-STACK)))
(WHEN (MINUSP COUNT)
(FORTH-EXCEPTION
:INVALID-NUMERIC-ARGUMENT
"Count to TYPE can't be negative"))
(MULTIPLE-VALUE-BIND (FORTH-MEMORY OFFSET)
(MEMORY-DECODE-ADDRESS MEMORY ADDRESS COUNT)
(WRITE-STRING (FORTH-STRING-TO-NATIVE FORTH-MEMORY OFFSET COUNT))))
(TERPRI)
:EXIT)))
OK.
optimizer on
OK.
: test2opt x 128 type cr ;
Source code for test2opt:
(DEFUN FORTH-WORDS::TEST2OPT (FS PARAMETERS)
(DECLARE (IGNORABLE PARAMETERS))
(WITH-FORTH-SYSTEM (FS)
(TAGBODY (LET ((COUNT 128) (ADDRESS 4503599627370496))
(DECLARE (IGNORABLE COUNT ADDRESS))
(MULTIPLE-VALUE-BIND (FORTH-MEMORY OFFSET)
(MEMORY-DECODE-ADDRESS MEMORY 4503599627370496 128)
(WRITE-STRING (FORTH-STRING-TO-NATIVE FORTH-MEMORY OFFSET 128))))
(TERPRI)
:EXIT)))
OK.
bye
In this session:
7 definitions created
3920 bytes of object code generated
24 bytes of memory allocated
CL-Forth includes a number of words defined by other implementation that are not part of the Forth 2012 Standard.
These words are specific to CL-Forth.
.SF |
Display the contents of the floating-point stack |
.SR |
Display the contents of the return stack |
ALL-WORDS |
Display all words in all word lists in the search order |
BREAK |
Enter a Lisp break loop |
INLINEABLE |
Mark that the most recent definition's code may be inlined |
NOTINTERPRETED |
Mark that the most recent definition must only appear in definitions |
OPTIMIZER |
Return the address of the flag that controls whether generated code is optimized (EXPERIMENTAL) |
P. |
Display the top cell of the data stack as a pointer (i.e., 16 hex digits) |
RELOAD |
Reload a predefined definition (i.e., created by define-word ) |
REMOVE |
Erase a single word |
SETINLINEABLE |
Enable/disable inlining of an existing word |
SHOW-BACKTRACES |
Return the address of the flag that controls whether exceptions display the return and data stacks |
SHOW-CODE |
Return the address of the flag that controls whether completing a definition shows the generated code |
STATISTICS |
Report some useful statistics about this CL-Forth session |
These words are defined as "Common Usage" in the Forth Programmer's Manual, 3rd Edition.
," |
2+ |
2- |
C+! |
CONTEXT |
CURRENT |
CVARIABLE |
M- |
M/ |
NOT |
NUMBER |
NUMBER? |
VOCABULARY |
These words are defined by SwiftForth.
-? |
EMPTY |
GILD |
OFF |
ON |
OPTIONAL |
SILENT |
VERBOSE |
WARNING |
\\ |
{ |
TO BE SUPPLIED
CL-Forth implements CODE
and ;CODE
to allow the definition of words written in Lisp rather than Forth. The terminator for
the Lisp code block is ;ENDCODE
.
Here is an example of using native code.
\ ( c-addr1 u - c-addr2 u)
\ Converts the string at C-ADDR1 U to uppercase and leaves the result in transient space at C-ADDR2 U.
CODE UPCASE
(let ((count (cell-signed (stack-pop data-stack)))
(address (stack-pop data-stack)))
(unless (plusp count)
(forth-exception :invalid-numeric-argument "Count to UPCASE must be positive"))
(multiple-value-bind (data offset)
(memory-decode-address memory address count)
(let* ((original (forth-string-to-native data offset count))
(upcased (string-upcase original))
(string-space (reserve-string-space memory))
(address (transient-space-base-address memory string-space)))
(ensure-transient-space-holds memory string-space count)
(multiple-value-bind (data offset)
(memory-decode-address memory address count)
(native-into-forth-string upcased data offset)
(seal-transient-space memory string-space)
(stack-push data-stack address)
(stack-push data-stack count)))))
;ENDCODE