libnaru: naru.h File Reference

Go to the source code of this file.


Defines
#define	nu_Scope_NULL -1
	no scope (NULL)
#define	nu_TypeId_NULL -1
	no type (NULL)
Typedefs
typedef int	nu_Scope
	A scope handle.
typedef struct nu_TypeSystemStruct *	nu_TypeSystem
	The type system object.
typedef int	nu_TypeId
	Id of a type.
Enumerations
enum	nu_ErrorCode { NU_OK = 0, NU_ERROR_NOMEM = 1, NU_ERROR_CONFLICT_RULE = 2, NU_ERROR_CONFLICT_DECISION = 3, NU_ERROR_CONFLICT_DUPLICATE_DEF = 4, NU_ERROR_SYNTAX = 5 }
	Possible error codes of libnaru. More...
Functions
nu_TypeSystem	nu_createTypeSystem (void)
	Constructor of a type system.
void	nu_destroyTypeSystem (nu_TypeSystem ts)
	Destructor of a type system.
nu_Scope	nu_beginScope (nu_TypeSystem ts)
	Declare the start of a new scope (open bracket). Returns Scope_NULL in case of failure, the built scope in case of success.
nu_Scope	nu_declareScope (nu_TypeSystem ts)
	Declare a declaration step in the current scope. This is done to define an order of declarations in the scope. Something declared with a following declareScope is accessible for following declaration in the same scope, but not vice versa.
int	nu_endScope (nu_TypeSystem ts)
	Declare the end of a scope 'scope' (close bracket).
int	nu_cmpScope (nu_TypeSystem ts, nu_Scope A, nu_Scope B)
	Compares two scopes. Decides wheter A covers B or B covers A or wheter they are disjunct.
int	nu_sameScope (nu_TypeSystem ts, nu_Scope A, nu_Scope B)
	Test two scopes to be the same. They are considered to be the same if opened with the same 'beginScope' action. Scopes derived from it with 'declareScope' are also considered to be the same.
int	nu_scopeId (nu_TypeSystem ts, nu_Scope scope)
	Returns an identifier for a scope unique for all declarations in the same scope.
nu_TypeId	nu_declareType (nu_TypeSystem ts, nu_Scope scope, const char id, uintptr_t tc, uintptr_t tcarg, nu_ErrorCode errcode)
	Declares a type identified by 'id' in the scope 'scope'. With tc/tcarg you declare how a result is built when this type has been used in a resolve expression query. It is part of the constructor of a resolved expression.
nu_TypeId	nu_getType (nu_TypeSystem ts, nu_Scope scope, const char *id)
	Find the type and its constructor identified by 'id' in the scope 'scope'.
char *	nu_getTypeName (nu_TypeSystem ts, nu_TypeId type)
	Returns the name of the type as passed with parameter 'id' when declaring the type with 'declareType'.
uintptr_t	nu_getTypeConstructor (nu_TypeSystem ts, nu_TypeId type, uintptr_t *tcarg)
	Returns the constructor of the type as passed with parameter 'tc' when declaring the type with 'declareType'.
int	nu_declareRule (nu_TypeSystem ts, nu_Scope scope, nu_TypeId src, nu_TypeId dest, unsigned int cstord, unsigned int cst, uintptr_t tc, uintptr_t tcarg, nu_ErrorCode *errcode)
	Declares a rule to deduce the type 'dest' from 'src' with the costs 'cstord/cst' and a constructor. The value of the type 'dest' after applying the rule can be built, when iterating through the result of a resolved expression. With tc/tcarg you declare how a result is built when this rule has been applied when resolving an expression. It is part of the constructor of a resolved expression.
int	nu_declareExpression (nu_TypeSystem ts, nu_Scope scope, unsigned int nof_tps, nu_TypeId tps, nu_TypeId restype, uintptr_t tc, uintptr_t tcarg, nu_ErrorCode errcode)
	Declares an expression as tuple of types that evaluates to the type 'restype'. The value of the expression can be built when iterating through the result of a 'resolveExpression'.
nu_TypeId	nu_getExpressionType (nu_TypeSystem ts, nu_Scope scope, unsigned int nof_tps, nu_TypeId tps, uintptr_t tc, uintptr_t *tcarg)
	Finds the expression adressed by 'tps[]' declared in a scope containing the scope 'scope' that is an exact match. So no rules are involved and there is no result constructed. This function is needed for implementing concepts. Concepts are sets of conditions that an object must meet in order to be of a certain type.
int	nu_resolveExpression (nu_TypeSystem ts, nu_Scope scope, unsigned int nof_tps, nu_TypeId tps, nu_TypeId resulttype, nu_ErrorCode *errcode)
	Finds the expression adressed by 'tps[]' declared in a scope containing the scope 'scope' that is the nearest in the evaluation path. Nearest means that the expression found by applying rules to elements in the tuple 'tps' (the unifier of the query expression and the defined expression) has the minimal sum of costs of all matching expressions and their rule evaluation paths.
int	nu_getRuleConflict (nu_TypeSystem ts, nu_TypeId path1, nu_TypeId path2)
	Get both deduction paths of the conflicts when nu_resolveExpression returned errcode=NU_ERROR_CONFLICT_RULE in the last call. path1[] and path2[] are TypeId_NULL terminated.
int	nu_getDecisionConflict (nu_TypeSystem ts, nu_TypeId expr1, nu_TypeId expr2)
	Get both conflicting expressions when nu_resolveExpression returned errcode=NU_ERROR_CONFLICT_DECISION in the last call. expr1[] and expr2[] are TypeId_NULL terminated.
int	nu_getElementConstructor (nu_TypeSystem ts, int result_handle, unsigned int tps_idx, int iter, uintptr_t tc, uintptr_t tcarg)
	Function to iterate through a result of 'resolveExpression'. 'iter' is starting with 0, and incremented until -1 is returned. Gets the constructors of the element unifiers. The function returns the constructor 'tc' of a type or rule declared with 'declareType' or 'declareRule'. It returns also the arguments of the constructor functor 'tc' in 'tcarg'. The expression element result is constructed by applying the constructors got with this function in the ascending order of 'iter' starting with 0.
int	nu_getResultConstructor (nu_TypeSystem ts, int result_handle, uintptr_t tc, uintptr_t tcarg)
	Get the constructor of the expression of the last result of 'resolveExpression'. The value of the expression can be constructed by applying the constructor functor on the elements built from the result of 'getElementConstructor'. Returns -1 when the result handle passed is invalid.
void	nu_clearResultBuffer (nu_TypeSystem ts)
	Clear the result buffer. The handles of results will counted again from 0.

Define Documentation

#define nu_Scope_NULL -1

no scope (NULL)

Definition at line 65 of file naru.h.

#define nu_TypeId_NULL -1

no type (NULL)

Definition at line 80 of file naru.h.

Typedef Documentation

typedef int nu_Scope

A scope handle.

Definition at line 60 of file naru.h.

typedef int nu_TypeId

Id of a type.

Definition at line 75 of file naru.h.

typedef struct nu_TypeSystemStruct* nu_TypeSystem

The type system object.

Definition at line 70 of file naru.h.

Enumeration Type Documentation

enum nu_ErrorCode

Possible error codes of libnaru.

Enumerator:

NU_OK	no error
NU_ERROR_NOMEM	run out of memory
NU_ERROR_CONFLICT_RULE	there exist two unifiers of types with the same sum of costs of the rules applied
NU_ERROR_CONFLICT_DECISION	there are two expressions defined having unifiers of the searched expression with equal costs
NU_ERROR_CONFLICT_DUPLICATE_DEF	duplicate definition (in the same scope in case of types or expressions or in comparable scopes in case of rules)
NU_ERROR_SYNTAX	illegal input

Definition at line 85 of file naru.h.

Function Documentation

nu_Scope nu_beginScope ( nu_TypeSystem ts )

Declare the start of a new scope (open bracket). Returns Scope_NULL in case of failure, the built scope in case of success.

Parameters:

type system

Returns:: valid scope identifier of Scope_NUlL, if a memory allocation error occurred.

void nu_clearResultBuffer ( nu_TypeSystem ts )

Clear the result buffer. The handles of results will counted again from 0.

Parameters:

type system

int nu_cmpScope	(	nu_TypeSystem	ts,
		nu_Scope	A,
		nu_Scope	B
	)

Compares two scopes. Decides wheter A covers B or B covers A or wheter they are disjunct.

Parameters:

	ts	type system
	A	scope identifier declared in ts.
	B	scope identifier declared in ts.

Returns:: +1, if A covers B or A and B are equal, -1, if B covers A and they are not equal, 0, if not comparable (disjunct)

nu_TypeSystem nu_createTypeSystem ( void )

Constructor of a type system.

int nu_declareExpression	(	nu_TypeSystem	ts,
		nu_Scope	scope,
		unsigned int	nof_tps,
		nu_TypeId *	tps,
		nu_TypeId	restype,
		uintptr_t	tc,
		uintptr_t	tcarg,
		nu_ErrorCode *	errcode
	)

Declares an expression as tuple of types that evaluates to the type 'restype'. The value of the expression can be built when iterating through the result of a 'resolveExpression'.

Parameters:

	ts	type system
	scope	scope identifier declared in ts. The scope of the declared expression.
	nof_tps	number of elements in tps[]
	tps	array of types defining the expression as tuple of types.
	restype	the result type of the expression
	tc	type constructor function identifier of this expression.
	tcarg	type constructor function argument identifier of this expression
	errcode	possible error returned in case of failure (0 returned)

Returns:: -1 in case of error, and something >= 0 in case of success.

int nu_declareRule	(	nu_TypeSystem	ts,
		nu_Scope	scope,
		nu_TypeId	src,
		nu_TypeId	dest,
		unsigned int	cstord,
		unsigned int	cst,
		uintptr_t	tc,
		uintptr_t	tcarg,
		nu_ErrorCode *	errcode
	)

Declares a rule to deduce the type 'dest' from 'src' with the costs 'cstord/cst' and a constructor. The value of the type 'dest' after applying the rule can be built, when iterating through the result of a resolved expression. With tc/tcarg you declare how a result is built when this rule has been applied when resolving an expression. It is part of the constructor of a resolved expression.

Parameters:

	ts	type system
	scope	scope identifier declared in ts. The scope of the declared rule.
	src	type identifier declared in ts. The type this deduction rule is applied on.
	dest	type identifier declared in ts. The type this deduction rule results in.
	cstord	number between 0..3 meaning the order of costs. Costs can have different order. A sum of costs of higher order is allways bigger than any sum of costs of lower order.
	cst	costs of the rule. The costs are part of the costs of a unifier of two expressions. The summation of all costs of the rules used in the unifier is used to decide what is the matching expression and its unifier when calling 'resolveExpression'. It is the expression that has the unifier with minimal sum of costs.
	tc	type constructor function identifier of this rule.
	tcarg	type constructor function argument identifier of this rule
	errcode	possible error returned in case of failure (0 returned)

Returns:: 0 in case of error, and 1 in case of success.

nu_Scope nu_declareScope ( nu_TypeSystem ts )

Declare a declaration step in the current scope. This is done to define an order of declarations in the scope. Something declared with a following declareScope is accessible for following declaration in the same scope, but not vice versa.

Parameters:

type system

Returns:: valid scope identifier of Scope_NUlL, if a memory allocation error occurred or no scope is open (anymore).

nu_TypeId nu_declareType	(	nu_TypeSystem	ts,
		nu_Scope	scope,
		const char *	id,
		uintptr_t	tc,
		uintptr_t	tcarg,
		nu_ErrorCode *	errcode
	)

Declares a type identified by 'id' in the scope 'scope'. With tc/tcarg you declare how a result is built when this type has been used in a resolve expression query. It is part of the constructor of a resolved expression.

Parameters:

	ts	type system
	scope	scope identifier declared in ts. The scope of the declared type.
	id	identifier of the declared type
	tc	type constructor function identifier
	tcarg	type constructor function argument identifier
	errcode	possible error returned in case of failure (TypeId_NULL returned)

Returns:: nu_TypeId of the declared type or TypeId_NULL in case of failure

void nu_destroyTypeSystem ( nu_TypeSystem ts )

Destructor of a type system.

int nu_endScope ( nu_TypeSystem ts )

Declare the end of a scope 'scope' (close bracket).

Parameters:

type system

Returns:: 0 in case of failure, 1 in case of success.

int nu_getDecisionConflict	(	nu_TypeSystem	ts,
		nu_TypeId **	expr1,
		nu_TypeId **	expr2
	)

Get both conflicting expressions when nu_resolveExpression returned errcode=NU_ERROR_CONFLICT_DECISION in the last call. expr1[] and expr2[] are TypeId_NULL terminated.

Parameters:

	ts	type system
	expr1[]	returned conflicting expression 1
	expr2[]	returned conflicting expression 2

Returns:: 0, if there has been no decision conflict registered, 1 on success

int nu_getElementConstructor	(	nu_TypeSystem	ts,
		int	result_handle,
		unsigned int	tps_idx,
		int	iter,
		uintptr_t *	tc,
		uintptr_t *	tcarg
	)

Function to iterate through a result of 'resolveExpression'. 'iter' is starting with 0, and incremented until -1 is returned. Gets the constructors of the element unifiers. The function returns the constructor 'tc' of a type or rule declared with 'declareType' or 'declareRule'. It returns also the arguments of the constructor functor 'tc' in 'tcarg'. The expression element result is constructed by applying the constructors got with this function in the ascending order of 'iter' starting with 0.

Parameters:

	ts	type system
	result_handle	handle of the result got as return value of 'resolveExpression'.
	tps_idx	which element of the query structure to build.
	iter	iterator to visit all element constructors of the query structure element unifier.
	tc	returned type constructor function identifier of the query structure element unifier.
	tcarg	returned type constructor function argument identifier of the query structure element unifier

Returns:: The next value to pass as 'iter' for the subsequent call of this function, -1 when there is no constructor left for result_handle[tps_idx] at 'iter'.

nu_TypeId nu_getExpressionType	(	nu_TypeSystem	ts,
		nu_Scope	scope,
		unsigned int	nof_tps,
		nu_TypeId *	tps,
		uintptr_t *	tc,
		uintptr_t *	tcarg
	)

Finds the expression adressed by 'tps[]' declared in a scope containing the scope 'scope' that is an exact match. So no rules are involved and there is no result constructed. This function is needed for implementing concepts. Concepts are sets of conditions that an object must meet in order to be of a certain type.

Parameters:

	ts	type system
	scope	scope identifier declared in ts. The query scope. The scope of the result must cover the query scope and be minimal. The result scope is the innermost scope of all matching expression definitions.
	nof_tps	number of elements in tps[]
	tps	array of types defining the expression as tuple of types.
	tc	returned type constructor function identifier of the found expression.
	tcarg	returned type constructor function argument identifier of the found expression

Returns:: TypeId_NULL, if not found, and the result type of the expression in case of success.

int nu_getResultConstructor	(	nu_TypeSystem	ts,
		int	result_handle,
		uintptr_t *	tc,
		uintptr_t *	tcarg
	)

Get the constructor of the expression of the last result of 'resolveExpression'. The value of the expression can be constructed by applying the constructor functor on the elements built from the result of 'getElementConstructor'. Returns -1 when the result handle passed is invalid.

Parameters:

	ts	type system
	result_handle	handle of the result got as return value of 'resolveExpression'.
	tc	returned type constructor function identifier of the matching expression.
	tcarg	returned type constructor function argument identifier of the matching expression.

Returns:: 0, when the passed result_handle is invalid and no result is returned, 1 in case of success.

int nu_getRuleConflict	(	nu_TypeSystem	ts,
		nu_TypeId **	path1,
		nu_TypeId **	path2
	)

Get both deduction paths of the conflicts when nu_resolveExpression returned errcode=NU_ERROR_CONFLICT_RULE in the last call. path1[] and path2[] are TypeId_NULL terminated.

Parameters:

	ts	type system
	path1[]	returned first deduction path of types the first element is the last type in the chain, the last element is the starting point.
	path2[]	returned alternative deduction path of types the first element is the last type in the chain, the last element is the starting point.

Returns:: 0, if there has been no rule conflict registered, 1 on success

nu_TypeId nu_getType	(	nu_TypeSystem	ts,
		nu_Scope	scope,
		const char *	id
	)

Find the type and its constructor identified by 'id' in the scope 'scope'.

Parameters:

	ts	type system
	scope	scope identifier declared in ts. The query scope. The scope of the result type must cover the query scope and be minimal. The result scope is the innermost scope of all matching type definitions.
	id	identifier of the type to search

Returns:: nu_TypeId of the found type or TypeId_NULL if not found

uintptr_t nu_getTypeConstructor	(	nu_TypeSystem	ts,
		nu_TypeId	type,
		uintptr_t *	tcarg
	)

Returns the constructor of the type as passed with parameter 'tc' when declaring the type with 'declareType'.

Parameters:

	ts	type system
	type	identifier of the type
	tcarg	returned constructor arument ('tcarg') of 'type'

Returns:: constructor 'tc' of 'type'

char* nu_getTypeName	(	nu_TypeSystem	ts,
		nu_TypeId	type
	)

Returns the name of the type as passed with parameter 'id' when declaring the type with 'declareType'.

Parameters:

	ts	type system
	type	identifier of the type

Returns:: name of the type

int nu_resolveExpression	(	nu_TypeSystem	ts,
		nu_Scope	scope,
		unsigned int	nof_tps,
		nu_TypeId *	tps,
		nu_TypeId *	resulttype,
		nu_ErrorCode *	errcode
	)

Finds the expression adressed by 'tps[]' declared in a scope containing the scope 'scope' that is the nearest in the evaluation path. Nearest means that the expression found by applying rules to elements in the tuple 'tps' (the unifier of the query expression and the defined expression) has the minimal sum of costs of all matching expressions and their rule evaluation paths.

Parameters:

	ts	type system
	scope	scope identifier declared in ts. The query scope. The scope of the result must cover the query scope and be minimal. All applied rules must cover the query scope too. The result scope is the innermost scope of all matching expression definitions.
	nof_tps	number of elements in tps[]
	tps	array of types defining the expression as tuple of types.
	resulttype	returned type of the result.
	errcode	possible error returned in case of failure (-1 returned). In case of errors because of conflicts, you can get the conflict reason with: nu_getDecisionConflict in case of NU_ERROR_CONFLICT_DECISION (conflicting expressions) nu_getRuleConflict in case of NU_ERROR_CONFLICT_RULE (2 type unifiers with same costs)

Returns:: -1, if no expression has been found. Returns the handle of the result in case of success. The handle is ascending incremented by 1 starting from 0.

int nu_sameScope	(	nu_TypeSystem	ts,
		nu_Scope	A,
		nu_Scope	B
	)

Test two scopes to be the same. They are considered to be the same if opened with the same 'beginScope' action. Scopes derived from it with 'declareScope' are also considered to be the same.

Parameters:

	ts	type system
	A	scope identifier declared in ts.
	B	scope identifier declared in ts.

Returns:: 1, if the scopes are the same, else 0

int nu_scopeId	(	nu_TypeSystem	ts,
		nu_Scope	scope
	)

Returns an identifier for a scope unique for all declarations in the same scope.

Parameters:

	ts	type system
	scope	scope identifier declared in ts.

Returns:: -1, for an invalid scope of Scope_NULL, else the scope identifier

naru.h File Reference

Defines

Typedefs

Enumerations

Functions

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation