OKit shared library NAME OKit - Object Tree, Virtual Machine and Compiler for concatenative languages, in a shared library. AUTHOR Author: Yann LANDRIN-SCHWEITZER Contact: varkhan@free.fr Homepage: http://varkhan.free.fr/ DESCRIPTION This library provides an implementation of many basic data types, as integers, floats, strings, lists, as well as executable primitives, encapsulated in a generic object structure. Lists can contain themselves, as any of these primitive types. Also included are methods for parsing and executing such lists, and error tracking. The library as a whole provides the necessary framework for manipulating concatenative code. The object hierarchy tree is described below, stating object name, content, category (between brackets), and string representation (between quotes). OKit_Object Generic object [none] --- OKit_Void Undefined object [null] '¬' OKit_Intg Integer number on 32 bits [scal] '123456' OKit_Fltp Floating point number [scal] '3.1415926e+00' OKit_Strg Character string [scal] '"any text"' OKit_List All-purposes list [list] '[ obj1 obj2 ... ]' OKit_Code Dynamic executable code [exec] '' or '' OKit_Bltn Static executable code [exec] '«BLTN_NAME»' Note 1: objects in an OKit_List can be separated by spaces, tabs, or linefeeds / carry returns Note 2: here is a table of numeric values for special characters: CHR DEC HEX CHR DEC HEX " 34 0x22 : 58 0x3A < 60 0x3C > 62 0x3E [ 91 0x5B ] 93 0x5D « 171 0xAB ¬ 172 0xAC » 187 0xBB Execution "OKit_ListEval" or "OKit_ObjectEval" respectively take a List or an Object in addition to a Stack and NameSpace, on which they will execute the List or Object. The List type can contain any particular Object. It also provides a mecanism to build a program, since when a List gets executed, all its elements are executed in turn. All OKit_Code and OKit_Bltn executable instructions, as well as the execution of an OKit_List, use an OKit_Stack and an OKit_NameSpace. They take arguments and return results on the OKit_Stack, while having access to named variables in the OKit_NameSpace. Execution of an OKit_List is the act to take every member of this list and deposit it on the stack if it is an OKit_Void, OKit_Intg, OKit_Strg, or OKit_List, or execute it if it is a Code or an OKit_Bltn. Execution stops when the end of the list is reached, or the execution of an [exec] type failed, from lack of arguments, bad argument types, or some other error. These execution routines return an error status (an OKit_Status structure), that is an error code and the associated message, providing a brief description of the error. <0,""> stands for "no error". Compiler "OKit_ListParse" or "OKit_ObjectParse" respectively take a character string and produce an OKit_List or an OKit_Object. The string is interpretated into objects so that printing these objects would produce back the original string, or something very similar. Syntax A valid string for "OKit_ListParse" is one or more string representation of objects, among: Built-ins: e.g. ' «HELP» ', a builtin command name Numbers: e.g. ' 3.1425e+00 ', an integer or floating point number Strings: e.g. ' "HELLO" ', a litteral string Lists: e.g. ' [ obj1 obj2 ] ', a list of other objects During parsing, a bareword is looked-up as a number, then if not applicable in the set of built-in commands, and finally parsed as a string if it could not be found. Data The memory representation of an OKit_Object has two parts: a generic memory and tracking structure, used for reference counting and cross-referencing, and a content part, type-dependant. The OKit_Void data type is the default type: it is only used to mark internal OKit_Object use, or in a standard context that something has gone wrong in memory management. The three scalar data types are simple counted memory segments: fixed size for the OKit_Intg and OKit_Fltp types, variable size (which means keeping a 'size' register) for the Strg type. The OKit_List type is a doubly-linked list, each of its nodes (possibly non- existant) containing an OKit_Object. As for the OKit_Code and OKit_Bltn (executables) types, they are complex structures, containing, among other things, a pointer toward a segment of assembler code retaining the actual implementation, input and output arity information, and a formatted description. The "system" types (OKit_Stack and OKit_NameSpace, or named variables table) play an essential role in memory management: Objects can be freed when no reference for them in one of these tables exist any more. They also are the essential holders for instruction arguments and results. BUGS Innumerable. Don't forget to report them, even if each bug correction is the source for new ones... TODO Implement pseudo-code (list-compiled code) file dumping, in a cross-platform format. SEE ALSO OKeval: a library defining a standard built-ins set, and an executable wrapper, enabeling the execution of arbitrary OKit code using these built-ins. GOKe: a Gtk interface for interactively executing OKit code and manipulating stack and variable lists. LICENSE This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA