XCLE_Mod

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/

Return status management

Macro XCLE_EXCEPTION_OK

XCLE_Exception XCLE_EXCEPTION_OK ;
The Exception returned when execution was successful.

	Note:
		The comparison operator == can be used to test whether an XCLE_Exception
		is the same as XCLE_EXCEPTION_OK (since this is a static pointer value).

Function XCLE_ExceptionNew

XCLE_Exception XCLE_ExceptionNew(unsigned long ident, char * messg) ;
Creates a new XCLE_Exception with the specified error number, exception identifier, and message.

Args:
	_ ident	: error identifier number
	_ messg	: description of the error

Returns:
	_ NULL	: if the memory could not be allocated
	_ XCLE_EXCEPTION_OK	: XCLE_ExceptionNew(0,NULL)
	else a new XCLE_Exception.

	Errors:
		_ ENOMEM	: if new memory could not be allocated

Function XCLE_ExceptionCopy

XCLE_Exception XCLE_ExceptionCopy(XCLE_Exception exp) ;
Creates a memory copy of the given exception.

	Args:
		_ exp	: the original exception

Returns:
	_ NULL	: if the memory could not be allocated
	_ XCLE_EXCEPTION_OK	: if XCLE_EXCEPTION_OK was passed as argument
	else a new XCLE_Exception.

Errors:
	_ ENOMEM	: if new memory could not be allocated
	_ EINVAL	: if a NULL XCLE_Exception was passed as argument

Function XCLE_ExceptionIdent

unsigned long XCLE_ExceptionIdent(XCLE_Exception exp) ;
Returns the error identifier of an exception.

	Args:
		_ exp	: the exception

Returns:
	_ -1	: if a NULL XCLE_Exception was passed as argument
	_ 0	: if XCLE_EXCEPTION_OK was passed as argument
	else the exception's error identifier

	Errors:
		_ EINVAL	: if a NULL XCLE_Exception was passed as argument

Function XCLE_ExceptionMessg

const char * XCLE_ExceptionMessg(XCLE_Exception exp) ;
Returns the message string of an exception.

	Args:
		_ exp	: the exception

Returns:
	_ NULL	: if a NULL XCLE_Exception was passed as argument
	_ ""	: if XCLE_EXCEPTION_OK was passed as argument
	else the exception's message string

	Errors:
		_ EINVAL	: if a NULL XCLE_Exception was passed as argument

Function XCLE_ExceptionFree

void XCLE_ExceptionFree(XCLE_Exception exp) ;
Frees an XCLE_Exception.

	Args:
		_ exp	: XCLE_Exception to free

	Note:
		Freeing XCLE_EXCEPTION_OK using XCLE_ExceptionFree does nothing

Function XCLE_ExecCtxAlloc

XCLE_ExecCtx XCLE_ExecCtxAlloc(unsigned long chksz) ;
Allocates an execution context.

	Args:
		_ chksz	: the chunk size used for the exception stack

Returns:
	_ NULL	: if the memory could not be allocated
	else a new, empty, execution context.

	Errors:
		_ ENOMEM	: if new memory could not be allocated

Function XCLE_ExecCtxFree

void XCLE_ExecCtxFree(XCLE_ExecCtx ctx) ;
Frees an execution context, along any eventual pending exception.

	Args:
		_ ctx	: the execution context to free

Function XCLE_ExecCtxThrow

XCLE_ExecCtx XCLE_ExecCtxThrow(XCLE_ExecCtx ctx, char * src, XCLE_Exception exp) ;
Throws an exception in this context.

Args:
	_ ctx	: the execution context
	_ src	: the name of the calling code
	_ exp	: the exception to throw

Returns:
	_ NULL	: if 'ctx', 'src', or 'exp' were NULL
	else the original context, with the exception added to the pending queue

Errors:
	_ ENOMEM	: if new memory could not be allocated
	_ EINVAL	: if 'ctx', 'src', or 'exp' were NULL

	Note:
		Nothing is done if exp is XCLE_EXCEPTION_OK.

Function XCLE_ExecCtxCatch

XCLE_Exception XCLE_ExecCtxCatch(XCLE_ExecCtx ctx) ;
Catches the last thrown exception.

	Args:
		_ ctx	: the execution context

Returns:
	_ NULL	: if the execution context was NULL
	_ XCLE_EXCEPTION_OK	: if no exception was pending in this context
	else the last thrown exception

	Errors:
		_ EINVAL	: if the execution context was NULL

Function XCLE_ExecCtxClear

XCLE_ExecCtx XCLE_ExecCtxClear(XCLE_ExecCtx ctx) ;
Clears all pending exceptions in this context.

	Args:
		_ ctx	: the execution context

Returns:
	_ NULL	: if the execution context was NULL
	else the original execution context

	Errors:
		_ EINVAL	: if the execution context was NULL

Function XCLE_ExecCtxMapExceptions

unsigned long XCLE_ExecCtxMapExceptions(XCLE_ExecCtx ctx, , void * dat) ;
Maps all pending exceptions in an execution context (e.g. for displaying).

Args:
	_ ctx	: the execution context
	_ map	: the mapping handler
	_ dat	: user-data pointer

Returns:
	_ NULL	: if the execution context or the map handler were NULL
	else the sum of all values returned by 'map'

	Errors:
		_ EINVAL	: if the execution context or the map handler were NULL

Note:
	The map handler takes, in order, the informations pertaining to the exception's
	calling code, and the exception nature:
	_ lev	: the depth of the currently mapped exception (0 for the root exception)
	_ src	: the name of the calling code
	_ idt	: the exception's identification number
	_ msg	: the exception's description
	_ dat	: user-defined data pointer (the last argument of XCLE_ExecCtxMapExceptions)

Typedef XCLE_CodeOperator

typedef XCLE_Exception (* XCLE_CodeOperator) (XCLE_ExecCtx, XCLE_Stack, XCLE_Hash, XCLE_Object) ;
The type of the handler segment of Code objects for them to be compatible with this module.

Object evaluation

Function XCLE_ObjectEval

XCLE_Exception XCLE_ObjectEval(XCLE_ExecCtx ctx, XCLE_Stack stk, XCLE_Hash hsh, XCLE_Object obj) ;
Evaluates an XCLE_Object.

Args:
	_ ctx	: execution context
	_ stk	: Stack environment
	_ dom	: Variables environment
	_ obj	: Object to execute

Returns:
	_ NULL	: if a NULL Stack, Hash or Object was passed as argument
	_ XCLE_EXCEPTION_OK	: if the execution terminated normally
	else the last exception thrown in this context.

	Errors:
		_ EINVAL	: if a NULL Stack, Hash or Object was passed as argument

Function XCLE_ListEval

XCLE_Exception XCLE_ListEval(XCLE_ExecCtx ctx, XCLE_Stack stk, XCLE_Hash hsh, XCLE_List lst) ;
Evaluates an XCLE_List.

Args:
	_ ctx	: execution context
	_ stk	: Stack environment
	_ dom	: Variables environment
	_ lst	: list to execute

Returns:
	_ NULL	: if a NULL Stack, Hash or Object was passed as argument
	_ XCLE_EXCEPTION_OK	: if the execution terminated normally
	else the last exception thrown in this context.

	Errors:
		_ EINVAL	: if a NULL Stack, Hash or Object was passed as argument

Function XCLE_CodeEval

XCLE_Exception XCLE_CodeEval(XCLE_ExecCtx ctx, XCLE_Stack stk, XCLE_Hash hsh, XCLE_Code cod) ;
Evaluates an XCLE_Code object.

Args:
	_ ctx	: execution context
	_ stk	: Stack environment
	_ dom	: Variables environment
	_ cod	: code to execute

Returns:
	_ NULL	: if a NULL Stack, Hash or Object was passed as argument
	_ XCLE_EXCEPTION_OK	: if the execution terminated normally
	else the last exception thrown in this context.

	Errors:
		_ EINVAL	: if a NULL Stack, Hash or Object was passed as argument

Generated by textdoc2html - 2006-02-22