NAME

OKit - Object Tree, Virtual Machine and Compiler for concatenative languages in a shared library.

AUTHOR

Author:	Yann LANDRIN-SCHWEITZER aka Varkhan
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]	'<CODE_NAME>' or '<CODE_NAME:data>'
	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
"	034	0x22		:	058	0x3A
<	060	0x3C		>	062	0x3E
[	091	0x5B		]	093	0x5D
«	171	0xAB		¬	172	0xAC
»	187	0xBB



Execution

"OKit_ListEval" or "OKit_ObjectEval" respectively take an OKit_List or an OKit_Object in addition to an OKit_Stack and OKit_NameSpace, on which they will execute the OKit_List or OKit_Object.

The OKit_List type can contain any particular OKit_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 OKit_Strg type.

The 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