What's new in version 2.04

ficlwin

• Catches exceptions thrown by VM in ficlThread (0 @ for example) rather than passing them off to the OS. 

ficl bugs vanquished

• Fixed leading delimiter bugs in s" ." .( and ( (reported by Reuben Thomas)
• Makefile tabs restored (thanks to Michael Somos)
• ABORT" now throws -2 per the DPANS (thanks to Daniel Sobral for sharp eyes again) 
• ficlExec does not print the prompt string unless (source-id == 0)
• Various fixes contributed by the FreeBSD team.

ficl enhancements

• Words.c: modified ficlCatch to use vmExecute and vmInnerLoop (request of Daniel Sobral) Added vmPop and vmPush functions (by request of Lars Krueger ) in vm.c These are shortcuts to the param stack. (Use LVALUEtoCELL to get things into CELL form) 
• Added function vmGetStringEx with a flag to specify whether or not to skip lead delimiters
• Added non-std word: number?
• Added CORE EXT word AGAIN (by request of Reuben Thomas) 
• Added double cell local (2local) support
• Augmented Johns Hopkins local syntax so that locals whose names begin with char 2 are treated as 2locals (OK - it's goofy, but handy for OOP)
• C-string class revised and enhanced - now dynamically sized
• C-hashstring class derived from c-string computes hashcode too.

What's new in version 2.03

New words 

• clock              (FICL)
• clocks/sec         (FICL)
• dnegate            (DOUBLE)
• ms                 (FACILITY EXT - replaces MSEC ficlWin only)
• throw              (EXCEPTION)
• catch              (EXCEPTION)
• allocate           (MEMORY)
• free               (MEMORY)
• resize             (MEMORY)
• within             (CORE EXT)
• alloc              (class method)
• alloc-array        (class method)
• free               (class method)

• Bug fix in isNumber(): used to treat chars between 'Z' and 'a' as valid in base 10... (harmless, but weird)
• ficlExec pushes the ip and interprets at the right times so that nested calls to ficlExec behave the way you'd expect them to.
• evaluate respects count parameter, and also passes exceptional return conditions back out to the calling instance of ficlExec.
• VM_QUIT now clears the locals dictionary in ficlExec.

• File Menu: recent file list and Open now load files.
• Text ouput function is now faster through use of string caching. Cache flushes at the end of each line and each time ficlExec returns.
• Edit/paste now behaves more reasonably for text. File/open loads the specified file.
• Registry entries specify dictionary and stack sizes, default window placement, and whether or not to create a splitter for multiple VMs. See HKEY_CURRENT_USER/Software/CodeLab/ficlwin/Settings

• This version includes changes to make it 64 bit friendly. This unfortunately meant that I had to tweak some core data types and structures. I've tried to make this transparent to 32 bit code, but a couple of things got renamed. INT64 is now DPINT. UNS64 is now DPUNS. FICL_INT and FICL_UNS are synonyms for INT32 and UNS32 in 32 bit versions, but a are obsolescent. Please use the new data types instead. Typed stack operations on INT32 and UNS32 have been renamed because they operate on CELL scalar types, which are 64 bits wide on 64 bit systems. Added BITS_PER_CELL, which has legal values of 32 or 64. Default is 32.
• ficl.c: Added ficlExecXT() - executes an xt completely before returning, passing back any exception codes generated in the process. Normal exit code is VM_INNEREXIT.
• ficl.c: Added ficlExecC() to operate on counted strings as opposed to zero terminated ones.
• ficlExec pushes ip and executes interpret at the right times so that nested calls to ficlExec behave the way you'd expect them to.
• ficlSetStackSize() allows specification of stack size at run-time (affects subsequent invocations of ficlNewVM()).
• vm.c: vmThrow() checks for (pVM->pState != NULL) before longjmping it. vmCreate nulls this pointer initially. 
• EXCEPTION wordset contributed by Daniel Sobral of FreeBSD
• MEMORY-ALLOC wordset contributed by Daniel Sobral, too. Added class methods alloc and alloc-array in softwords/oo.fr to allocate objects from the heap.
• Control structure match check upgraded (thanks to Daniel Sobral for this suggestion). Control structure mismatches are now errors, not warnings, since the check accepts all syntactally legal constructs.
• Added vmInnerLoop() to vm.h. This function/macro factors the inner  interpreter out of ficlExec so it can be used in other places. Function/macro behavior is conditioned on INLINE_INNER_LOOP in sysdep.h. Default: 1 unless _DEBUG is set. In part, this is because VC++ 5 goes apoplectic when trying to compile it as a function. See 

comments in vm.c 
• EVALUATE respects the count parameter, and also passes exceptional return conditions back out to the calling instance of ficlExec.
• VM_QUIT clears locals dictionary in ficlExec()
• Added Michael Gauland's ficlLongMul and ficlLongDiv and support routines to math64.c and .h. These routines are coded in C, and are compiled only if PORTABLE_LONGMULDIV == 1 (default is 0).
• Added definition of ficlRealloc to sysdep.c (needed for memory allocation wordset). If your target OS supports realloc(), you'll probably want to redefine ficlRealloc in those terms. The default version does ficlFree followed by ficlMalloc.
• testmain.c: Changed gets() in testmain to fgets() to appease the security gods.
• testmain: msec renamed to ms in line with the ANS
• softcore.pl now removes comments & spaces at the start and end of lines. As a result: sizeof (softWords) == 7663 bytes (used to be 20000)  and consumes 11384 bytes of dictionary when compiled
• Deleted license paste-o in readme.txt (oops).

What's new in version 2.02

• marker        (CORE EXT)
• forget       (TOOLS EXT)
• forget-wid        (FICL)
• ficl-wordlist     (FICL)
• ficl-vocabulary   (FICL)
• hide              (FICL)
• hidden            (FICL)
• Johns Hopkins local variable syntax (as best I can determine)

• forget now adjusts the dictionary pointer to remove the name of the word being forgotten (name chars come before the word header in ficl's dictionary)
• :noname used to push the colon control marker and its execution token in the wrong order
• source-id now behaves correctly when loading a file.
• refill returns zero at EOF (Win32 load). Win32 load command continues to be misnamed. Really ought to be called included, but does not exactly conform to that spec either (because included expects a string signature on the stack, while Ficl's load expects a filename upon invocation). The "real" LOAD is a BLOCK word.

• dictUnsmudge no longer links anonymous definitions into the dictionary
• oop is no longer the default compile wordlist at startup, nor is it in the search order. Execute also oop definitions to use Ficl OOP.
• Revised oo.fr extensively to make more use of early binding
• Added meta - a constant that pushes the address of metaclass. See oo.fr for examples of use.
• Added classes: c-ptr  c-bytePtr  c-2bytePtr  c-cellPtr These classes model pointers to non-object data, but each knows the size of its referent.

What's new in version 2.01

• Bug fix: (local) used to leave a value on the stack between the first and last locals declared. This value is now stored in a static.
• Added new local syntax with parameter re-ordering. See description below. (No longer compiled in version 2.02, in favor of the Johns Hopkins syntax)

What's new in version 2.0

• New ANS Forth words: TOOLS and part of TOOLS EXT, SEARCH and SEARCH EXT, LOCALS and LOCALS EXT word sets, additional words from CORE EXT, DOUBLE, and STRING. (See the function ficlCompileCore in words.c for an alphabetical list by word set).
• Simple USER variable support - a user variable is a virtual machine instance variable. User variables behave as VARIABLEs in all other respects.
• Object oriented syntax extensions (see below)
• Optional stack underflow and overflow checking in many CORE words (enabled when FICL_ROBUST >= 2)
• Various bug fixes

What is ficl?

• 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

Ficl features

• Code is 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 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 VMs share one system dictionary; 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.
• Simple incorporation into existing systems: the sample implementation requires three Ficl function calls (see the example program in testmain.c).
• ROM able: 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 an 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++
• Does full 32 bit math (but you need to implement two mixed precision math primitives (see sysdep.c))
• Type 1 indirect threaded interpreter

Porting ficl

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

To-Do List (target system dependent words)

• Unimplemented system dependent CORE word: KEY 
• Kludged CORE word: ACCEPT

Application Programming Interface

void 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(void)

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(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.

FICL_VM *ficlNewVM(void)

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(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(void)

Returns a pointer to the main system dictionary, or NULL if the system is uninitialized.

FICL_DICT *ficlGetEnv(void)

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

void ficlSetEnv(char *name, UNS32 value)

Enters a new constant into the environment dictionary, with the specified name and value.

void ficlSetEnvD(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(void)

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_DICT *dp)

Defined in words.c, this function builds ficl's primitives. 

void ficlCompileSoftCore(FICL_VM *pVM)

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

Local Variables

Ficl includes support for LOCALS and LOCALS EXT words (all three of them!). I've implemented both of the local variable syntaxes suggested in DPANS Appendix A.13. Examples: (By the way, Ficl implements -ROT as : -rot   2 -roll ; ) 

\ Using LOCALS| from LOCALS EXT 
: -rot   ( a b c -- c a b )
   locals| c b a |
  c a b 
;

\ Using LOCAL END-LOCAL
: -rot   ( a b c -- c a b )
    local c
    local b
    local a
    end-locals
    c a b
;

Ficl 2.02 includes by default an implementation of the Johns Hopkins local syntax (as best I can determine it from examples on the web). This syntax lets you declare local variables that look very much like a stack comment. Variables in the declaration appear in the "correct" order for a stack comment. Everything after the -- is treated as a comment. In addition, you can insert a | before the -- to declare one or more zero-initialized locals. Example: 

:tuck0   { a b c | d -- 0 a b c }
    d a b c ;

In ficl 2.04 and later, this facilty can also declare double cell locals (this is handy for OOP, where objects take two cells to represent on the stack). Double cell locals (AKA 2locals) have names that start with 2. See ficl/softwords/string.fr for examples.

Ficl 2.01 added yet another local syntax that models a stack comment. This one is not compiled in the release, but you can add it by editing softwords/softcore.bat to include the file ficllocal.fr. In this case, parameters are re-ordered so that the rightmost initialized param comes from the top of the stack. The syntax is: 

{{ <initialized params> -- <cleared params> }}

: -rot   ( a b c -- c a b )
    {{ a b c }} 
    c a b  
; 

: tuck0  ( a b c -- 0 a b c ) 
    {{ a b c -- d }} 
    d a b c  
; 

Search Order

Soft Words

Ficl extras

Number syntax

You can precede a number with "0x", as in C, and it will be interpreted as a hex value regardless of the value of BASE. Example: 

ok> decimal 123 . cr 

123 
ok> 0x123 . cr
291 

Search order words

Note: Ficl resets the search order whenever it does ABORT. If you don't like this behavior, just comment out the dictResetSearchOrder() lines in ficlExec(). 
 

>search   ( wid -- )

Push wid onto the search order. Many of the other search order words are written in terms of the SEARCH> and >SEARCH primitives.

search>   ( -- wid )

Pop wid off the search order

ficl-set-current   ( wid -- old-wid )

Set wid as compile wordlist, leaving the previous compile wordlist on the stack

ficl-vocabulary   ( nBins "name" -- )

Creates a ficl-wordlist with the specified number of hash table bins, binds it to the name, and associates the semantics of vocabulary with it (replaces the top wid in the search order list with its own wid when executed)

ficl-wordlist   ( nBins -- wid )

Creates a wordlist with the specified number of hash table bins, and leaves the address of the wordlist on the stack. A ficl-wordlist behaves exactly as a regular wordlist, but it may search faster depending on the number of bins chosen and the number of words it contains at search time. As implemented in ficl, a wordlist is single threaded by default. 

forget-wid   ( wid -- )

Iterates through the specified wordlist and unlinks all definitions whose xt addresses are greater than or equal to the value of HERE, the dictionary fill pointer. 

hide   ( -- current-wid-was )

Push the hidden wordlist onto the search order, and set it as the current compile wordlist (unsing ficl-set-current). Leaves the previous compile wordlist ID. I use this word to hide implementation factor words that have low reuse potential so that they don't clutter the default wordlist. To undo the effect of hide, execute  previous set-current

hidden   ( -- wid )

Wordlist for storing implementation factors of ficl provided words. To see what's in there, try:  hide words previous set-current

wid-set-super   ( wid -- )

Ficl wordlists have a parent wordlist pointer that is not specified in standard Forth. Ficl initializes this pointer to NULL whenever it creates a wordlist, so it ordinarily has no effect. This word sets the parent pointer to the wordlist specified on the top of the stack. Ficl's implementation of SEARCH-WORDLIST will chain backward through the parent link of the wordlist when searching. This simplifies Ficl's object model in that the search order does not need to reflect an object's class hierarchy when searching for a method. It is possible to implement Ficl object syntax in strict ANS Forth, but method finders need to manipulate the search order explicitly.

User variables

user   ( -- ) name

Create a user variable with the given name. User variables are virtual machine local. Each VM allocates a fixed amount of storage for them. You can change the maximum number of user variables allowed by defining FICL_USER_CELLS on your compiiler's command line. Default is 16 user cells.

Miscellaneous

-roll   ( xu xu-1 ... x0 u -- x0 xu-1 ... x1 ) 

Rotate u+1 items on top of the stack after removing u. Rotation is in the opposite sense to ROLL

-rot   ( a b c -- c a b )

Rotate the top three stack entries, moving the top of stack to third place. I like to think of this as 1¹/₂swap because it's good for tucking a single cell value behind a cell-pair (like an object). 

.env   ( -- )

List all environment variables of the system

.hash   ( -- )

List hash table performance statistics of the wordlist that's first in the search order

.ver   ( -- )

Display ficl version ID

>name   ( xt -- c-addr u )

Convert a word's execution token into the address and length of its name

body>   ( a-addr -- xt )

Reverses the effect of CORE word >body (converts a parameter field address to an execution token)

compile-only

Mark the most recently defined word as being executable only while in compile state. Many immediate words have this property.

empty   ( -- ) 

Empty the parameter stack

endif

Synonym for THEN

parse-word   ( <spaces>name -- c-addr u )

Skip leading spaces and parse name delimited by a space. c-addr is the address within the input buffer and u is the length of the selected string. If the parse area is empty, the resulting string has a zero length. (From the Standard)

w@   ( addr -- x )

Fetch a 16 bit quantity from the specified address

w!   ( x addr -- )

Store a 16 bit quantity to the specified address (the low 16 bits of the given value)

x.   ( x -- )

Pop and display the value in hex format, regardless of the current value of BASE

FiclWin Extras (defined in testmain.c)

break   ( -- )

Does nothing - just a handy place to set a debugger breakpoint

cd      ( "directory-name<newline>" -- )

Executes the Win32 chdir() function, changing the program's logged directory.

clock   ( -- now )

Wrapper for the ANSI C clock() function. Returns the number of clock ticks elapsed since process start.

clocks/sec   ( -- clocks_per_sec )

Pushes the number of ticks in a second as returned by clock

load    ( "filename<newline>" -- )

Opens the Forth source file specified and loads it one line at a time, like INCLUDED (FILE)

pwd     ( -- )

Prints the current working directory as set by cd

system  ( "command<newline>" -- )

Issues a command to a shell; implemented with the Win32 system() call.

spewhash   ( "filename<newline>" -- )

Dumps all threads of the current compilation wordlist to the specified text file. This was useful when I thought there might be some point in attempting to optimize the hash function. I no longer harbor those illusions.

FiclWin Exclusives (no source provided)

!oreg   ( c -- )

Set the value of the simulated LED register as specified (0..255)

@ireg   ( -- c )

Gets the value of the simulated switch block (0..255)

!dac    ( c -- )

Sets the value of the bargraph control as specified. Valid values range from 0..255

@adc    ( -- c )

Fetches the current position of the slider control. Range is 0..255

status"   ( "ccc<quote>" -- )

Set the mainframe window's status line to the text specified, up to the first trailing quote character.

ms   ( u -- )

Causes the running virtual machine to sleep() for the number of milliseconds specified by the top-of-stack value.

DISCLAIMER OF WARRANTY and LICENSE

Any third party may reproduce, distribute, or modify the ficl software code or any derivative works thereof without any compensation or license, provided that the original author information and this disclaimer text are retained in the source code files. The ficl software code is provided on an "as is" basis without warranty of any kind, including, without limitation, the implied warranties of merchantability and fitness for a particular purpose and their equivalents under the laws of any jurisdiction. 

The FiclWin distribution, a derivative work of the ficl source code, is hereby licensed for unrestricted non-commercial use under the ficl license provided the user notifies the author (John Sadler) in writing or by electronic mail or their intended use of the FiclWin sources. You may freely redistribute the FiclWin distribution provided it contains this notice and adheres to all other provisions of this license. 

Reselling the FiclWin source code, executable, or works derived from the FiclWin source code is prohibited under this license. Please contact me directly in order to discuss license terms for commercial use and distribution.

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.