\n" ?> 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. FICL_WANT_COMPATIBILITY") ?> 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. 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!). 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.

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

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. dataStack, p)") oldvsnew("POPUNS()", "ficlStackPopUnsigned(vm->dataStack)") oldvsnew("GETTOP()", "ficlStackGetTop(vm->dataStack)") oldvsnew("ltoa()", "ficlLtoa()") oldvsnew("strincmp()", "ficlStrincomp()") endoldvsnew() ?> 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: In a similar vein, ficlSystemBuild() has been removed in favor of using ficlDictionarySetPrimitive() directly: 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.)