FLK non-standard words
This section describes useful words provided by the system. Since there a
lots of useful words in the system only those are explained which are
important for every day's work.
Cell counted string handling
To overcome the limitations of the byte counted strings proposed by the
standard cell counted strings are available. Both static variables and
dynamicly allocated ones can be used.
Word | Stack effect | Function |
$COUNT | (addr -- addr+cell count) | COUNT for cell counted
strings |
$cat | (caddr u addr -- ) | Append the cell counted string at
addr by the given string. |
$copy | (caddr u addr -- ) | Replace the cell counted string at
addr by the given string. |
$VARIABLE | (n -<name>-) | Create a cell counted
string variable reserving n characters. |
Vocabularies
Word | Stack effect | Function |
VOCS | ( -- ) | Show the names of all known vocabularies. |
.VOC | ( wid --) | Display the name of the given wordlist. |
SEARCH-WORDLISTS | ( c-addr u -- 0 / xt 1 / xt -1 ) | Perform
the function of FIND but with a faster and simpler interface. |
VOCABULARY | ( -<name>- ) | Create a named wordlist.
The execution of name replaces the first word list in the search order. |
Transport functions
Word | Stack effect | Function |
TURN | ( t3 t2 t1 t0 -- t2 t1 t0 t3 ) | ROT with 4 items |
-TURN | ( t3 t2 t1 t0 -- t0 t3 t2 t1 ) | -ROT with 4 items |
TWIST | ( t4 t3 t2 t1 t0 -- t3 t2 t1 t0 t4 ) | ROT with 5
items |
-TWIST | ( t4 t3 t2 t1 t0 -- t0 t4 t3 t2 t1 ) | -ROT with 5
items |
ROTARE | ( t5 t4 t3 t2 t1 t0 -- t4 t3 t2 t1 t0 t5 ) | ROT
with 6 items |
-ROTARE | ( t5 t4 t3 t2 t1 t0 -- t0 t5 t4 t3 t2 t1 ) | -ROT
with 6 items |
PLUCK | ( t2 t1 t0 -- t2 t1 t0 t2 ) | OVER with 3 items |
FLOCK | ( t3 t2 t1 t0 -- t3 t2 t1 t0 t3 ) | OVER with 4 items |
exchange | ( x1 addr -- x2 ) | Exchange the value at addr
with x1 returning the old content of addr |
nDROP | ( n*x n-- ) | Drop the top n+1 items. |
TO++ | ( -<name>- ) | Increase a VALUE by one. |
TO-- | ( -<name>- ) | Derease a VALUE by one. |
+TO | ( x -<name>- ) | Add a number to a VALUE. |
String tools
Word | Stack effect | Function |
CAPS-COMPARE | ( caddr1 u1 caddr2 u2 -- n | Perform the
function of the word COMPARE but case insensitive. |
ARGC | ( -- u ) | Return the number of commandline arguments. |
ARGV | ( -- addr ) | Return the address of the array containg
the addresses of zero-terminated string containing the commandline arguments.
There are exactly ARGC items stored in consequtive cells beginning at the
returned address. |
CHAR-H-LINE+ | ( x y w -- ) | Draw a horizontal line of w
characters starting at (x,y). |
CHAR-V-LINE+ | ( x y h -- ) | Draw a vertical line of h
characters starting at (x,y). |
CHAR-FRAME | ( x y width height -- ) | Draw a frame of the
given width and height with the left upper corner at (x,y). |
strlen | ( caddr -- caddr u ) | Count the characters in a
zero terminated string. |
System storage
FLK is able to save its current state to disk. Sadly you cannot save to a
currently running file. The code area is the room where all code is compiled
to and where the headers are placed. The data area holds the data space
accessed by CREATE etc.
Word | Stack effect | Function |
SAVE-SYSTEM | ( caddr u -- ) | Saves the system to the file
with the given name. You need to have write permission. If the file already
exists and contains an image it is overwritten. Otherwise the image is
appended or the file is created. |
TURN-KEY | ( caddr u -<name>- ) | Make name the first word to
be executed and perform the function of SAVE-SYSTEM. |
copy-executable | ( name #name -- ) | Copy the running
executable to a different name in preparation for SAVE-SYSTEM or TURN-KEY. |
set-codesize | ( n -- ) | Set a new size for the code area. |
set-datasize | ( n -- ) | Set a new size for the data area. |
new-system | ( addr len -- ) | Copy the current executable to
the given name and save the system to it. The name must not be the name of the
current executable. |
Other useful words
Word | Stack effect | Function |
INCLUDE | ( -- ) | Input a filename and perform INCLUDED. |
TODO | ( -- ) | Throw the "to do" exception. If you mark
unfinished code with this word execution of the unfinished parts raises an
exception and does not crash. |
INLINE | ( -- ) | Inline code into the currently compiled
defintion. This word can bee seen as a throw-away primitive. |
DEFER | ( -<name>- ) | Create name. If you assign an xt to
name using TO the execution of name calls the stored xt. |
r, | ( x -- ) | Perform the function of , but relocate the
stored value. |
TURN-ON | ( -<name>- ) | Perform the equivalent to TRUE
TO name . |
TURN-OFF | ( -<name>- ) | Perform the equivalent to FALSE
TO name . |
ALERT | ( -- ) | Alert the user by a bell if
audible-signal is TRUE or by flashing the screen. |
.NOW | ( -- ) | Tell the current time and date. |
>UPPER | ( char -- char2 ) | Convert a character to upper
case. |
SYSTEM | ( addr len -- retval ) | Shell out and perform the
command in the string. |
RCONSTANT | ( x -<name>- ) | A relocated CONSTANT. |
RVALUE | ( x -<name>- ) | A relocated VALUE. |
COMMENT | -- | Mark the last defined word as a comment,
i.e. execute it instead of caching it. If you POSTPONE a
COMMENT ing word the current definition becomes a comment itself. |
PARSING | -- | Mark the last defined word to be parsing.
You have to give this flag if you mess around in the parsing area and do not
use PARSE directly or indirectly. |
.faulty-word | ( fault-at base -- ) | Debugging utility.
If you encounter a segmentation fault you can't explain just run FLK in
gdb and write down the address of the fault and the base address of
the image. Then restart the same image again and execute
.faulty-word . It tells you which word is closest to the given
address. |
Macro words
By default FLK compiles every word as separate subroutine ended by return.
Sometimes this is not desirable e.g. if words are factored for readability and
the factors are not meant to be used interactively. Using the macro recorder
invoced by macro
you can define those words to be compiled inline.
macro
reads the input until an empty line or the end of the file
is found and connects these lines to a single string separated by new-lines.
When the created word is executed (it is IMMEDIATE
) the recorded
string is passed to EVALUATE
. All words are allowed in the macro
but be aware that long definitions can use a lot of memory in the
dictionary.
The flag setting words are provided here to.
Word | Stack effect | Function |
macro | ( -<name>- ) | Create an IMMEDIATE word
name and record all further up to the next empty one into the
definition. When name is executed the recorded string is processed
by EVALUATE . |
Shared library words
To extend the abilities of FLK even further you can bind dynamically loaded
libaries or shared objects using the following words. The used syntax is
similiar but not equal to bigforth.
When a library is loaded and the system is saved the library is loaded again
at the next start of the new system.
If either a symbol name or library file can not be found an error message from
the linker is produced and ABORT
is called.
Word | Stack effect | Function |
lib | ( addr len -<name>- ) | Create name ,
load the library who's filename is given in the string and make the library
the current library (The one to be searched for symbols.). Execution of
name makes the library the current library too.. |
fct: | ( returns -<name parameters>- ) | Declare a
word name and bind the function name found in the
current library to it. The accepted return types are int ,
double and void . The parameters are declared in
reverse and passed in the same order as a C-prototype. Accepted
parameter types are int , double , float
and void . All integer and pointer parameters are passed as
int . As an abbreviation ints is provided. 2
ints is the same as int int but generates more efficient
code. |
var: | ( -<name>- ) | Bind the address of the
variable name found in the the current library to
name . name behaves like declared by
VARIABLE . |
libs | ( -- ) | Display the names of the loaded libraries. |
Linux system calls
This feature is somehow experimental at the moment. You can use the Linux
system calls (man page section 2 functions) like colon definitions. It is not
advisable to use them interactively but it is possible and if you're
careful...
The actual words are named sys_
name where name is
the name of the call as found in /usr/include/asm/unistd.h
.
I present no comment on the individual words. Look into the man page if you're
curious. The calling order is left-to-right i.e. write(a,b,c);
in
C becomes a b c sys_write
in FORTH.
The return value from them is put onto the stack after removal of the
parameters. If this value is negative the call failed and the number is the
negative content of errno
in C.
The script mksc
to generate linuxsc.fs
is included
but not connected to the Makefile. If anyone finds bugs in the script
please send a mail to me.
Some system calls are listed with a negative number of parameters. Those calls
are either obsolete or require more than 5 parameters. Their number of
parameters (the first case) are not known or the calling sequence for that
many parameters is not documented anywhere. A Linux hacker who knows this
could be helpful.
Flags
Word | Behaviour when TRUE | Behaviour when FALSE |
CAPS | String comparison is case insensitive. | String
comparison is case sensitive. |
audible-signal | ALERT rings a bell. | ALERT flashes the
screen. |
redef-warning | A warning is printed, when a word in the same
wordlist is redefined. | The warning is not displayed. |
checkpoints | Checkpoints are compiled or
displayed. | Checkpoints are ignored. |