From f4e75c6395310fa4b119d3eaa9a4a9f8913df200 Mon Sep 17 00:00:00 2001 From: "Pedro F. Giffuni" Date: Tue, 12 May 2015 03:27:06 +0000 Subject: Update to ficl 4.1.0 (latest release on sourceforge) --- doc/source/api.ht | 250 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 250 insertions(+) create mode 100644 doc/source/api.ht (limited to 'doc/source/api.ht') diff --git a/doc/source/api.ht b/doc/source/api.ht new file mode 100644 index 000000000000..599ba9e16b14 --- /dev/null +++ b/doc/source/api.ht @@ -0,0 +1,250 @@ +
\n" + "" + prototype + "\n
\n" +?> + + + + + + +A Ficl dictionary is equivalent to the FORTH "dictionary"; it is where words are stored. +A single dictionary has a single HERE pointer. +

+ +A Ficl system information structure is used to change default values used +in initializing a Ficl system. +

+ +A Ficl system contains a single dictionary, and one or more virtual machines. +

+ +A Ficl stack is equivalent to a FORTH "stack". Ficl has three stacks: +

+ +

+ +A Ficl virtual machine (or vm) represents a single running instance of the Ficl interpreter. +All virtual machines in a single Ficl system see the same dictionary. +

+ + + +Though Ficl's API offers a great deal of flexibility, most programs +incorporating Ficl simply use it as follows: + +

    + +
  1. +Create a single ficlSystem using ficlSystemCreate(NULL). + +
  2. +Add native functions as necessary with ficlDictionarySetPrimitive(). + +
  3. +Add constants as necessary with ficlDictionarySetConstant(). + +
  4. +Create one (or more) virtual machine(s) with ficlSystemCreateVm(). + +
  5. +Add one or more scripted functions with ficlVmEvaluate(). + +
  6. +Execute code in a Ficl virtual machine, usually with ficlVmEvaluate(), +but perhaps with ficlVmExecuteXT(). + +
  7. +At shutdown, call ficlSystemDestroy() on the single Ficl system. + +
+ + + + +The following is a partial listing of functions that interface your +system or program to Ficl. For a complete listing, see ficl.h +(which is heavily commented). For a simple example, see main.c. +

+ +Note that as of Ficl 4, the API is internally consistent. +Every external entry point starts with the word +ficl, and the word after that also corresponds +with the first argument. For instance, a word that operates +on a ficlSystem * will be called ficlSystemSomething(). + + + + +

+ + + +Resets a ficlSystemInformation structure to all zeros. +(Actually implemented as a macro.) Use this to initialize a ficlSystemInformation +structure before initializing its members and passing it +into ficlSystemCreate() (below). + + + +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()). If you pass in a NULL +pointer, you will recieve a ficlSystem using the default +sizes for the dictionary and stacks. + + + + +Reclaims memory allocated for the Ficl system including all +dictionaries and all virtual machines created by +ficlSystemCreateVm(). Note that this will not +automatically free memory allocated by the FORTH memory allocation +words (ALLOCATE and RESIZE). + + + +Adds a new word to the dictionary with the given +name, code pointer, and flags. To add +

+ +The flags parameter is a bitfield. The valid +flags are:

    + +
  • +FICL_WORD_IMMEDIATE +
  • +FICL_WORD_COMPILE_ONLY +
  • +FICL_WORD_SMUDGED +
  • +FICL_WORD_OBJECT +
  • +FICL_WORD_INSTRUCTION + +
+ +For more information on these flags, see ficl.h. + + + + +Creates a new virtual machine in the specified system. + + + + + the specified C string (zero-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. Calls to ficlVmEvaluate() +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). + + + + +Same as ficlExec, but takes a pointer to a ficlWord 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. + + + +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. + + + +Create, initialize, and return a VM from the heap using +ficlMalloc. Links the VM into the system VM list for later reclamation +by ficlTermSystem. + + + +Returns the address of the specified word in the main dictionary. +If no such word is found, it returns NULL. +The address is also a valid execution token, and can be used in a call to ficlVmExecuteXT(). + +ficlDictionary *ficlVmGetDictionary(ficlVm *system)") ?> + +Returns a pointer to the main system dictionary. + + + + +Returns a pointer to the environment dictionary. This dictionary +stores information that describes this implementation as required by the +Standard. + + + + + + +Returns a pointer to the locals dictionary. This function is +defined only if FICL_WANT_LOCALS is non-zero (see ficl.h). +The locals dictionary is the symbol table for +local variables. + + +
+ + + + +There are a lot of preprocessor constants you can set at compile-time +to modify Ficl's runtime behavior. Some are required, such as telling +Ficl whether or not the local platform supports double-width integers +(FICL_PLATFORM_HAS_2INTEGER); +some are optional, such as telling Ficl whether or not to use the +extended set of "prefixes" (FICL_WANT_EXTENDED_PREFIXES). +

+ +The best way to find out more about these constants is to read ficl.h +yourself. The settings that turn on or off Ficl modules all start with +FICL_WANT. The settings relating to functionality available +on the current platform all start with FICL_PLATFORM. +

+ + + +ficllocal.h") ?> + +One more note about constants. Ficl now ships with a standard place for +you to tweak the Ficl compile-time preprocessor constants. +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. + + + + -- cgit v1.2.3