What is ficl?

Ficl is a complete programming language interpreter designed to be embedded into other systems (including firmware based ones) as a command, macro, and development prototype language. Unlike other scripting interpreters, Ficl:

typically takes under 2 hours to port to a new system -- much less if the target operating system is one of several already supported (Win32, Linux, FreeBSD, RiscOS, and more)
has a small memory footprint: a fully featured Win32 console version takes less than 100K of memory, and a minimal version is less than half that
is relatively quick thanks to its threaded code virtual machine design and just in time compiling
is a complete and powerful programming language
is interactive
has object oriented programming features that can be used to wrap data structures or classes of the host system without altering them - even if the host is mainly written in a non-OO language

Ficl syntax is based on ANS Forth and the code is Standard C. See below for examples of software and products that include ficl. Ficl stands for "Forth inspired command language".

Ficl vs. other Forth interpreters

Where Forths usually view themselves as the center of the system and expect the rest of the system to be coded in Forth, Ficl acts as a component of the system. It is easy to export code written in C or ASM to Ficl in the style of TCL, or to invoke Ficl code from a compiled module. This allows you to do incremental development in a way that combines the best features of threaded languages (rapid development, quick code/test/debug cycle, reasonably fast) with the best features of C (everyone knows it, easier to support large blocks of code, efficient, type checking). In addition, Ficl provides a simple and powerful object model that can act as an object oriented adapter for code written in C (or asm, Forth, C++...).

Ficl Design goals

Target 32 bit processors (version 2.03 targets 64 bit processors too)
Scripting, prototyping, and extension language for systems written also in C
Supportable - code is as transparent as I can make it
Interface to functions written in C
Conform to the Forth DPANS 94
Minimize porting effort - require an ANSI C runtime environment and minimal glue code
Provide object oriented extensions

Links

Download ficl (latest release)

Getting Started: Forth Tutorials on the Web

Julian Noble's Forth Primer (start here if you're new to Forth)
An excellent Forth Primer by Hans Bezemer
An Introduction to Forth using Stack Flow
Phil Burk's Forth Tutorial
Anton Ertl's description of Threaded Code

More information on Ficl and Forth

Some software that uses ficl

FreeBSD boot loader (Daniel Sobral, Jordan Hubbard)
SwitchCore Gigabit Ethernet switches (Örjan Gustavsson )
Palm Pilot Debuffer (Eric Sessoms) Also see ficlx, a C++ interface to ficl, on the same site
Osmond PC Board Layout tool
NetCom Systems ML7710
ParView GPS system
PowerPlant Software Development Environment for Linux
Vyyo V3000 Broadband Wireless Hub
Your Product Name Here!!!

LICENSE and DISCLAIMER

I am interested in hearing from anyone who uses ficl. If you have a problem, a success story, a defect, an enhancement request, or if you would like to contribute to the ficl release, please send me email.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

Ficl features

Simple to integrate into existing systems: the sample implementation requires three Ficl function calls (see the example program in testmain.c).
Written in ANSI C for portability.
Standard: Implements the ANS Forth CORE word set, part of the CORE EXT word set, SEARCH and SEARCH EXT, TOOLS and part of TOOLS EXT, LOCAL and LOCAL EXT, EXCEPTION, MEMORY, and various extras.
Extensible: you can export code written in Forth, C, or asm in a straightforward way. Ficl provides open facilities for extending the language in an application specific way. You can even add new control structures (not surprising if you're familiar with Forth)
Ficl and C/C++ can interact in two ways: Ficl can wrap C code, and C functions can invoke ficl code.
Ficl code is thread safe and re-entrant: All Ficl Virtual Machines share one system dictionary (version 3.0 will permit multiple dictionaries); each Ficl Virtual Machine has an otherwise complete state, and each can be bound to a separate I/O channel (or none at all). An optional function called ficlLockDictionary() can control exclusive dictionary access. This function is stubbed out by default (See FICL_MULTITHREAD in sysdep.h). As long as there is only one "session" that can compile words into the dictionary, you do not need exclusive dictionary access for multithreading. Note: while the code is re-entrant, there are still restrictions on how you can use it safely in a multithreaded system. Specifically, the VM itself maintains state, so you generally need a VM per thread in a multithreaded system. If interrupt service routines make calls into Ficl code that alters VM state, then these generally need their own VM as well. Alternatively, you could provide a mutual exclusion mechanism to serialize access to a VM from multiple threads.
ROMable: Ficl is designed to work in RAM based and ROM code / RAM data environments. It does require somewhat more memory than a pure ROM implementation because it builds its system dictionary in RAM at startup time.
Written in ANSI C to be as simple as I can make it to understand, support, debug, and port. Compiles without complaint at /Az /W4 (require ANSI C, max. warnings) under Microsoft VC++. Ports to several other toolchains and operating systems (notably FreeBSD and Linux flavors) exist.
Does full 32 bit math (but you need to implement two mixed precision math primitives (see sysdep.c))

Porting ficl

To install ficl on your target system, you need an ANSI C compiler and its runtime library. Inspect the system dependent macros and functions in sysdep.h and sysdep.c and edit them to suit your system. For example, INT16 is a short on some compilers and an int on others. Check the default CELL alignment controlled by FICL_ALIGN. If necessary, add new definitions of ficlMalloc, ficlFree, ficlRealloc, and ficlTextOut to work with your operating system. Finally, use testmain.c as a guide to installing the ficl system and one or more virtual machines into your code. You do not need to include testmain.c in your build.

Note: ficlLockDictionary can be left unimplemented in most multithreaded implementations - it's only necessary if you expect to have more than one thread modifying the dictionary at the same time. If you do decide to implement it, make sure calls to ficlLockDictionary can nest properly (see the comments in sysdep.h). You need to keep count of nested locks and unlocks and do the right thing.

Feel free to stub out the double precision math functions (which are presently implemented as inline assembly because it's so easy on many 32 bit processors) with kludge code that only goes to 32 bit precision. In most applications, you won't notice the difference. If you're doing a lot of number crunching, consider implementing them correctly.

Build controls

The file sysdep.h contains default values for build controls. Most of these are written such that if you define them on the compiler command line, the defaults are overridden. I suggest you take the defaults on everything below the "build controls" section until you're confident of your port. Beware of declaring too small a dictionary, for example. You need about 3200 cells for a full system, about 2000 if you strip out most of the "soft" words.

Soft Words

Many words from all the supported wordsets are written in Forth, and stored as a big string that Ficl compiles when it starts. The sources for all of these words are in directory ficl/softwords. There is a .bat file (softcore.bat) and a PERL 5 script (softcore.pl) that convert Forth files into the file softcore.c, so softcore.c is really dependent on the Forth sources. This is not reflected in the Visual C++ project database. For the time being, it's a manual step. You can edit softcore.bat to change the list of files that contribute to softcore.c.

To-Do List (target system dependent words)

Unimplemented system dependent CORE word: KEY (implement this yourself if you need it)
Kludged CORE word: ACCEPT (implement this better if you need to)

Application Programming Interface

The following is a partial listing of functions that interface your system or program to ficl. For a complete listing, see ficl.h (heavily commented). For examples, see testmain.c and the ficlwin sources (below). See the comments in ficl.c and ficl.h for additional information, and the example in file testmain.c.

FICL_SYSTEM *ficlInitSystem(int nDictCells): 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)
void ficlTermSystem(FICL_SYSTEM *pSys): Reclaims memory allocated for the ficl system including all dictionaries and all virtual machines created by vmCreate. Any uses of the memory allocation words (allocate and resize) are your problem.
int ficlBuild(FICL_SYSTEM *pSys, char *name, FICL_CODE code, char flags): Create a primitive word in ficl's main dictionary with the given name, code pointer, and properties (immediate, compile only, etc) as described by the flags (see ficl.h for flag descriptions of the form FW_XXXX)
int ficlExec(FICL_VM *pVM, char *text): Feed the specified C string ('\0' 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. ficlExec calls 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 ficlExecC(FICL_VM *pVM, char *text, int nChars): Same as ficlExec, but takes a count indicating the length of the supplied string. Setting nChars to -1 is equivalent to ficlExec (expects '\0' termination).
int ficlExecXT(FICL_VM *pVM, FICL_WORD *pFW): Same as ficlExec, but takes a pointer to a FICL_WORD 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(FICL_VM *pVM): 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.
FICL_VM *ficlNewVM(FICL_SYSTEM *pSys): Create, initialize, and return a VM from the heap using ficlMalloc. Links the VM into the system VM list for later reclamation by ficlTermSystem.
FICL_WORD *ficlLookup(FICL_SYSTEM *pSys, char *name): Returns the address (also known as an XT in this case) of the specified word in the main dictionary. If not found, returns NULL. The address can be used in a call to ficlExecXT.
FICL_DICT *ficlGetDict(FICL_SYSTEM *pSys): Returns a pointer to the main system dictionary, or NULL if the system is uninitialized.
FICL_DICT *ficlGetEnv(FICL_SYSTEM *pSys): Returns a pointer to the environment dictionary. This dictionary stores information that describes this implementation as required by the Standard.
void ficlSetEnv(FICL_SYSTEM *pSys, char *name, UNS32 value): Enters a new constant into the environment dictionary, with the specified name and value.
void ficlSetEnvD(FICL_SYSTEM *pSys, char *name, UNS32 hi, UNS32 lo): Enters a new double-cell constant into the environment dictionary with the specified name and value.
FICL_DICT *ficlGetLoc(FICL_SYSTEM *pSys): Returns a pointer to the locals dictionary. This function is defined only if FICL_WANT_LOCALS is #defined as non-zero (see sysdep.h). The locals dictionary is the symbol table for local variables.
void ficlCompileCore(FICL_SYSTEM *pSys): Defined in words.c, this function builds ficl's primitives.
void ficlCompileSoftCore(FICL_SYSTEM *pSys): Defined in softcore.c, this function builds ANS required words and ficl extras by evaluating a text string (think of it as a memory mapped file ;-) ). The string itself is built from files in the softwords directory by PERL script softcore.pl.

Ficl Source Files
ficl.h	Declares most public functions and all data structures. Includes sysdep.h and math.h
sysdep.h	Declares system dependent functions and contains build control macros. Edit this file to port to another system.
math.h	Declares functions for 64 bit math
dict.c	Dictionary
ficl.c	System initialization, termination, and ficlExec
float.c	Adds precompiled definitions from the optional FLOAT word set. Most of the file is conditioned on FICL_WANT_FLOAT
math64.c	Implementation of 64 bit math words (except the two unsigned primitives declared in sysdep.h and implemented in sysdep.c)
prefix.c	The optional prefix parse step (conditioned on FICL_EXTENDED_PREFIX). This parse step handles numeric constructs like 0xa100, for example. See the release notes for more on parse steps.
search.c	Contains C implementations of several of the SEARCH and SEARCH EXT words
softcore.c	Contains all of the "soft" words - those written in Forth and compiled by Ficl at startup time. Sources for these words are in the softwords directory. The files softwords/softcore.bat and softwords/softcore.pl generate softcore.c from the .fr sources.
softwords/	Directory contains sources and translation scripts for the words defined in softcore.c. Softcore.c depends on most of the files in this directory. See softcore.bat for the actual list of files that contribute to softcore.c. This is where you'll find source code for the object oriented extensions. PERL script softcore.pl converts the .fr files into softcore.c.
stack.c	Stack methods
sysdep.c	Implementation of system dependent functions declared in sysdep.h
testmain.c	The main() function for unix/linux/win32 console applications - use this as an example to integrate ficl into your system. Also contains some definitions for testing - also useful in unix/linux/win32 land.
tools.c	Contains C implementations of TOOLS and TOOLS EXT words, the debugger, and debugger support words.
vm.c	Virtual Machine methods
win32.c & unix.c	Platform extensions words loaded in ficl.c by ficlCompilePlatform() - conditioned on FICL_WANT_PLATFORM
words.c	Exports ficlCompileCore(), the run-time dictionary builder, and contains most precompiled CORE and CORE-EXT words.

Ficl Documentation