System Types

Instructions manual





OKit: Object Tree, RPL Virtual Machine and compiler shared library

Copyright (C) 2000 Yann LANDRIN-SCHWEITZER


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


Author: Yann LANDRIN-SCHWEITZER
Contact: varkhan@free.fr
Homepage: http://varkhan.free.fr/





USES ErrLog.h





Stack definition






Function StackAlloc

Stack StackAlloc(unsigned long chksz) ;
Allocates a new, empty Stack.


Args
_chksz:buffer size increment


Returns
_NULL:if no memory was available
else the newly allocated Stack.


Errors
_ENOMEM:if no memory was available



Function StackFree

void StackFree(Stack stk) ;
Frees a Stack, dereferences and frees its contents.


Args
_stk:Stack to free



Function StackDepth

unsigned long StackDepth(Stack stk) ;
Returns the depth (number of elements) of a Stack.


Args
_stk:Stack we want to get information about


Returns
_-1:if a NULL Stack was passed as argument
else the Stack's depth.


Errors
_EINVAL:if a NULL Stack was passed as argument



Function StackPush

unsigned long StackPush(Stack stk, Object obj) ;
Pushes and references an Object onto a Stack.


Args
_stk:Stack
_obj:Object to push


Returns
_-1:if some error occurred
else the new depth of the Stack.


Errors
_EINVAL:if a NULL Stack or Object was passed as argument
_EACCES:if the Stack was freezed and consequently cannot receive Objects
_ENOMEM:if no memory was available



Function StackPop

Object StackPop(Stack stk) ;
Pops and dereferences an Object from a Stack.


Args
_stk:non-empty Stack


Returns
_NULL:if the Stack was NULL, empty or freezed
else the object popped from the stack.


Errors
_EINVAL:if a NULL Stack was passed as argument
_EACCES:if the Stack was freezed and consequently cannot yield Objects
_ENOMEM:if a memory disallocation failed (non-fatal error)



Function StackGet

Object StackGet(Stack stk, unsigned long num) ;
Gets an Object at a specified level of a Stack.


Args
_stk:non-empty Stack
_num:level at which to look for an object


Returns
_NULL:if the Stack was NULL, or the level invalid
else the object at level 'num' of the Stack (first level is 1).


Errors
_EINVAL:if a NULL or empty Stack was passed as argument, or the level was invalid



Function StackPut

Object StackPut(Stack stk, Object obj, unsigned long num) ;
Puts an Object at a specified level of a Stack.


Args
_stk:Stack
_obj:Object to put
_num:level at which to put an object


Returns
_NULL:if the Stack was NULL, or the level invalid
else the old object at the specified level of the Stack (first level is 1).


Errors
_EINVAL:if a NULL Stack or Object was passed as argument, or the level was invalid



Function StackChkType

unsigned long StackChkType(Stack stk, unsigned long argc, unsigned short * argt) ;
Checks the types of Objects on a Stack.


Args
_stk:Stack
_argc:number of Objects to check
_argt:types of Objects to check (or-ed types of admissible objects, level by level)


Returns
_-1:if the Stack was NULL or there was not enough Objects on Stack
else an error flag (0 if all arguments were OK, every bit standing as an individual
error flag for each level).


Errors
_EINVAL:if a NULL Stack was passed as argument



Function StackOut

unsigned long StackOut(Stack stk, char * out, unsigned long max, char * head, char * rowfmt, char * tail, unsigned long rows) ;
Prints the contents of a Stack, following the given formats.


Args
_stk:Stack
_out:output character string
_max:maximum number of characters to print (final nil char EXCEPTED)
_head:head string
_rowfmt:row printing format
_tail:tail string
_rows:number of rows (height in chars)


Returns
_-1:if the Stack was NULL
else the number of characters printed.
or the total number of characters that should be printed, if 'out' was NULL.


Errors
_EINVAL:if a NULL Stack was passed as argument


Note
The row format string is printed for each stack row between 0 and rows-1.
Escape sequences take the form %fdd..dd?, where the 'f' char is an optionnal
fill character (by dfault ' '), 'd' chars are digits and '?' denotes either
the 'n' or 's' characters. They are replaced by the stack row number, for the 'n'
format, and the corresponding object, for the 's' format, each written on
the number of chars denoted by the digits.



Function StackStat

unsigned long StackStat(Stack stk) ;
Prints Stack statistics on 'stdout'.


Args
_stk:Stack


Returns
_-1:if the Stack was NULL
else 0.


Errors
any error generated by the 'printf' libc call.




Variables domain definition






Function NameSpaceAlloc

NameSpace NameSpaceAlloc(unsigned long chksz) ;
Allocates an empty NameSpace.


Args
_chksz:buffer size increment


Returns
_NULL:if no memory was available
else the newly allocated NameSpace.


Errors
_ENOMEM:if no memory was available



Function NameSpaceFree

void NameSpaceFree(NameSpace nms) ;
Frees a NameSpace, dereferences and frees its contents.


Args
_nms:NameSpace to free



Function NameSpaceGet

Object NameSpaceGet(NameSpace nms, char * name) ;
Gets an elements by its key in a NameSpace.


Args
_nms:NameSpace
_name:key, or "Object name"


Returns
_NULL:if a NULL NameSpace or name was passed as argument, or no Object was known by this key
else the Object under name 'name'.


Errors
_EINVAL:if a NULL NameSpace or name was passed as argument
_ENOMEM:if no memory was available



Function NameSpaceSet

Object NameSpaceSet(NameSpace nms, char * name, Object obj) ;
Sets and references an Object under a key in a NameSpace.


Args
_nms:NameSpace
_name:key, or "Object name"
_obj:Object to set under its "name"


Returns
_NULL:if some error occurred
else the old Object under this key, if it existed (and it is then dereferenced)
or the Object passed as argument.


Errors
_EINVAL:if a NULL NameSpace, name or Object was passed as argument
_EACCES:if the NameSpace was freezed and consequently cannot receive Objects
_ENOMEM:if no memory was available



Function NameSpaceDel

Object NameSpaceDel(NameSpace nms, char * name) ;
Deletes a key and dereferences its contents in a NameSpace.


Args
_nms:NameSpace
_name:key, or "Object name"


Returns
_NULL:if a NULL NameSpace or name was passed as argument,
or the key was not found
else the Object under name 'name'.


Errors
_EINVAL:if a NULL NameSpace or name was passed as argument
_EACCES:if the NameSpace was freezed and consequently cannot yield Objects
_ENOMEM:if a disallocation failed (non-fatal error)



Function NameSpaceList

List NameSpaceList(NameSpace nms) ;
Lists all the names in a NameSpace.


Args
_nms:NameSpace


Returns
_NULL:if a NULL NameSpace was passed as argument, or the List allocation failed
else the List of all names in nms.


Errors
_EINVAL:if a NULL NameSpace or name was passed as argument
_ENOMEM:if no memory was available



Function NameSpaceOut

unsigned long NameSpaceOut(NameSpace nms, char * out, unsigned long max, char * head, char * rowfmt, char * tail) ;
Prints a NameSpace keys and contents, acording to formats.


Args
_nms:NameSpace
_out:output character string
_max:maximum number of characters to print (final nil char EXCEPTED)
_head:head string
_rowfmt:row printing format
_tail:tail string
_rows:number of rows (height in chars)


Returns
_-1:if the Stack was NULL
else the number of characters printed.
or the total number of characters that should be printed, if 'out' was NULL.


Errors
_EINVAL:if a NULL NameSpace was passed as argument


Note
The row format string is printed for each name entry in the NameSpace.
Escape sequences take the form %fdd..dd?, where the 'f' char is an optionnal
fill character (by dfault ' '), 'd' chars are digits and '?' denotes either
the 'n' or 's' characters. They are replaced by the entry name, for the 'n'
format, and the corresponding object, for the 's' format, each written on
the number of chars denoted by the digits.



Function NameSpaceStat

unsigned long NameSpaceStat(NameSpace nms) ;
Prints NameSpace statistics on 'stdout'.


Args
_nms:NameSpace


Returns
_-1:if the NameSpace was NULL
else 0.


Errors
any error generated by the 'printf' libc call.