upgrading ficl
Description: Ficl - embedded scripting with object oriented programming
Keywords: scripting prototyping tcl OOP Forth interpreter C

| upgrading ficl
| 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.
| Using `FICL_WANT_COMPATIBILITY`
> 1. 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: 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)
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: 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. 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.
| Using The New API
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.)
| Types
> 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`
| Structure Members
> 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()`
| Callback Functions
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.
| Renamed Macros
> 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`
| `ficllocal.h`
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.
| Renamed Functions
> 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()`
| Removed Functions
> 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.)
| Internal Changes
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.)