Index

ANS
API
Debugger
Download
Licensing
Links
Locals
OOP In Ficl
Parse Steps
Release History
Upgrading To 4.0

A Ficl dictionary is equivalent to the FORTH "dictionary"; it is where words are stored. A single dictionary has a single HERE pointer.

A Ficl system information structure is used to change default values used in initializing a Ficl system.

A Ficl system contains a single dictionary, and one or more virtual machines.

A Ficl stack is equivalent to a FORTH "stack". Ficl has three stacks:

• The data stack, where integer arguments are stored.
• The return stack, where locals and return addresses for subroutine returns are stored.
• The float stack, where floating-point arguments are stored. (This stack is only enabled when FICL_WANT_FLOAT is nonzero.)

A Ficl virtual machine (or vm) represents a single running instance of the Ficl interpreter. All virtual machines in a single Ficl system see the same dictionary.

Though Ficl's API offers a great deal of flexibility, most programs incorporating Ficl simply use it as follows:

1. Create a single ficlSystem using ficlSystemCreate(NULL).
2. Add native functions as necessary with ficlDictionarySetPrimitive().
3. Add constants as necessary with ficlDictionarySetConstant().
4. Create one (or more) virtual machine(s) with ficlSystemCreateVm().
5. Add one or more scripted functions with ficlVmEvaluate().
6. Execute code in a Ficl virtual machine, usually with ficlVmEvaluate(), but perhaps with ficlVmExecuteXT().
7. At shutdown, call ficlSystemDestroy() on the single Ficl system.

The following is a partial listing of functions that interface your system or program to Ficl. For a complete listing, see ficl.h (which is heavily commented). For a simple example, see main.c.

Note that as of Ficl 4, the API is internally consistent. Every external entry point starts with the word ficl, and the word after that also corresponds with the first argument. For instance, a word that operates on a ficlSystem * will be called ficlSystemSomething().

void ficlSystemInformationInitialize(ficlSystemInformation *fsi)

Resets a ficlSystemInformation structure to all zeros. (Actually implemented as a macro.) Use this to initialize a ficlSystemInformation structure before initializing its members and passing it into ficlSystemCreate() (below).

ficlSystem *ficlSystemCreate(ficlSystemInformation *fsi)

Initializes Ficl's shared system data structures, and creates the dictionary allocating the specified number of cells from the heap (by a call to ficlMalloc()). If you pass in a NULL pointer, you will recieve a ficlSystem using the default sizes for the dictionary and stacks.

void ficlSystemDestroy(ficlSystem *system)

Reclaims memory allocated for the Ficl system including all dictionaries and all virtual machines created by ficlSystemCreateVm(). Note that this will not automatically free memory allocated by the FORTH memory allocation words (ALLOCATE and RESIZE).

ficlWord *ficlDictionarySetPrimitive(ficlDictionary *dictionary, char *name, ficlCode code, ficlUnsigned8 flags)

Adds a new word to the dictionary with the given name, code pointer, and flags. To add

The flags parameter is a bitfield. The valid flags are:

• FICL_WORD_IMMEDIATE
• FICL_WORD_COMPILE_ONLY
• FICL_WORD_SMUDGED
• FICL_WORD_OBJECT
• FICL_WORD_INSTRUCTION

For more information on these flags, see ficl.h.

ficlVm *ficlSystemCreateVm(ficlSystem *system)

Creates a new virtual machine in the specified system.

int ficlVmEvaluate(ficlVm *vm, char *text)

the specified C string (zero-terminated) to the given virtual machine for evaluation. Returns various exception codes (VM_XXXX in ficl.h) to indicate the reason for returning. Normal exit condition is VM_OUTOFTEXT, indicating that the VM consumed the string successfully and is back for more. Calls to ficlVmEvaluate() can be nested, and the function itself is re-entrant, but note that a VM is static, so you have to take reasonable precautions (for example, use one VM per thread in a multithreaded system if you want multiple threads to be able to execute commands).

int ficlVmExecuteXT(ficlVm *vm, ficlWord *pFW)

Same as ficlExec, but takes a pointer to a ficlWord instead of a string. Executes the word and returns after it has finished. If executing the word results in an exception, this function will re-throw the same code if it is nested under another ficlExec family function, or return the exception code directly if not. This function is useful if you need to execute the same word repeatedly—you save the dictionary search and outer interpreter overhead.

void ficlFreeVM(ficlVm *vm)

Removes the VM in question from the system VM list and deletes the memory allocated to it. This is an optional call, since ficlTermSystem will do this cleanup for you. This function is handy if you're going to do a lot of dynamic creation of VMs.

ficlVm *ficlNewVM(ficlSystem *system)

Create, initialize, and return a VM from the heap using ficlMalloc. Links the VM into the system VM list for later reclamation by ficlTermSystem.

ficlWord *ficlSystemLookup(ficlSystem *system, char *name)

Returns the address of the specified word in the main dictionary. If no such word is found, it returns NULL. The address is also a valid execution token, and can be used in a call to ficlVmExecuteXT().

ficlDictionary *ficlSystemGetDictionary(ficlSystem *system)
ficlDictionary *ficlVmGetDictionary(ficlVm *system)

Returns a pointer to the main system dictionary.

ficlDictionary *ficlSystemGetEnvironment(ficlSystem *system)

Returns a pointer to the environment dictionary. This dictionary stores information that describes this implementation as required by the Standard.

ficlDictionary *ficlSystemGetLocals(ficlSystem *system)

Returns a pointer to the locals dictionary. This function is defined only if FICL_WANT_LOCALS is non-zero (see ficl.h). The locals dictionary is the symbol table for local variables.

There are a lot of preprocessor constants you can set at compile-time to modify Ficl's runtime behavior. Some are required, such as telling Ficl whether or not the local platform supports double-width integers (FICL_PLATFORM_HAS_2INTEGER); some are optional, such as telling Ficl whether or not to use the extended set of "prefixes" (FICL_WANT_EXTENDED_PREFIXES).

The best way to find out more about these constants is to read ficl.h yourself. The settings that turn on or off Ficl modules all start with FICL_WANT. The settings relating to functionality available on the current platform all start with FICL_PLATFORM.

One more note about constants. Ficl now ships with a standard place for you to tweak the Ficl compile-time preprocessor constants. It's a file called ficllocal.h, and we guarantee that it will always ship empty (or with only comments). We suggest that you put all your local changes there, rather than editing ficl.h or editing the makefile. That should make it much easier to integrate future Ficl releases into your product—all you need do is preserve your tweaked copy of ficllocal.h and replace the rest.