ref: 0a10ee45dab0f0730216621719bb61a99e6ecae8
dir: /doc/ficl.html/
<!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en">
<HTML>
<HEAD>
<META name="Author" content="john sadler">
<META name="Description" content="Ficl - embedded scripting with object oriented programming">
<META name="Keywords" content="scripting prototyping tcl OOP Forth interpreter C">
<LINK media="screen" href="ficlstyle.css" type="text/css" rel="stylesheet">
<STYLE type="text/css">
</STYLE>
<LINK rel="SHORTCUT ICON" href="ficl.ico">
<TITLE>
Ficl - Embedded Scripting
</TITLE>
</HEAD>
<BODY>
<H1>
<B>Ficl Documentation</B>
</H1>
<SCRIPT language="javascript" src="ficlheader.js" type="text/javascript">
</SCRIPT>
<DIV style="width:675px">
<BR>
<H1>
<A name="whatis"></A>What is ficl?
</H1>
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:
<UL>
<LI>
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)
</LI>
<LI>
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
</LI>
<LI>
is relatively quick thanks to its threaded code virtual machine design and just in time compiling
</LI>
<LI>
is a complete and powerful programming language
</LI>
<LI>
is interactive
</LI>
<LI>
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
</LI>
</UL>
<P>
Ficl syntax is based on ANS Forth and the code is Standard C. See below for examples of <A href="#includesficl">software and products that include ficl</A>. Ficl stands for "Forth inspired
command language".
</P>
<H3>
Ficl vs. other Forth interpreters
</H3>
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 <I>adapter</I> for code written in C (or asm, Forth, C++...).
<H3>
Ficl Design goals
</H3>
<UL>
<LI>
Target 32 bit processors (<I>version 2.03 targets 64 bit processors too</I>)
</LI>
<LI>
Scripting, prototyping, and extension language for systems written also in C
</LI>
<LI>
Supportable - code is as transparent as I can make it
</LI>
<LI>
Interface to functions written in C
</LI>
<LI>
Conform to the Forth DPANS 94
</LI>
<LI>
Minimize porting effort - require an ANSI C runtime environment and minimal glue code
</LI>
<LI>
Provide object oriented extensions
</LI>
</UL>
<HR>
<h1><A name="links"></A>Links</H1>
<UL>
<LI>
<B><A name="download" href="http://sourceforge.net/project/showfiles.php?group_id=24441">Download ficl (latest release)</A></B>
</LI>
</UL>
<H2>
<A name="tutorials"></A>Getting Started: Forth Tutorials on the Web
</H2>
<ul>
<LI>
<A href="primer.html">Julian Noble's Forth Primer</A> (start here if you're new to Forth)
</LI>
<LI>
<A href="http://ficl.sourceforge.net/pdf/Forth_Primer.pdf">An excellent Forth Primer by Hans Bezemer</A>
</LI>
<LI>
<A href="http://www.taygeta.com/forth_intro/stackflo.html">An Introduction to Forth using Stack Flow</A>
</LI>
<LI>
<A href="http://www.softsynth.com/pforth/pf_tut.htm">Phil Burk's Forth Tutorial</A>
</LI>
<LI>
<A href="http://www.complang.tuwien.ac.at/forth/threaded-code.html">Anton Ertl's description of Threaded Code</A>
</LI>
</UL>
<H2>
More information on Ficl and Forth
</H2>
<UL>
<LI>
<A href="http://ficl.sourceforge.net">Web home of Ficl</A>
</LI>
<LI>
<A href="ficlddj.pdf">Manuscript of Ficl article for January 1999 Dr. Dobb's Journal</A>
</LI>
<LI>
<A href="jwsforml.pdf">1998 FORML Conference paper - OO Programming in Ficl</A>
</LI>
<LI>
<A href="http://ficl.sourceforge.net/dpans/dpans.htm">Draft Proposed American National Standard for Forth</A> (quite readable, actually)
</LI>
<LI>
<A href="http://www.taygeta.com/forthlit.html">Forth literature index on Taygeta</A>
</LI>
<LI>
<A href="http://www.forth.org">Forth Interest Group</A>
</LI>
</ul>
<H2>
<A name="includesficl"></A>Some software that uses ficl
</H2>
<UL>
<LI>
<A href="http://www.freebsd.org/">FreeBSD</A> boot loader (Daniel Sobral, Jordan Hubbard)
</LI>
<LI>
<A href="http://www.chipcenter.com/networking/images/prod/prod158a.pdf">SwitchCore</A> Gigabit Ethernet switches (Örjan Gustavsson )
</LI>
<LI>
<A href="http://debuffer.sourceforge.net/">Palm Pilot Debuffer</A> (Eric Sessoms) Also see ficlx, a C++ interface to ficl, on the same site
</LI>
<LI>
<A href="http://www.swcp.com/~jchavez/osmond.html">Osmond PC Board Layout tool</A>
</LI>
<LI>
<A href="http://www.netcomsystems.com">NetCom Systems</A> ML7710
</LI>
<LI>
<A href="http://www.parview.com/ds/homepage.html">ParView</A> GPS system
</LI>
<LI>
<A href="http://www.thekompany.com/products/powerplant/software/Languages/Embedded.php3">PowerPlant Software</A> Development Environment for Linux
</LI>
<LI>
<A href="http://www.vyyo.com/products/architecture_v3000.html">Vyyo V3000 Broadband Wireless Hub</A>
</LI>
<LI>
<A href="mailto:john_sadler@alum.mit.edu"><I>Your Product Name Here!!!</I></A>
</LI>
</UL>
<HR>
<H2>
<A name="lawyerbait"></A>LICENSE and DISCLAIMER
</H2>
<P>
Copyright (c) 1997-2001 John Sadler (john_sadler@alum.mit.edu) All rights reserved.
</P>
<P>
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
<A href="mailto:john_sadler@alum.mit.edu">send me email</A>.
</P>
<PRE>
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.
</PRE>
<H2>
<A name="features"></A>Ficl features
</H2>
<UL>
<LI>
Simple to integrate into existing systems: the sample implementation requires three Ficl function calls (see the example program in testmain.c).
</LI>
<LI>
Written in ANSI C for portability.
</LI>
<LI>
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.
</LI>
<LI>
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)
</LI>
<LI>
Ficl and C/C++ can interact in two ways: Ficl can wrap C code, and C functions can invoke ficl code.
</LI>
<LI>
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. <B>Note</B>: 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.
</LI>
<LI>
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.
</LI>
<LI>
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.
</LI>
<LI>
Does full 32 bit math (but you need to implement two mixed precision math primitives (see sysdep.c))
</LI>
</UL>
<HR>
<H2>
<A name="porting"></A>Porting ficl
</H2>
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 <TT>sysdep.h</TT> and <TT>sysdep.c</TT> and edit
them to suit your system. For example, <TT>INT16</TT> is a <TT>short</TT> on some compilers and an <TT>int</TT> on others. Check the default <TT>CELL</TT> alignment controlled by <TT>
FICL_ALIGN</TT>. If necessary, add new definitions of <TT>ficlMalloc, ficlFree, ficlRealloc</TT>, and <TT>ficlTextOut</TT> to work with your operating system. Finally, use <TT>testmain.c</TT>
as a guide to installing the ficl system and one or more virtual machines into your code. You do not need to include <TT>testmain.c</TT> in your build.
<P>
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.
</P>
<P>
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.
</P>
<H3>
Build controls
</H3>
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.
<H3>
Soft Words
</H3>
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.
<H3>
To-Do List (target system dependent words)
</H3>
<UL>
<LI>
Unimplemented system dependent <TT>CORE</TT> word: <TT>KEY</TT> (implement this yourself if you need it)
</LI>
<LI>
Kludged <TT>CORE</TT> word: <TT>ACCEPT</TT> (implement this better if you need to)
</LI>
</UL>
<BR>
<BR>
<H2>
<A name="api"></A>Application Programming Interface
</H2>
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 (<A href="#download">below</A>). <I>See the comments in ficl.c and ficl.h for additional information, and the example in file testmain.c.</I>
<DL>
<DT>
<B>FICL_SYSTEM *ficlInitSystem(int nDictCells)</B>
</DT>
<DD>
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)
</DD>
<DT>
<B>void ficlTermSystem(FICL_SYSTEM *pSys)</B>
</DT>
<DD>
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.
</DD>
<DT>
<B>int ficlBuild(FICL_SYSTEM *pSys, char *name, FICL_CODE code, char flags)</B>
</DT>
<DD>
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)
</DD>
<DT>
<B>int ficlExec(FICL_VM *pVM, char *text)</B>
</DT>
<DD>
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).
</DD>
<DT>
<B>int ficlExecC(FICL_VM *pVM, char *text, int nChars)</B>
</DT>
<DD>
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).
</DD>
<DT>
<B>int ficlExecXT(FICL_VM *pVM, FICL_WORD *pFW)</B>
</DT>
<DD>
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.
</DD>
<DT>
<B>void ficlFreeVM(FICL_VM *pVM)</B>
</DT>
<DD>
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.
</DD>
<DT>
<B>FICL_VM *ficlNewVM(FICL_SYSTEM *pSys)</B>
</DT>
<DD>
Create, initialize, and return a VM from the heap using ficlMalloc. Links the VM into the system VM list for later reclamation by ficlTermSystem.
</DD>
<DT>
<B>FICL_WORD *ficlLookup(FICL_SYSTEM *pSys, char *name)</B>
</DT>
<DD>
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.
</DD>
<DT>
<B>FICL_DICT *ficlGetDict(FICL_SYSTEM *pSys)</B>
</DT>
<DD>
Returns a pointer to the main system dictionary, or NULL if the system is uninitialized.
</DD>
<DT>
<B>FICL_DICT *ficlGetEnv(FICL_SYSTEM *pSys)</B>
</DT>
<DD>
Returns a pointer to the environment dictionary. This dictionary stores information that describes this implementation as required by the Standard.
</DD>
<DT>
<B>void ficlSetEnv(FICL_SYSTEM *pSys, char *name, UNS32 value)</B>
</DT>
<DD>
Enters a new constant into the environment dictionary, with the specified name and value.
</DD>
<DT>
<B>void ficlSetEnvD(FICL_SYSTEM *pSys, char *name, UNS32 hi, UNS32 lo)</B>
</DT>
<DD>
Enters a new double-cell constant into the environment dictionary with the specified name and value.
</DD>
<DT>
<B>FICL_DICT *ficlGetLoc(FICL_SYSTEM *pSys)</B>
</DT>
<DD>
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 <A href=
"ficl_loc.html">local variables</A>.
</DD>
<DT>
<B>void ficlCompileCore(FICL_SYSTEM *pSys)</B>
</DT>
<DD>
Defined in words.c, this function builds ficl's primitives.
</DD>
<DT>
<B>void ficlCompileSoftCore(FICL_SYSTEM *pSys)</B>
</DT>
<DD>
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.
</DD>
</DL>
<HR>
<TABLE border="0" cellspacing="5" cols="2">
<TR>
<TD colspan="2">
<H2>
<A name="manifest"></A>Ficl Source Files
</H2>
</TD>
</TR>
<TR>
<TD>
<B>ficl.h</B>
</TD>
<TD>
Declares most public functions and all data structures. Includes sysdep.h and math.h
</TD>
</TR>
<TR>
<TD>
<B>sysdep.h</B>
</TD>
<TD>
Declares system dependent functions and contains build control macros. Edit this file to port to another system.
</TD>
</TR>
<TR>
<TD>
<B>math.h</B>
</TD>
<TD>
Declares functions for 64 bit math
</TD>
</TR>
<TR>
<TD>
<B>dict.c</B>
</TD>
<TD>
Dictionary
</TD>
</TR>
<TR>
<TD>
<B>ficl.c</B>
</TD>
<TD>
System initialization, termination, and ficlExec
</TD>
</TR>
<TR>
<TD>
<B>float.c</B>
</TD>
<TD>
Adds precompiled definitions from the optional FLOAT word set. Most of the file is conditioned on FICL_WANT_FLOAT
</TD>
</TR>
<TR>
<TD>
<B>math64.c</B>
</TD>
<TD>
Implementation of 64 bit math words (except the two unsigned primitives declared in sysdep.h and implemented in sysdep.c)
</TD>
</TR>
<TR>
<TD>
<B>prefix.c</B>
</TD>
<TD>
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.
</TD>
</TR>
<TR>
<TD>
<B>search.c</B>
</TD>
<TD>
Contains C implementations of several of the SEARCH and SEARCH EXT words
</TD>
</TR>
<TR>
<TD>
<B>softcore.c</B>
</TD>
<TD>
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.
</TD>
</TR>
<TR>
<TD>
<B>softwords/</B>
</TD>
<TD>
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.
</TD>
</TR>
<TR>
<TD>
<B>stack.c</B>
</TD>
<TD>
Stack methods
</TD>
</TR>
<TR>
<TD>
<B>sysdep.c</B>
</TD>
<TD>
Implementation of system dependent functions declared in sysdep.h
</TD>
</TR>
<TR>
<TD>
<B>testmain.c</B>
</TD>
<TD>
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.
</TD>
</TR>
<TR>
<TD>
<B>tools.c</B>
</TD>
<TD>
Contains C implementations of TOOLS and TOOLS EXT words, the debugger, and debugger support words.
</TD>
</TR>
<TR>
<TD>
<B>vm.c</B>
</TD>
<TD>
Virtual Machine methods
</TD>
</TR>
<TR>
<TD>
<B>win32.c & unix.c</B>
</TD>
<TD>
Platform extensions words loaded in ficl.c by ficlCompilePlatform() - conditioned on FICL_WANT_PLATFORM
</TD>
</TR>
<TR>
<TD>
<B>words.c</B>
</TD>
<TD>
Exports ficlCompileCore(), the run-time dictionary builder, and contains most precompiled CORE and CORE-EXT words.
</TD>
</TR>
</TABLE>
</DIV>
</BODY>
</HTML>