Forth Inspired Command Language | |
Author: John Sadler (john_sadler@alum.mit.edu) | |
Created: 19 July 1997 | |
Revision 2.05: June 2000 |
What is ficl?Ficl (Forth inspired command language) a complete programming language interpreter based on ANS Forth and written in Standard C. Ficl is designed to be embedded into other systems as a command/macro/development prototype language. Ficl provides object extensions that can be used to wrap methods and structures of the host system without altering them. See below for examples of software that includes ficl. |
Where Forths usually view themselves as the center of the system and expect the rest of the system to be coded in Forth, Ficl acts as a component of the system. It is easy to export code written in C or ASM to Ficl in the style of TCL, or to invoke Ficl code from a compiled module. This allows you to do incremental development in a way that combines the best features of threaded languages (rapid development, quick code/test/debug cycle, reasonably fast) with the best features of C (everyone knows it, easier to support large blocks of code, efficient, type checking). In addition, Ficl provides a simple and powerful object model that can act as an object oriented adapter for code written in C (or asm, Forth, C++...). |
Ficl Design goals
|
DISCLAIMER OF WARRANTY and LICENSEFicl is freeware. Use it in any way that you like, with the understanding that the code is not supported.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. |
Application Programming InterfaceThe following is a partial listing of functions that interface your system or program to ficl. For a complete listing, see ficl.h (heavily commented). For examples, see testmain.c and the ficlwin sources (below). See the comments in ficl.c and ficl.h for additional information, and the example in file testmain.c.
|
Ficl extrasNumber syntaxYou 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:123 ok> 0x123 . cr 291 Search order wordsFicl implements many of the search order words in terms of two primitives called >SEARCH and SEARCH>. As their names suggest (assuming you're familiar with Forth), they push and pop the search order stack. See the list of Ficl extras for details.The standard does not appear to specify any conditions under which the search order is reset to a sane state. Ficl resets the search order to its default state whenever ABORT happens. This includes stack underflows and overflows. QUIT does not affect the search order. The minimum search order (set by ONLY) is equivalent to
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().
User variables
Miscellaneous
FiclWin Extras (defined in testmain.c)
FiclWin Exclusives (no source provided) |
ANS Required Information
ANS Forth System
Providing names from the Core Extensions word set Providing the Exception word set Providing names from the Exception Extensions word set Providing the Locals word set Providing the Locals Extensions word set Providing the Memory Allocation word set Providing the Programming-Tools word set Providing names from the Programming-Tools Extensions word set Providing the Search-Order word set Providing the Search-Order Extensions word set Implementation-defined OptionsThe implementation-defined items in the following list represent characteristics and choices left to the discretion of the implementor, provided that the requirements of the Standard are met. A system shall document the values for, or behaviors of, each item.
System dependent. You can change the default address alignment by defining FICL_ALIGN on your compiler's command line. The default value is set to 2 in sysdep.h. This causes dictionary entries and ALIGN and ALIGNED to align on 4 byte boundaries. To align on 2n byte boundaries, set FICL_ALIGN to n. Depends on target system, C runtime library, and your implementation of ficlTextOut(). None implemented in the versions supplied in words.c. Because ficlExec() is supplied a text buffer externally, it's up to your system to define how that buffer will be obtained. Depends on target system and implementation of ficlTextOut() Ficl characters are one byte each. There are no alignment requirements. No special processing is performed on characters beyond case-folding. Therefore, extended characters will not match their unaccented counterparts. Ficl uses the Standard C function isspace() to distinguish space characters. The rest is up to your library vendor. Uses the data stack The maximum supported value of BASE is 36. Ficl will assertion fail in function ltoa of vm.c if the base is found to be larger than 36 or smaller than 2. There will be no effect if NDEBUG is defined, however, other than possibly unexpected behavior. Target system dependent Does ABORT Target system dependent (implementation of outer loop that calls ficlExec) 255 Limited by available memory and the maximum unsigned value that can fit in a CELL (232-1). Ficl stores the first 31 characters of a definition name. Same as maximum definition name length None supported. This is up to the target system None supported. This is up to the target system Target system dependent. Ficl generally supports processors that can address 8 bit quantities, but there is no dependency that I'm aware of. System dependent. Ficl represents a CELL internally as a union that can hold INT32 (a signed 32 bit scalar value), UNS32 (32 bits unsigned), and an untyped pointer. No specific byte ordering is assumed. Assuming a 32 bit implementation, range for signed single-cell values is -231..231-1. Range for unsigned single cell values is 0..232-1. Range for signed double-cell values is -263..263-1. Range for unsigned single cell values is 0..264-1. None Default is 255. Depends on the setting of nPAD in ficl.h. System dependent, generally four. System dependent, generally one. This buffer is supplied by the host program. Ficl imposes no practical limit. Default is 255 characters. Depends on the setting of nPAD in ficl.h. Not presently supported Ficl is not case sensitive "ok>" Symmetric One (no others) System dependent. Ficl makes no special checks for overflow. No. Definitions are unsmudged after ; only, and only then if no control structure matching problems have been detected. Ambiguous ConditionsA system shall document the system action taken upon each of the general or specific ambiguous conditions identified in this Standard. See 3.4.4 Possible actions on an ambiguous condition.The following general ambiguous conditions could occur because of a combination of factors:
Ficl does ABORT and prints the name followed by " not found". Ficl stores the first 31 characters of the definition name, and uses all characters of the name in computing its hash code. The actual length of the name, up to 255 characters, is stored in the definition's length field. No problem: all addresses in ficl are absolute. You can reach any 32 bit address in Ficl's address space. Ficl makes no check for argument type compatibility. Effects of a mismatch vary widely depending on the specific problem and operands. Ficl returns a valid token, but the result of executing that token while interpreting may be undesirable. Results are target procesor dependent. Generally, Ficl makes no check for divide-by-zero. The target processor will probably throw an exception. With FICL_ROBUST (sysdep.h) set >= 2, most parameter stack operations are checked for underflow and overflow. Ficl does not check the return stack. No check - Evil results. Ficl generates an error message if the dictionary is too full to create a definition header. It checks ALLOT as well, but it is possible to make an unchecked allocation request that overflows the dictionary. Ficl protects all ANS Forth words with undefined interpretation semantics from being executed while in interpret state. It is possible to defeat this protection using ' (tick) and EXECUTE, though. Varies depending on the nature of the buffer. The input buffer is supplied by ficl's host function, and may reside in read-only memory. If so, writing the input buffer can ganerate an exception. String literals are stored in the dictionary, and are writable. In the unlikely event you are able to construct a pictured numeric string of more than 255 characters, the system will be corrupted unpredictably. The buffer area that holds pictured numeric output is at the end of the virtual machine. Whatever is mapped after the offending VM in memory will be trashed, along with the heap structures that contain it. Ficl does not copy parsed strings unless asked to. Ordinarily, a string parsed from the input buffer during normal interpretation is left in-place, so there is no possibility of overflow. If you ask to parse a string into the dictionary, as in SLITERAL, you need to have enough room for the string, otherwise bad things may happen. This is not usually a problem. Value will be truncated Most stack underflows are detected and prevented if FICL_ROBUST (sysdep.h) is set to 2 or greater. Otherwise, the stack pointer and size are likely to be trashed. Ficl returns for a new input buffer until a non-empty one is supplied.
Bad Things occur - unpredictable bacause the input buffer is supplied by the host program's outer loop. It finds the address of the definition before DOES> Not implemented This is OK until the cells are overwritten with something else. The dictionary maintains a hash table, and the table must be updated in order to de-allocate words without corruption. Target processor dependent. Consequences include: none (Intel), address error exception (68K). See above on data space read/write alignment Ficl detects a stack underflow and reports it, executing ABORT, as long as FICL_ROBUST is two or larger. Loop initiation words are responsible for checking the stack and guaranteeing that the control parameters are pushed. Any underflows will be detected early if FICL_ROBUST is set to two or greater. Note however that Ficl only checks for return stack underflows at the end of each line of text. No problem. Ficl's version of TO works correctly with VALUEs, CONSTANTs and VARIABLEs. Ficl prints an error message and does ABORT No check. Results vary depending on the specific problem. The word is postponed correctly. Ficl stores the first FICL_STRING_MAX-1 chars in the destination buffer. (The extra character is the trailing space required by the standard. Yuck.) Depends on target process or and C runtime library implementations of the << and >> operators on unsigned values. For I386, the processor appears to shift modulo the number of bits in a cell. words improperly used outside 6.1.0490 <# and 6.1.0040 #> (6.1.0030 #, 6.1.0050 #S, 6.1.1670 HOLD, 6.1.2210 SIGN) Don't. CREATE reserves a field in words it builds for DOES>to fill in. If you use DOES> on a word not made by CREATE, it will overwrite the first cell of its parameter area. That's probably not what you want. Likewise, pictured numeric words assume that there is a string under construction in the VM's scratch buffer. If that's not the case, results may be unpleasant. Locals Implementation-defined options
Default is 16. Change by redefining FICL_MAX_LOCALS, defined in sysdep.h Locals Ambiguous conditions
Locals can be found in interpretation state while in the context of a definition under construction. Under these circumstances, locals behave correctly. Locals are not visible at all outside the scope of a definition. See the CORE ambiguous conditions, above (no change) Programming Tools Implementation-defined options
SEE de-compiles definitions from the dictionary. Because Ficl words are threaded by their header addresses, it is very straightforward to print the name and other characteristics of words in a definition. Primitives are so noted. Colon definitions are decompiled, but branch target labels are not reconstructed. Literals and string literals are so noted, and their contents displayed. Search Order Implementation-defined options
Defaults to 16. Can be changed by redefining FICL_DEFAULT_VOCS, declared in sysdep.h Equivalent to FORTH-WORDLIST 1 SET-ORDER Search Order Ambiguous conditions
Ficl stores a link to the current definition independently of the compile wordlist while it is being defined, and links it into the compile wordlist only after the definition completes successfully. Changing the compile wordlist mid-definition will cause the definition to link into the new compile wordlist. Ficl prints an error message if the search order underflows, and resets the order to its default state. Ficl prints an error message if the search order overflows, and resets the order to its default state. |