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/

Signature structure definition and memory management

Function XCLE_SignatureAlloc

XCLE_Signature XCLE_SignatureAlloc() ;
Creates a new XCLE_Signature object.

Returns:
	_ NULL	: if memory allocation could not be performed
	a new XCLE_Signature object..

	Errors:
		_ ENOMEM	: if no memory was available

Function XCLE_SignatureCopy

XCLE_Signature XCLE_SignatureCopy(XCLE_Signature sig) ;
Copies data from an XCLE_Signature.

	Args:
		_ sig	: the original object to copy

Returns:
	_ NULL	: if no memory was available or an invalid signature was passed as argument
	a complete copy of the 'sig' object.

Errors:
	_ EINVAL	: if 'sig' was NULL or invalid
	_ ENOMEM	: if no memory was available

Function XCLE_SignatureFree

void XCLE_SignatureFree(XCLE_Signature sig) ;
Frees an XCLE_Signature.

	Args:
		_ sig	: XCLE_Signature to free

Signature object accessors

Function XCLE_SignatureNum

unsigned short XCLE_SignatureNum(XCLE_Signature sig) ;
Returns the number of signatures registered in the argument.

	Args:
		_ sig	: the XCLE_Signature object to query

Returns:
	_ -1	: if an invalid signature was passed as argument
	the number of signatures in 'sig'.

	Errors:
		_ EINVAL	: if 'sig' was NULL or invalid

Function XCLE_SignatureArgc

unsigned short XCLE_SignatureArgc(XCLE_Signature sig, unsigned short sign) ;
Returns the number of arguments for a specific signature in an XCLE_Signature.

Args:
	_ sig	: the XCLE_Signature object to query
	_ sign	: the index number of the signature

Returns:
	_ -1	: if an error occured
	the number of arguments for the signature at index 'sign'.

	Errors:
		_ EINVAL	: if 'sig' was NULL or invalid, or 'sign' was greater than the number of signatures in 'sig'

Function XCLE_SignatureRetc

unsigned short XCLE_SignatureRetc(XCLE_Signature sig, unsigned short sign) ;
Returns the number of returns for a specific signature in an XCLE_Signature.

Args:
	_ sig	: the XCLE_Signature object to query
	_ sign	: the index number of the signature

Returns:
	_ -1	: if an error occured
	the number of returns for the signature at index 'sign'.

	Errors:
		_ EINVAL	: if 'sig' was NULL or invalid, or 'sign' was greater than the number of signatures in 'sig'

Function XCLE_SignatureArgt

XCLE_Type XCLE_SignatureArgt(XCLE_Signature sig, unsigned short sign, unsigned short argn) ;
Returns the type of an argument for a specific signature in an XCLE_Signature.

Args:
	_ sig	: the XCLE_Signature object to query
	_ sign	: the index number of the signature
	_ argn	: the index number of the argument

Returns:
	_ -1	: if an error occured
	the type of the 'argn'th argument for the signature at index 'sign'.

	Errors:
		_ EINVAL	: if 'sig' was NULL or invalid, or 'sign' was greater than the number of signatures in 'sig', or 'argn' was greater than the number of arguments for this signature

Function XCLE_SignatureRett

XCLE_Type XCLE_SignatureRett(XCLE_Signature sig, unsigned short sign, unsigned short retn) ;
Returns the type of a return for a specific signature in an XCLE_Signature.

Args:
	_ sig	: the XCLE_Signature object to query
	_ sign	: the index number of the signature
	_ retn	: the index number of the return

Returns:
	_ -1	: if an error occured
	the type of the 'retn'th return for the signature at index 'sign'.

	Errors:
		_ EINVAL	: if 'sig' was NULL or invalid, or 'sign' was greater than the number of signatures in 'sig', or 'argn' was greater than the number of arguments for this signature

Signature constructors / content management

Function XCLE_SignatureExtract

XCLE_Signature XCLE_SignatureExtract(XCLE_Code cod) ;
Extracts the signatures from an XCLE_Code object.

	Args:
		_ cod	: XCLE_Code object to query

Returns:
	_ NULL	: if no memory was available, or the XCLE_Code object was NULL or invalid
	the signatures contained in 'cod'.

Errors:
	_ ENOMEM	: if no memory was available
	_ EINVAL	: if 'cod' was NULL or invalid

Function XCLE_SignatureAdd

unsigned short XCLE_SignatureAdd(XCLE_Signature sig, unsigned short argc, XCLE_Type * argt, unsigned short retc, XCLE_Type * rett) ;
Adds a signature to an XCLE_Signature.

Args:
	_ sig	: XCLE_Signature to modify
	_ argc	: number of arguments
	_ argt	: number of returns
	_ retc	: argument types list
	_ rett	: returns types list

Returns:
	_ -1	: if an error occured
	the modified 'sig' object.

Errors:
	_ ENOMEM	: if no memory was available
	_ EINVAL	: if 'sig' was NULL or invalid

	Note:
		Upon allocation with XCLE_SignatureAlloc, an XCLE_Signature starts with no registered
		signature. As such, it will mean literally 'accepts no argument configuration, does not
		return', i.e. something that can not be executed. XCLE_SignatureAdd must be used at least
		once to make an XCLE_Signature usable. It can be used several times, meaning several
		input/output configurations are acceptable.

Function XCLE_SignatureMatch

unsigned short XCLE_SignatureMatch(XCLE_Signature sig, unsigned short argc, XCLE_Type * argt, unsigned short retc, XCLE_Type * rett) ;
Searches for a signature matching exactly the given argument and return types and numbers.

Args:
	_ sig	: XCLE_Signature to test
	_ argc	: number of arguments
	_ argt	: number of returns
	_ retc	: types of arguments
	_ rett	: types of returns

Returns:
	_ -1	: if an argument was invalid
	the index of a matching signature in 'sig'.

	Errors:
		_ EINVAL	: if 'sig' was NULL or invalid

	Note:
		XCLE_SignatureMatch is exactly looking for the index of a signature added using
		XCLE_SignatureAdd with the same 'argc', 'argt', 'retc' and 'rett' arguments values.

Function XCLE_SignatureDel

unsigned short XCLE_SignatureDel(XCLE_Signature sig, unsigned short sign) ;
Deletes a signature from an XCLE_Signature.

Args:
	_ sig	: XCLE_Signature to modify
	_ sign	: index number of the signature to delete

Returns:
	_ -1	: if an argument was invalid
	the modified 'sig' argument.

	Errors:
		_ EINVAL	: if 'sig' was NULL or invalid

	Note:
		This deletes one signature from the list, changing the index numbers of other
		signatures. XCLE_SignatureDel thus invalidates any previous signature index
		obtained from 'sig' with the XCLE_SignatureMatch function, and decreases of 1
		the return value of XCLE_SignatureNum.

Signature String conversion and printing

Function XCLE_SignatureToString

unsigned long XCLE_SignatureToString(XCLE_Signature sig, char * out, unsigned long len) ;
Produces a character string representation of an XCLE_Signature.

Args:
	_ sig	: XCLE_Signature to display
	_ out	: output character buffer, of size at least 'len'
	_ len	: maximum number of characters to write

Returns:
	_ -1	: if an argument was invalid
	the maximum number of characters needed to write completely the XCLE_Signature if 'out' is NULL, otherwise the number of characters written in 'out'.

	Errors:
		_ EINVAL	: if 'sig' was NULL or invalid

Function XCLE_SignatureWrite

unsigned long XCLE_SignatureWrite(XCLE_Signature sig, XCLE_WriteHandler wrt, void * dat, XCLE_WriteFormat fmt) ;
Writing method for an XCLE_Signature.

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

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

Errors:
	_ EINVAL	: if a NULL XCLE_Signature was passed as argument
	_ ENOMEM	: if no memory was available
	or any error generated by the 'wrt' handler

	Note:
		See [XCLE_Mod_write] for details on the XCLE_WriteHandler and XCLE_WriteFormat types.

Function XCLE_SignaturePrint

unsigned long XCLE_SignaturePrint(XCLE_Signature sig, int fd) ;
Prints an XCLE_Signature on a file descriptor.

Args:
	_ sig	: XCLE_Signature to print
	_ fd	: file descriptor

Returns:
	_ -1	: if an argument was invalid, or a write error occured
	else the number of characters written on 'fd'.

Errors:
	_ EINVAL	: if 'sig' was NULL or invalid
	_ any error generated by the 'write' system call on 'fd'

Function XCLE_SignatureFPrint

unsigned long XCLE_SignatureFPrint(XCLE_Signature sig, FILE * os) ;
Prints an XCLE_Signature on a stream.

Args:
	_ sig	: XCLE_Signature to print
	_ os	: output stream

Returns:
	_ -1	: if an argument was invalid, or a write error occured
	else the number of characters written on 'os'.

Errors:
	_ EINVAL	: if 'sig' was NULL or invalid
	_ any error generated by the 'fwrite' system call on 'os'

Signature high-level API

Function XCLE_SignatureIsSub

unsigned short XCLE_SignatureIsSub(XCLE_Signature sg1, XCLE_Signature sg2) ;
Determines if an XCLE_Signature is a subset of another.

Args:
	_ sg1	: candidate-subset XCLE_Signature
	_ sg2	: candidate-superset XCLE_Signature

Returns:
	_ -1	: if an argument was invalid
	_ 0	: if some signatures in 'sg1' were not in 'sg2'
	_ 1	: if ALL signatures in 'sg1' were also in 'sg2'

	Errors:
		_ EINVAL	: if 'sg1' or 'sg2' were NULL or invalid

	Note:
		XCLE_SignatureIsSub is a partial order relation: XCLE_SignatureIsSub(sg1,sg2)==0 does not mean XCLE_SignatureIsSub(sg2,sg1)==1. The reverse is true, however, except when 'sg1' and 'sg2' are equal. When comparing type specifications, a type mask is a subset of another if any non-zero bit in the first one is also non-zero in the second one.

Function XCLE_SignatureEqual

unsigned short XCLE_SignatureEqual(XCLE_Signature sg1, XCLE_Signature sg2) ;
Tests the equality between two XCLE_Signature objects.

Args:
	_ sg1	: first XCLE_Signature to test
	_ sg2	: second XCLE_Signature to test

Returns:
	_ 0	: if only one argument was NULL, or the argument differed
	_ 1	: if both 'sg1' and 'sg2' were NULL, or they were equal

	Note:
		Testing equality for XCLE_Signature objects means ensuring that every signature found in 'sg1' is also in 'sg2', and vice-versa. This means strict equality, and matching but not equal type masks count as distinct.

Function XCLE_SignatureCompat

unsigned short XCLE_SignatureCompat(XCLE_Signature sg1, XCLE_Signature sg2) ;
Tests for compatibility between signatures in XCLE_Signature objects.

Args:
	_ sg1	: first XCLE_Signature
	_ sg2	: second XCLE_Signature

Returns:
	_ -1	: if one of the arguments was NULL or invalid
	_ 0	: if 'sg2' is not compatible with 'sg1'
	_ 1	: if one argument signature in 'sg2' was compatible with one return signature in 'sg1'

Errors:
	_ EINVAL	: if 'sg1' or 'sg2' were NULL or invalid
	_ ENOMEM	: if no memory was available

	Note:
		Compatibility of 'sg2' with 'sg1' means than at least one signature in 'sg1' is compatible with at least one signature in 'sg2', i.e. a signature in 'sg1' which asks for, either:.
		_ less arguments than a counterpart in 'sg1', and that all argument types match return types in that signature
		_ more arguments than a counterpart in 'sg1', and that all return types match argument types in this signature
		In both cases, overflow types (types that are in a position bigger than the smaller of the argument and return counts) are ignored.

Function XCLE_SignatureChain

XCLE_Signature XCLE_SignatureChain(XCLE_Signature sg1, XCLE_Signature sg2) ;
Computes the resulting signatures when chaining XCLE_Signature objects.

Args:
	_ sg1	: first XCLE_Signature
	_ sg2	: second XCLE_Signature

Returns:
	_ NULL	: if an error occured
	else .

Errors:
	_ EINVAL	: if 'sg1' or 'sg2' were NULL or invalid
	_ ENOMEM	: if no memory was available

	Note:
		Chaining two signatures meaning keeping only compatible couples of signatures in 'sg1' and 'sg2', and discarding matching return sections in 'sg1' signatures, and argument sections in 'sg2' signatures. Overflow arguments from 'sg2' are added to argument signatures in the results, and overflow returns from 'sg1' are added to retrurn signatures in the results.

Function XCLE_SignatureCompute

XCLE_Signature XCLE_SignatureCompute(XCLE_List lst) ;
Computes the global signatures of the elements of an XCLE_List.

	Args:
		_ lst	: XCLE_List to profile

Returns:
	_ NULL	: if an error occured
	else the chain of all extracted signatures from elements in 'lst'.

Errors:
	_ EINVAL	: if 'lst' was NULL or invalid
	_ ENOMEM	: if no memory was available

	Note:
		Each element in the list is converted into a signature. All types except XCLE_Code have a signle signature, taking no argument and returning that type. Signatures are extracted from XCLE_Code object using XCLE_SignatureExtract. The chain is then computed from the left onward, in associative manner.

Generated by textdoc2html - 2006-04-10