Up
Previous Next
Mail the author

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.
WordStack effectFunction
$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

WordStack effectFunction
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

WordStack effectFunction
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

WordStack effectFunction
CAPS-COMPARE( caddr1 u1 caddr2 u2 -- nPerform 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.
WordStack effectFunction
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

WordStack effectFunction
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 COMMENTing 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.
WordStack effectFunction
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.

WordStack effectFunction
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

WordBehaviour when TRUEBehaviour when FALSE
CAPSString comparison is case insensitive.String comparison is case sensitive.
audible-signalALERT rings a bell.ALERT flashes the screen.
redef-warningA warning is printed, when a word in the same wordlist is redefined.The warning is not displayed.
checkpointsCheckpoints are compiled or displayed.Checkpoints are ignored.

Up
Previous

FLK

Next
Mail the author