Index

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

Ficl 4.0 is smaller, faster, and more capable than any previous version. For more information on why Ficl 4.0 is so gosh-darned swell, see the What's New In Ficl 4.0? section of the overview.

Since the Ficl API has changed so dramatically, you can't just drop the new Ficl source. You have two basic choices: use the FICL_WANT_COMPATIBILITY support, and switching to the new API.

Note that using either of these choices requires that you recompile your application. You cannot build Ficl 4 into a shared library or DLL and use it with an application expecting Ficl 3.0. Stated another way: Ficl 4 is source compatible but not binary compatible with Ficl 3.

If you want to get Ficl 4.0 up and running in your project as quickly as possible, FICL_WANT_COMPATIBILITY is what you'll want to use. There are two easy steps, one of which you might be able to skip:

1. Set the C preprocessor constant FICL_WANT_COMPATIBILITY to 1. The best way is by adding the following line to ficllocal.h:

   	#define FICL_WANT_COMPATIBILITY (1)
   

2. If you use a custom ficlTextOut() function, you'll have to rename it, and explicitly specify it to Ficl. Renaming it is necessary, because the Ficl compatibility layer also provides one for code that called ficlTextOut() directly (instead of calling vmTextOut() as it should have). We recommend renaming your function to ficlTextOutLocal(), as we have have provided a prototype for this function for you in ficlcompatibility.h. This will save you the trouble of defining your own prototype, ensuring you get correct name decoration / linkage, etc.

   There are two methods you can use to specify your ficlTextOut() function:

   1. Specify it in the FICL_INIT_INFO structure passed in to ficlInitSystem(). This is the preferred method, as it ensures you will see the results of Ficl's initialization code, and it will be automatically passed in to every newly created VM.
   2. Set it explicitly in every VM by calling vmSetTextOut() and passing it in.

   Note: Any other method, such as setting it by hand in the FICL_SYSTEM or FICL_VM structures, will not work. There is a special compatibility layer for old-style OUTFUNC functions, but it is only invoked properly when you use one of the two methods mentioned above.

This should be sufficient for you to recompile-and-go with Ficl 4. If it's not, please let us know, preferably including a suggested solution to the problem.

Since most (all?) of the external symbols have changed names since the 3.0 series, here is a quick guide to get you started on renaming everything. This is by no means an exhaustive list; this is meant to guide you towards figuring out what the new name should be. (After all, part of the point of this massive renaming was to make all the external symbols consistent.)

Every external type has been renamed. They all begin with the word ficl, and they use mixed case (instead of all upper-case, which is now reserved for macros). Also, the confusingly-named string objects have been renamed: FICL_STRING is now ficlCountedString, as it represents a "counted string" in the language, and the more commonly-used STRINGINFO is now simply ficlString.

old name	new name
FICL_SYSTEM	ficlSystem
FICL_VM	ficlVm
FICL_SYSTEM_INFO	ficlSystemInformation
FICL_WORD	ficlWord
IPTYPE	ficlIp
FICL_CODE	ficlPrimitive
OUTFUNC	ficlOutputFunction
FICL_DICTIONARY	ficlDictionary
FICL_STACK	ficlStack
STRINGINFO	ficlString
FICL_STRING	ficlCountedString

In addition, many structure names have changed. To help ease the heartache, we've also added some accessor macros. So, in case they change in the future, your code might still compile (hooray!).

old name	new name	accessor
pExtend	context	ficlVmGetContext(), ficlSystemGetContext()
pStack	dataStack	ficlVmGetDataStack()
fStack	floatStack	ficlVmGetFloatStack()
rStack	returnStack	ficlVmGetReturnStack()

Text output callbacks have changed in two major ways:

• They no longer take a VM pointer; they now take a ficlCallback structure. This allows output to be printed before a VM is defined, or in circumstances where a VM may not be defined (such as an assertion failure in a ficlSystem...() function).
• They no longer take a flag indicating whether or not to add a "newline". Instead, the function must output a newline whenever it encounters a \n character in the text.

If you don't want to rewrite your output function yet, you can "thunk" the new-style call to the old-style. Just pass in ficlOldnamesCallbackTextOut as the name of the output function for the system and VM, and then set the thunkedTextout member of the ficlSystem or ficlVm to your old-style text output function.

old name	new name
PUSHPTR(p)	ficlStackPushPointer(vm->dataStack, p)
POPUNS()	ficlStackPopUnsigned(vm->dataStack)
GETTOP()	ficlStackGetTop(vm->dataStack)
FW_IMMEDIATE	FICL_WORD_IMMEDIATE
FW_COMPILE	FICL_WORD_COMPILE_ONLY
VM_INNEREXIT	FICL_VM_STATUS_INNER_EXIT
VM_OUTOFTEXT	FICL_VM_STATUS_OUT_OF_TEXT
VM_RESTART	FICL_VM_RESTART

One more note about macros. Ficl now ships with a standard place for you to tweak the Ficl compile-time preprocessor switches such as FICL_WANT_COMPATIBILITY and FICL_WANT_FLOAT. 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.

Every function that deals primarily with a particular structure is now named after that structure. For instance, any function that takes a ficlSystem as its first argument is named ficlSystemSomething(). Any function that takes a ficlVm as its first argument is named ficlVmSomething(). And so on.

Also, functions that create a new object are always called Create (not Alloc, Allot, Init, or New). Functions that create a new object are always called Destroy (not Free, Term, or Delete).

old name	new name
ficlInitSystem()	ficlSystemCreate()
ficlTermSystem()	ficlSystemDestroy()
ficlNewVM()	ficlSystemCreateVm()
ficlFreeVM()	ficlVmDestroy()
dictCreate()	ficlDictionaryCreate()
dictDelete()	ficlDictionaryDestroy()

All functions exported by Ficl now start with the word ficl. This is a feature, as it means the Ficl project will no longer pollute your namespace.

old name	new name
PUSHPTR(p)	ficlStackPushPointer(vm->dataStack, p)
POPUNS()	ficlStackPopUnsigned(vm->dataStack)
GETTOP()	ficlStackGetTop(vm->dataStack)
ltoa()	ficlLtoa()
strincmp()	ficlStrincomp()

A few entry points have simply been removed. For instance, functions specifically managing a system's ENVIRONMENT settings have been removed, in favor of managing the system's environment dictionary directly:

old name	new name
ficlSystemSetEnvironment(system)	ficlDictionarySetConstant(ficlSystemGetEnvironment(system), ...)
ficlSystemSet2Environment(system)	ficlDictionarySet2Constant(ficlSystemGetEnvironment(system), ...)

In a similar vein, ficlSystemBuild() has been removed in favor of using ficlDictionarySetPrimitive() directly:

old name	new name
ficlSystemBuild(system, ...)	ficlDictionarySetPrimitive(ficlSystemGetDictionary(system), ...)

Finally, there is no exact replacement for ficlExec(). 99% of the code that called ficlExec() never bothered to manage SOURCE-ID properly. If you were calling ficlExec(), and you weren't changing SOURCE-ID (or vm->sourceId) to match, you should replace those calls with ficlVmEvaluate(), which will manage SOURCE-ID for you.

There is a function that takes the place of ficlExec() which doesn't change SOURCE-ID: ficlVmExecuteString(). However, instead of taking a straight C string (a char *), it takes a ficlString * as its code argument. (This is to discourage its use.)

Note: none of these changes should affect you. If they do, there's probably a problem somewhere. Either Ficl's API doesn't abstract away something enough, or you are approaching a problem the wrong way. Food for thought.

There's only one internal change worth noting here. The top value on a Ficl stack used to be at (to use the modern structure names) stack->top[-1]. It is now at stack->top[0]. In other words, the "stack top" pointer used to point past the top element; it now points at the top element. (Pointing at the top element is not only less confusing, it is also faster.)