Adaptive function support

Files
file	afw_function.h
	Header file for Adaptive Framework Runtime Basic Function Support.

Data Structures
struct	afw_function_execute_s
	Function execute parameter. More...
struct	afw_function_environment_s

Macros
#define	AFW_FUNCTION_EXECUTE_STANDARD_POLYMORPHIC_FUNCTION_HANDLING   NULL
	Function execute is handled by standard polymorphic function handling. More...
#define	AFW_FUNCTION_ARGV(A_N)   ((A_N <= x->argc) ? x->argv[A_N] : NULL)
	Get the unevaluated argv value or NULL. More...
#define	AFW_FUNCTION_ASSERT_PARAMETER_COUNT_IS(n)
	Assert that argc is a specific number. More...
#define	AFW_FUNCTION_ASSERT_PARAMETER_COUNT_MIN(n)
	Assert that argc is at least a specific number. More...
#define	AFW_FUNCTION_ASSERT_PARAMETER_COUNT_MAX(n)
	Assert that argc is no more than specific number. More...
#define	AFW_FUNCTION_ASSERT_VALUE_IS_UTF8(A_VALUE)
	Assert that a value is at data type with cType of afw_utf8_t. More...
#define	AFW_FUNCTION_PARAMETER_IS_PRESENT(A_N)    (AFW_FUNCTION_ARGV(A_N) != NULL)
	Determine if a specific parameter value is present. More...
#define	AFW_FUNCTION_EVALUATE_DATA_TYPE_PARAMETER(A_RESULT, A_N, A_TYPE)
	Evaluate an arg for a particular data type. More...
#define	AFW_FUNCTION_EVALUATE_PARAMETER(A_RESULT, A_N)   A_RESULT = afw_function_evaluate_parameter(x, A_N, NULL)
	Evaluate a parameter. More...
#define	AFW_FUNCTION_EVALUATE_REQUIRED_PARAMETER(A_RESULT, A_N)   A_RESULT = afw_function_evaluate_required_parameter(x, A_N, NULL);
	Evaluate an required parameter. More...
#define	AFW_FUNCTION_EVALUATE_REQUIRED_CONDITION_PARAMETER(A_RESULT, A_N)
	Evaluate an arg that is a required condition. More...
#define	AFW_FUNCTION_EVALUATE_REQUIRED_DATA_TYPE_PARAMETER(A_RESULT, A_N, A_TYPE)
	Evaluate an arg for a particular data type. More...
#define	AFW_FUNCTION_SOURCE_LOCATION
	Source location of a value. More...

Functions
const afw_value_t *	afw_function_evaluate_function_parameter (const afw_value_t *function_arg, const afw_pool_t *p, afw_xctx_t *xctx)
const afw_utf8_t *	afw_function_evaluate_whitespace_parameter (afw_function_execute_t *x, afw_size_t n)
const afw_value_t *	afw_function_evaluate_parameter (afw_function_execute_t *x, afw_size_t parameter_number, const afw_data_type_t *data_type)
	Evaluate a parameter and convert if necessary. More...
	afw_function_evaluate_required_parameter (afw_function_execute_t *x, afw_size_t parameter_number, const afw_data_type_t *data_type)
	Evaluate an required parameter and convert if necessary. More...
const afw_value_t *	afw_function_evaluate_parameter_with_type (const afw_value_t *value, afw_size_t parameter_number, const afw_value_type_t *type, const afw_pool_t *p, afw_xctx_t *xctx)
	Evaluate a parameter with dataTypeParameter. More...

Detailed Description

Adaptive Framework runtime function support.

Macro Definition Documentation

AFW_FUNCTION_ARGV

#define AFW_FUNCTION_ARGV

(

A_N

)

((A_N <= x->argc) ? x->argv[A_N] : NULL)

Get the unevaluated argv value or NULL.

Parameters

A_N	is the 1 based parameter number of argv to check.

Returns

argv[A_N] or NULL.

This will return NULL if A_N is greater than x->argc.

This is used when implementing the body of an adaptive function. Like all of the AFW_FUNCTION_* macros, "x" must be the name of the function execute struct pointer.

Definition at line 159 of file afw_function.h.

AFW_FUNCTION_ASSERT_PARAMETER_COUNT_IS

#define AFW_FUNCTION_ASSERT_PARAMETER_COUNT_IS

(

n

)

Value:

do { \
    if ((x->argc) != (n)) {\
        AFW_THROW_ERROR_Z(general, "Expecting " #n " parameters.", x->xctx);\
    } \
} while (0)

Assert that argc is a specific number.

Parameters

n	is the number to check

This is used when implementing the body of an adaptive function. Like all of the AFW_FUNCTION_* macros, "x" must be the name of the function execute struct pointer.

Definition at line 172 of file afw_function.h.

AFW_FUNCTION_ASSERT_PARAMETER_COUNT_MAX

#define AFW_FUNCTION_ASSERT_PARAMETER_COUNT_MAX

(

n

)

Value:

do { \
    if (x->argc > (n)) {\
        AFW_THROW_ERROR_Z(general, "Expecting no more than " #n " parameters.", x->xctx);\
    } \
} while (0)

Assert that argc is no more than specific number.

Parameters

n	is the number to check

This is used when implementing the body of an adaptive function. Like all of the AFW_FUNCTION_* macros, "x" must be the name of the function execute struct pointer.

Definition at line 206 of file afw_function.h.

AFW_FUNCTION_ASSERT_PARAMETER_COUNT_MIN

#define AFW_FUNCTION_ASSERT_PARAMETER_COUNT_MIN

(

n

)

Value:

do { \
    if (x->argc < (n)) {\
        AFW_THROW_ERROR_Z(general, "Expecting at least " #n " parameters.", x->xctx);\
    } \
} while (0)

Assert that argc is at least a specific number.

Parameters

n	is the number to check

This is used when implementing the body of an adaptive function. Like all of the AFW_FUNCTION_* macros, "x" must be the name of the function execute struct pointer.

Definition at line 189 of file afw_function.h.

AFW_FUNCTION_ASSERT_VALUE_IS_UTF8

#define AFW_FUNCTION_ASSERT_VALUE_IS_UTF8

(

A_VALUE

)

Value:

if (!(A_VALUE) || !afw_utf8_equal( \
    &afw_value_get_data_type(((const afw_value_t *)A_VALUE), x->xctx)->cType, \
    &afw_s_afw_utf8_t)) \
{ \
    AFW_THROW_ERROR_Z(arg_error, \
        "Value's data type not supported for this function", x->xctx); \
}

Assert that a value is at data type with cType of afw_utf8_t.

Parameters

A_VALUE

to check.

This is used when implementing the body of an adaptive function. Like all of the AFW_FUNCTION_* macros, "x" must be the name of the function execute struct pointer.

Definition at line 223 of file afw_function.h.

AFW_FUNCTION_EVALUATE_DATA_TYPE_PARAMETER

#define AFW_FUNCTION_EVALUATE_DATA_TYPE_PARAMETER	(		A_RESULT,
			A_N,
			A_TYPE
	)

Value:

A_RESULT = (const afw_value_##A_TYPE##_t *) \
    afw_function_evaluate_parameter(x, A_N, afw_data_type_##A_TYPE)

Evaluate an arg for a particular data type.

Parameters

A_RESULT	is a const afw_value_<A_TYPE>_t * variable name for result.
A_N	is the 1 based parameter number in of argv to evaluate.
A_TYPE	is the unquoted dataType.

Returns

the value casted to afw_value_<A_TYPE>_t * or NULL (undefined).

This is used when implementing the body of an adaptive function. Like all of the AFW_FUNCTION_* macros, "x" must be the name of the function execute struct pointer.

It is up to the implementation to check if A_RESULT is NULL and the correct data type.

Definition at line 261 of file afw_function.h.

AFW_FUNCTION_EVALUATE_PARAMETER

#define AFW_FUNCTION_EVALUATE_PARAMETER	(		A_RESULT,
			A_N
	)		A_RESULT = afw_function_evaluate_parameter(x, A_N, NULL)

Evaluate a parameter.

Parameters

A_RESULT	is a const afw_value_t * variable name for result.
A_N	is the 1 based parameter number in argv to evaluate.

This is used when implementing the body of an adaptive function. Like all of the AFW_FUNCTION_* macros, "x" must be the name of the function execute struct pointer.

It is up to the implementation to check if A_RESULT is NULL and the correct data type.

Definition at line 279 of file afw_function.h.

AFW_FUNCTION_EVALUATE_REQUIRED_CONDITION_PARAMETER

#define AFW_FUNCTION_EVALUATE_REQUIRED_CONDITION_PARAMETER	(		A_RESULT,
			A_N
	)

Value:

A_RESULT = (const afw_value_boolean_t *) \
    afw_function_evaluate_required_parameter(x, A_N, NULL); \
    if (!afw_value_is_boolean(A_RESULT)) \
        AFW_THROW_ERROR_FZ(arg_error, xctx, \
            "Condition must be boolean (parameter %d)", (A_N))

Evaluate an arg that is a required condition.

Parameters

A_RESULT	is a const afw_value_<A_TYPE>_t * variable name for result.
A_N	is the 1 based parameter number in of argv to evaluate.

This is used when implementing the body of an adaptive function. Like all of the AFW_FUNCTION_* macros, "x" must be the name of the function execute struct pointer.

Definition at line 309 of file afw_function.h.

AFW_FUNCTION_EVALUATE_REQUIRED_DATA_TYPE_PARAMETER

#define AFW_FUNCTION_EVALUATE_REQUIRED_DATA_TYPE_PARAMETER	(		A_RESULT,
			A_N,
			A_TYPE
	)

Value:

A_RESULT = (const afw_value_##A_TYPE##_t *) \
    afw_function_evaluate_required_parameter(x, A_N, afw_data_type_##A_TYPE)

Evaluate an arg for a particular data type.

Parameters

A_RESULT	is a const afw_value_<A_TYPE>_t * variable name for result.
A_N	is the 1 based parameter number in of argv to evaluate.
A_TYPE	is the unquoted dataType.

This is used when implementing the body of an adaptive function. Like all of the AFW_FUNCTION_* macros, "x" must be the name of the function execute struct pointer.

Definition at line 328 of file afw_function.h.

AFW_FUNCTION_EVALUATE_REQUIRED_PARAMETER

#define AFW_FUNCTION_EVALUATE_REQUIRED_PARAMETER	(		A_RESULT,
			A_N
	)		A_RESULT = afw_function_evaluate_required_parameter(x, A_N, NULL);

Evaluate an required parameter.

Parameters

A_RESULT	is a const afw_value_t * variable name for result.
A_N	is the 1 based parameter number in argv to evaluate.

This is used when implementing the body of an adaptive function. Like all of the AFW_FUNCTION_* macros, "x" must be the name of the function execute struct pointer.

A undefined error is thrown if result is NULL.

Definition at line 295 of file afw_function.h.

AFW_FUNCTION_EXECUTE_STANDARD_POLYMORPHIC_FUNCTION_HANDLING

#define AFW_FUNCTION_EXECUTE_STANDARD_POLYMORPHIC_FUNCTION_HANDLING   NULL

Function execute is handled by standard polymorphic function handling.

NULL in function->execute indicates standard polymorphic function handling is performed in afw_value_call_built_in_function.c function impl_afw_value_optional_evaluate().

The reason this is NULL:

AFW_FUNCTION_EXECUTE_STANDARD_POLYMORPHIC_FUNCTION_HANDLING is NULL so it can be used in extensions. The generated *_function_bindings.c source contains a direct reference to the execute function name so if this was a direct reference to a function, there would be linkage problems on some operating systems.

Definition at line 44 of file afw_function.h.

AFW_FUNCTION_PARAMETER_IS_PRESENT

#define AFW_FUNCTION_PARAMETER_IS_PRESENT

(

A_N

)

(AFW_FUNCTION_ARGV(A_N) != NULL)

Determine if a specific parameter value is present.

Parameters

A_N	is the 1 based parameter number of argv to check.

This is used when implementing the body of an adaptive function. Like all of the AFW_FUNCTION_* macros, "x" must be the name of the function execute struct pointer.

Definition at line 242 of file afw_function.h.

AFW_FUNCTION_SOURCE_LOCATION

#define AFW_FUNCTION_SOURCE_LOCATION

Value:

afw_compile_source_location_of_value( \
    (const afw_value_t *)x->self, x->p, x->xctx)

Source location of a value.

This is used when implementing the body of an adaptive function. Like all of the AFW_FUNCTION_* macros, "x" must be the name of the function execute struct pointer.

Definition at line 341 of file afw_function.h.

Function Documentation

afw_function_evaluate_parameter()

const afw_value_t* afw_function_evaluate_parameter	(	afw_function_execute_t *	x,
		afw_size_t	parameter_number,
		const afw_data_type_t *	data_type
	)

Evaluate a parameter and convert if necessary.

Parameters

x	function execute struct pointer.
parameter_number	starting at 1.
data_type	result will be converted to if needed or NULL.

Returns

value of parameter or undefined (NULL).

This function adds the parameter number to the evaluation stack if an evaluation or conversion is needed then removes it if successful.

It's up to the caller to check if the returned value is undefined. Use afw_function_evaluate_required_parameter() instead for required parameters.

If data_type specified and result can't be converted, an error is thrown.

Definition at line 129 of file afw_function.c.

afw_function_evaluate_parameter_with_type()

const afw_value_t* afw_function_evaluate_parameter_with_type	(	const afw_value_t *	value,
		afw_size_t	parameter_number,
		const afw_value_type_t *	type,
		const afw_pool_t *	p,
		afw_xctx_t *	xctx
	)

Evaluate a parameter with dataTypeParameter.

Parameters

value	to evaluate.
parameter_number	starting at 1.
type	for result or NULL if not converting.
p	Pool
xctx	of caller.

Returns

value or undefined if there is an error.

This is called for script function parameters so is different from others for now.

Todo:

FIXME: add support for dataTypeParameter.

Definition at line 243 of file afw_function.c.

afw_function_evaluate_required_parameter()

afw_function_evaluate_required_parameter	(	afw_function_execute_t *	x,
		afw_size_t	parameter_number,
		const afw_data_type_t *	data_type
	)

Evaluate an required parameter and convert if necessary.

Parameters

x	function execute struct pointer.
parameter_number	starting at 1.
data_type	result will be converted to if needed or NULL.

Returns

value of parameter.

This function adds the parameter number to the evaluation stack if an evaluation or conversion is needed then removes it if successful.

If result is undefined or data_type is specified and can't be converted, an error is thrown.

Definition at line 213 of file afw_function.c.