The current kForth release is:
Version: 1.0.14
Last Release Date: 2003-04-19
Systems: Linux, Windows 95/98/NT/2000/XP
(on ix86 and compatible PCs only)
In general new releases for Linux and Windows are made available simultaneously
on our website. Thus the documentation for the kForth dictionary is
valid for all versions, unless specially noted. Some releases may contain
experimental words which are not fully implemented or debugged. However,
such words will not be documented in the user's guide and should not be used
until they appear in the dictionary section
of the user's guide. The Linux version of kforth is also reported to work
under the FreeBSD and BeOS operating systems (for BeOS, see Todd Nathan's
README.beos file
for build instructions).
Non-zero return codes from the virtual machine (VM) indicate the
following conditions:
addr
.
ival
.
QUIT
(not seen by user).
ALLOT
memory for a word.
CREATE
(bad word name).
DO
.
BEGIN
.
ELSE
without matching IF
.
THEN
without matching IF
.
ABORT
will
reset the stack pointers. This procedure should be
used to recover from VM errors 5 and 7, and whenever
there is a suspicion that the stacks have been
corrupted.The kForth compiler/interpreter parses the input stream into a vector of pseudo op-codes or Forth Byte Code. The vector of codes is passed on to the virtual machine which executes the codes. The kForth virtual machine is implemented as a mixture of assembly language, C, and C++ functions. Special features of kForth are described in a two-part article in Forthwrite magazine, issues 116 and 117.These features are:
HERE
address in kForth.
,
(comma operator) in kForth.
C,
operator in kForth.
HERE
does not exist,
the word ALLOT
not only allocates the requested
amount of memory, but also has the non-standard behavior
that it assigns the address of the new memory region
to the parameter field address (PFA) of the last defined word.
In kForth, the use of ALLOT
must always be preceeded
by the use of CREATE
. A variant of ALLOT
,
named ?ALLOT
is also provided. ?ALLOT
has the
same behavior as ALLOT
plus it returns the
start address of the dynamically allocated region on the parameter
stack. ?ALLOT
has the following equivalent definition
under ANS Forth:: ?ALLOT ( u -- a ) HERE SWAP ALLOT ;
?ALLOT
is particularly useful in writing defining words
in the absence of HERE
and the comma operators. For
example, to write your own integer constant defining word:: CONST ( n -- ) CREATE 4 ?ALLOT ! DOES> @ ;
: PTR ( a -- ) CREATE 4 ?ALLOT ! DOES> A@ ;
A@
as follows:: A@ @ ;
0 | not IMMEDIATE | DEFERRED |
1 | IMMEDIATE | DEFERRED |
2 | not IMMEDIATE | NONDEFERRED |
3 | IMMEDIATE | NONDEFERRED |
Precedence | Interpret | Compile |
0 | E0 | E0 |
1 | E2 | E2 |
2 | E1 | E0 |
3 | E1 | E2 |
10 0 do i . loop
do-loop
,
begin-while-repeat
, and if-then
structures
to occur outside of word definitions. kForth can interpret and execute
such structures as long as they are completed on a single line of
input.
NONDEFERRED
are those for which
interpretation of the rest of the input line will depend
on the execution of the word. Thus, the following intrinsic
words in kForth have the nondeferred precedence attribute:\ | .( | BINARY | DECIMAL | HEX |
WORD | ' | CREATE | FORGET | COLD |
ALLOT | ?ALLOT | CONSTANT | FCONSTANT | VARIABLE |
FVARIABLE | CHAR | >FILE | CONSOLE |
NONDEFERRED
keyword to set explicitly the
interpretation precedence of a word. This is due to the automatic
inheritance of the nondeferred attribute: if a word definition includes a
nondeferred word, then the new word is automatically nondeferred
also. Thus, for example, any word which has a definition including
WORD
is also a nondeferred word. Another example
is a defining word, i.e. one which uses CREATE
.
Since CREATE
is nondeferred the new defining word
is also nondeferred.NONDEFERRED
keyword
should be explicitly used is in the definition of a word which
changes the number base. For example,
DECIMAL
: BASE3 3 BASE ! ; NONDEFERRED
BASE3 21
BASE3
was not declared to be a nondeferred word,
then 21
in the above line would be interpreted as
decimal 21 rather than as decimal 7 (which is 21 in base 3).-D
. Compiled op-codes and
other debugging information are displayed in this mode. It is
useful primarily for programmers interested in extending and
debugging their own versions of kForth.
Versions of standard benchmark programs for measuring
kForth execution speed may be found under
the directory: examples/benchmarks/
.
John Hayes' suite of tests for the core words of an ANS Forth
system is available for kForth:
tester.4th and
core.4th. Tests involving unsupported words such as
HERE
and ,
and C,
have
been commented out, as well as tests involving the
BEGIN ... WHILE ... WHILE ... REPEAT ... THEN
structure,
and some weird variants of CREATE
and DOES>
usage.
Source code for kForth consists of the following C++, C, and assembly
language files:
kforth.cpp
ForthCompiler.cpp
ForthVM.cpp
vmc.c
vm.s
fbc.h
ForthCompiler.h
ForthVM.h
The source code is made available to users under the
GNU General
Public License. The Linux version is provided as
source code only and must be built locally on the user's machine
(see installation).
Under Linux, the standard GNU assembler, GNU C and C++ compilers,
and the C++ Standard Template Library (STL)
are required to build the executable. The Windows 95/98/NT console
application was built using the free
Cygwin port of the GNU
development tools.
The file kforth.cpp
serves as a skeleton C++
program to illustrate how the kForth compiler and virtual
machine may be embedded in a standalone program. XYPLOT for
Linux is a more complex GUI program which embeds kForth
to allow user extensibility. The file xyplot.cpp
shows how to set up hooks for calling C++ functions in the host
program from the embedded kForth interpreter and vice-versa.
The rest of this section is being written.