XCLE



Object Writing routines

Instructions manual


XCLE: eXtensible Concatenative Language Engine
Copyright (C) 2000-2006 Yann LANDRIN-SCHWEITZER a.k.a. Varkhan


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@varkhan.net
Homepage: http://www.varkhan.net/


Structures and typedefs


Typedef XCLE_WriteHandler

typedef unsigned long (* XCLE_WriteHandler) (void * dat, char * chr, unsigned long len) ;
Handler for the write operation.

Note:
The programmer has the responsability to keep in the 'dat' pointer
any useful information. The handler is charged to effect the actual
writing operation on whatever support is used, and must return the
number of characters actually written, that may be less than 'len'.




Typedef XCLE_WriteFormat

typedef struct { ... } XCLE_WriteFormat ;
Data formatting information for the XCLE_*Write methods.

Members:
_ formflag: Format flags
_ intgprec: Precision (number of digits) for integers
_ intgbase: Base for printing integers
_ fltpprec: Precision (number of digits) for floating point numbers
_ fltpdeci: Decimals (digits after separ.) for floating point numbers





Writer routines for object types


Function XCLE_ObjectWrite

unsigned long XCLE_ObjectWrite(XCLE_Object obj, XCLE_WriteHandler wrt, void * dat, XCLE_WriteFormat fmt) ;
Writing method for XCLE_Object.

Args:
_ obj: XCLE_Object to write
_ wrt: handler for the real write operation
_ dat: user-set data pointer to pass the handler
_ fmt: data formatting information


Returns:
_ -1: if some error occurred
_ the total number of character needed, if 'wrt' is NULL
else the total number of characters printed


Errors:
_ EINVAL: if a NULL XCLE_Object was passed as argument
or any error generated by the 'wrt' handler.



Function XCLE_VoidWrite

unsigned long XCLE_VoidWrite(XCLE_Void vd, XCLE_WriteHandler wrt, void * dat, XCLE_WriteFormat fmt) ;
Writing method for XCLE_Void.

Args:
_ vd: XCLE_Void to write
_ wrt: handler for the real write operation
_ dat: user-set data pointer to pass the handler
_ fmt: data formatting information


Returns:
_ -1: if some error occurred
_ the total number of character needed, if 'wrt' is NULL
else the total number of characters printed


Errors:
_ EINVAL: if a NULL XCLE_Void was passed as argument
or any error generated by the 'wrt' handler.



Function XCLE_IntgWrite

unsigned long XCLE_IntgWrite(XCLE_Intg in, XCLE_WriteHandler wrt, void * dat, XCLE_WriteFormat fmt) ;
Writing method for XCLE_Intg.

Args:
_ in: XCLE_Intg to write
_ wrt: handler for the real write operation
_ dat: user-set data pointer to pass the handler
_ fmt: data formatting information


Returns:
_ -1: if some error occurred
_ the total number of character needed, if 'wrt' is NULL
else the total number of characters printed


Errors:
_ EINVAL: if a NULL XCLE_Intg was passed as argument
or any error generated by the 'wrt' handler.



Function XCLE_FltpWrite

unsigned long XCLE_FltpWrite(XCLE_Fltp fp, XCLE_WriteHandler wrt, void * dat, XCLE_WriteFormat fmt) ;
Writing method for XCLE_Fltp.

Args:
_ fp: XCLE_Fltp to write
_ wrt: handler for the real write operation
_ dat: user-set data pointer to pass the handler
_ fmt: data formatting information


Returns:
_ -1: if some error occurred
_ the total number of character needed, if 'wrt' is NULL
else the total number of characters printed


Errors:
_ EINVAL: if a NULL XCLE_Fltp was passed as argument
or any error generated by the 'wrt' handler.



Function XCLE_StrgWrite

unsigned long XCLE_StrgWrite(XCLE_Strg str, XCLE_WriteHandler wrt, void * dat, XCLE_WriteFormat fmt) ;
Writing method for XCLE_Strg.

Args:
_ str: XCLE_Strg to write
_ wrt: handler for the real write operation
_ dat: user-set data pointer to pass the handler
_ fmt: data formatting information


Returns:
_ -1: if some error occurred
_ the total number of character needed, if 'wrt' is NULL
else the total number of characters printed


Errors:
_ EINVAL: if a NULL XCLE_Strg was passed as argument
or any error generated by the 'wrt' handler.



Function XCLE_ListWrite

unsigned long XCLE_ListWrite(XCLE_List lst, XCLE_WriteHandler wrt, void * dat, XCLE_WriteFormat fmt) ;
Writing method for XCLE_List.

Args:
_ lst: XCLE_List to write
_ wrt: handler for the real write operation
_ dat: user-set data pointer to pass the handler
_ fmt: data formatting information


Returns:
_ -1: if some error occurred
_ the total number of character needed, if 'wrt' is NULL
else the total number of characters printed


Errors:
_ EINVAL: if a NULL XCLE_List was passed as argument
or any error generated by the 'wrt' handler.



Function XCLE_CodeWrite

unsigned long XCLE_CodeWrite(XCLE_Code cod, XCLE_WriteHandler wrt, void * dat, XCLE_WriteFormat fmt) ;
Writing method for XCLE_Code.

Args:
_ cod: XCLE_Code to write
_ wrt: handler for the real write operation
_ dat: user-set data pointer to pass the handler
_ fmt: data formatting information


Returns:
_ -1: if some error occurred
_ the total number of character needed, if 'wrt' is NULL
else the total number of characters printed


Errors:
_ EINVAL: if a NULL XCLE_Code was passed as argument
or any error generated by the 'wrt' handler.




Writer routines for execution context objects


Function XCLE_StackWrite

unsigned long XCLE_StackWrite(XCLE_Stack stk, XCLE_WriteHandler wrt, void * dat, XCLE_WriteFormat fmt, char * head, char * rowf, char * tail, unsigned long rown) ;
Writing method for XCLE_Code.

Args:
_ stk: XCLE_Stack to write
_ wrt: handler for the real write operation
_ dat: user-set data pointer to pass the handler
_ fmt: data formatting information
_ head: header line
_ rowf: row format line
_ tail: tailer line
_ rown: number of rows to write


Returns:
_ -1: if some error occurred
_ the total number of character needed, if 'wrt' is NULL
else the total number of characters printed


Errors:
_ EINVAL: if a NULL XCLE_Stack, or an invalid format string, was passed as argument
or any error generated by the 'wrt' handler.

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




Function XCLE_HashWrite

unsigned long XCLE_HashWrite(XCLE_Stack stk, XCLE_WriteHandler wrt, void * dat, XCLE_WriteFormat fmt, char * head, char * rowf, char * tail) ;
Writing method for XCLE_Code.

Args:
_ stk: XCLE_Stack to write
_ wrt: handler for the real write operation
_ dat: user-set data pointer to pass the handler
_ fmt: data formatting information
_ head: header line
_ rowf: row format line
_ tail: tailer line


Returns:
_ -1: if some error occurred
_ the total number of character needed, if 'wrt' is NULL
else the total number of characters printed


Errors:
_ EINVAL: if a NULL XCLE_Stack, or an invalid format string, was passed as argument
or any error generated by the 'wrt' handler.

Note:
The row format string is printed for each key in the Hash.
Escape sequences take the form %pdd..dd?, where the 'p' char is an optionnal
padding character (by default ' '), 'd' chars are digits and '?' denotes either
the 'n' or 's' characters. They are replaced by the sh key, for the 'n' format
specifier, and the corresponding object, for the 's' format, each written on the
number of chars denoted by the digits.




Generated by textdoc2html - 2006-02-22