src/pabstract.h File Reference

description of callbacks. More...

#include "pstring.h"
#include "pabidecl.h"

Include dependency graph for pabstract.h:

This graph shows which files directly or indirectly include this file:


Typedefs

typedef void ABSTRACT_WRITER
 optional pointer to be passed to a callback of writer_functype.
typedef void ABSTRACT_FINDFILE
 optional pointer to be passed to a callback of find_file_functype.
typedef void ABSTRACT_FILTER
 optional pointer to be passed to a callback of load_file_functype / unload_file_functype.
typedef void ABSTRACT_CALLER
 optional pointer to be passed to a callback of call_expr_userfnc_functype.
typedef void ABSTRACT_DATASTATE
 optional pointer to be passed to data manipulation callbacks of get_ABSTRACT_VALUE_functype, ABSTRACT_VALUE2ABSTRACT_ARRAY_functype, get_ABSTRACT_ARRAY_length_functype, is_ABSTRACT_VALUE_true_functype, get_ABSTRACT_MAP_functype, exit_loop_scope_functype.
typedef void ABSTRACT_ARRAY
 optional pointer representing a loop.
typedef void ABSTRACT_MAP
 optional pointer representing a root scope or a loop scope.
typedef void ABSTRACT_VALUE
 optional pointer representing an abstract value that can be converted to a sting or loop.
typedef void ABSTRACT_FUNCMAP
 optional pointer to be passed to a callback of is_expr_userfnc_functype.
typedef void ABSTRACT_ARGLIST
 optional pointer representing a list accumulating arguments to user function call.
typedef void ABSTRACT_USERFUNC
 optional pointer representing user function.
typedef struct exprval ABSTRACT_EXPRVAL
 optional pointer representing user function argument or return value.
typedef void BACKCALL(* writer_functype )(ABSTRACT_WRITER *, const char *begin, const char *endnext)
 optional callback for writing or accumulating a piece of generated text.
typedef ABSTRACT_VALUE *BACKCALL(* get_ABSTRACT_VALUE_functype )(ABSTRACT_DATASTATE *, ABSTRACT_MAP *, PSTRING name)
 required callback to get a variable value.
typedef PSTRING BACKCALL(* ABSTRACT_VALUE2PSTRING_functype )(ABSTRACT_DATASTATE *, ABSTRACT_VALUE *)
 required callback to transform into PSTRING a variable name passed to callback of get_ABSTRACT_VALUE_functype.
typedef int BACKCALL(* is_ABSTRACT_VALUE_true_functype )(ABSTRACT_DATASTATE *, ABSTRACT_VALUE *)
 optional callback to fine-tune is ABSTRACT_VALUE* is true or false.
typedef ABSTRACT_ARRAY *BACKCALL(* ABSTRACT_VALUE2ABSTRACT_ARRAY_functype )(ABSTRACT_DATASTATE *, ABSTRACT_VALUE *)
 required callback to transform into ABSTRACT_ARRAY a variable name passed to callback of get_ABSTRACT_VALUE_functype.
typedef int BACKCALL(* get_ABSTRACT_ARRAY_length_functype )(ABSTRACT_DATASTATE *, ABSTRACT_ARRAY *)
 optional callback to specify a length of the loop.
typedef ABSTRACT_MAP *BACKCALL(* get_ABSTRACT_MAP_functype )(ABSTRACT_DATASTATE *, ABSTRACT_ARRAY *, int)
 required callback to transform into ABSTRACT_ARRAY a variable name passed to callback of get_ABSTRACT_VALUE_functype.
typedef const char *BACKCALL(* find_file_functype )(ABSTRACT_FINDFILE *, const char *filename, const char *prevfilename)
 optional callback to fine-tune the algorythm of finding template file by name.
typedef PSTRING BACKCALL(* load_file_functype )(ABSTRACT_FILTER *, const char *filename)
 optional callback to load and preprocess (filter) files.
typedef int BACKCALL(* unload_file_functype )(ABSTRACT_FILTER *, PSTRING memarea)
 optional callback to free memory accuired by a callback of load_file_functype.
typedef ABSTRACT_USERFUNC
*BACKCALL(* 
is_expr_userfnc_functype )(ABSTRACT_FUNCMAP *, PSTRING name)
 optional callback for support of user-provided functions.
typedef ABSTRACT_ARGLIST
*BACKCALL(* 
init_expr_arglist_functype )(ABSTRACT_CALLER *)
 optional callback to initialize the list of arguments for a user-provided function.
typedef void BACKCALL(* push_expr_arglist_functype )(ABSTRACT_ARGLIST *, ABSTRACT_EXPRVAL *)
 optional callback to add new value to the list of arguments for a user-provided function.
typedef void BACKCALL(* free_expr_arglist_functype )(ABSTRACT_ARGLIST *)
 optional callback to release the list of arguments for a user-provided function.
typedef void BACKCALL(* call_expr_userfnc_functype )(ABSTRACT_CALLER *, ABSTRACT_ARGLIST *, ABSTRACT_USERFUNC *, ABSTRACT_EXPRVAL *return_value)
 optional callback to call a user-provided function with a current list of arguments.

Detailed Description

description of callbacks.

In order to interact with core library a wrapper should provide some callback functions. This file specifies which callbacks can be provided.

Author:
Igor Vlasenko <vlasenko@imath.kiev.ua>
Warning:
This header file should never be included directly. Include <tmplpro.h> instead.

Typedef Documentation

typedef void ABSTRACT_ARGLIST

optional pointer representing a list accumulating arguments to user function call.

It is returned from a callback of init_expr_arglist_functype and is passed to callbacks of push_expr_arglist_functype, call_expr_userfnc_functype and free_expr_arglist_functype.

typedef void ABSTRACT_ARRAY

optional pointer representing a loop.

It is returned from a callback of ABSTRACT_VALUE2ABSTRACT_ARRAY_functype and is passed to callbacks of get_ABSTRACT_ARRAY_length_functype and get_ABSTRACT_MAP_functype.

typedef void ABSTRACT_CALLER

optional pointer to be passed to a callback of call_expr_userfnc_functype.

Optional pointer to store internal state for a callback of call_expr_userfnc_functype. If used, it should be stored beforehand with tmplpro_set_option_ext_calluserfunc_state().

See also:
tmplpro_set_option_ext_calluserfunc_state

typedef void ABSTRACT_DATASTATE

optional pointer to be passed to data manipulation callbacks of get_ABSTRACT_VALUE_functype, ABSTRACT_VALUE2ABSTRACT_ARRAY_functype, get_ABSTRACT_ARRAY_length_functype, is_ABSTRACT_VALUE_true_functype, get_ABSTRACT_MAP_functype, exit_loop_scope_functype.

Optional pointer to store internal state for a callback of get_ABSTRACT_VALUE_functype, ABSTRACT_VALUE2ABSTRACT_ARRAY_functype, get_ABSTRACT_ARRAY_length_functype, is_ABSTRACT_VALUE_true_functype, get_ABSTRACT_MAP_functype, exit_loop_scope_functype. If used, it should be stored beforehand with tmplpro_set_option_ext_data_state().

See also:
tmplpro_set_option_ext_data_state

typedef void ABSTRACT_EXPRVAL

optional pointer representing user function argument or return value.

It is passed to callbacks of push_expr_arglist_functype and call_expr_userfnc_functype.

typedef void ABSTRACT_FILTER

optional pointer to be passed to a callback of load_file_functype / unload_file_functype.

Optional pointer to store internal state for a callback of load_file_functype / unload_file_functype. If used, it should be stored beforehand with tmplpro_set_option_ext_filter_state().

See also:
tmplpro_set_option_ext_filter_state

typedef void ABSTRACT_FINDFILE

optional pointer to be passed to a callback of find_file_functype.

Optional pointer to store internal state for a callback of find_file_functype. If used, it should be stored beforehand with tmplpro_set_option_ext_findfile_state().

See also:
tmplpro_set_option_ext_findfile_state

typedef void ABSTRACT_FUNCMAP

optional pointer to be passed to a callback of is_expr_userfnc_functype.

If used, it should be stored beforehand with tmplpro_set_option_expr_func_map().

See also:
tmplpro_set_option_expr_func_map

typedef void ABSTRACT_MAP

optional pointer representing a root scope or a loop scope.

Pointer for the loop scope is returned from a callback of get_ABSTRACT_MAP_functype. Pointer of the root scope should be stored beforehead using tmplpro_set_option_root_param_map(). Both types of pointers are passed to callback of get_ABSTRACT_VALUE_functype. Also, root scope pointer is passed to callbacks of end_loop_functype and select_loop_scope_functype.

See also:
tmplpro_set_option_root_param_map

typedef void ABSTRACT_USERFUNC

optional pointer representing user function.

It is returned from a callback of is_expr_userfnc_functype and is passed to callback of call_expr_userfnc_functype.

typedef void ABSTRACT_VALUE

optional pointer representing an abstract value that can be converted to a sting or loop.

It is returned from callback of get_ABSTRACT_VALUE_functype and passed to callbacks of ABSTRACT_VALUE2ABSTRACT_ARRAY_functype and ABSTRACT_VALUE2PSTRING_functype.

required callback to transform into ABSTRACT_ARRAY a variable name passed to callback of get_ABSTRACT_VALUE_functype.

Parameters:
ABSTRACT_VALUE* optional pointer returned by callback of get_ABSTRACT_VALUE_functype.
Returns:
NULL if NAME can not be converted to ABSTRACT_ARRAY or a non-null pointer that will be passed then to callbacks of get_ABSTRACT_ARRAY_length_functype and get_ABSTRACT_MAP_functype.
See also:
tmplpro_set_option_AbstractVal2abstractArrayFuncPtr

required callback to transform into PSTRING a variable name passed to callback of get_ABSTRACT_VALUE_functype.

Parameters:
ABSTRACT_VALUE* optional pointer returned by callback of get_ABSTRACT_VALUE_functype.
Returns:
PSTRING to a memory area. The memery area can be safely freed in the next call to ABSTRACT_VALUE2PSTRING_functype.
See also:
tmplpro_set_option_AbstractVal2pstringFuncPtr

typedef void ABSTRACT_WRITER

optional pointer to be passed to a callback of writer_functype.

Optional pointer to store internal state for a callback of writer_functype. If used, it should be stored beforehand with tmplpro_set_option_ext_writer_state().

See also:
tmplpro_set_option_ext_writer_state

optional callback to call a user-provided function with a current list of arguments.

Parameters:
ABSTRACT_CALLER* optional pointer stored by tmplpro_set_option_ext_calluserfunc_state().
ABSTRACT_ARGLIST* optional pointer returned by callback of init_expr_arglist_functype.
ABSTRACT_USERFUNC* optional pointer returned by callback of is_expr_userfnc_functype.
ABSTRACT_EXPRVAL* pointer required by tmplpro_set_expr_as_* functions (a place the return value will be stored).
To return the result user function returned the callback of call_expr_userfnc_functype should call one of the functions
See also:
tmplpro_set_option_CallExprUserfncFuncPtr

typedef const char *(* find_file_functype)(ABSTRACT_FINDFILE *, const char *filename, const char *prevfilename)

optional callback to fine-tune the algorythm of finding template file by name.

Parameters:
ABSTRACT_FINDFILE* optional pointer stored by tmplpro_set_option_ext_writer_state().
filename file to be found.
prevfilename fully qualified path to containing file, if any.
Returns:
fully qualified path to a file to be loaded.
By default a stub is used (as of 0.82, with limited functionality).

See also:
tmplpro_set_option_FindFileFuncPtr

optional callback to release the list of arguments for a user-provided function.

Note that if function calls are nested, then the calls to a callbacks of init_expr_arglist_functype, push_expr_arglist_functype, free_expr_arglist_functype will also be nested.

Parameters:
ABSTRACT_ARGLIST* optional pointer returned by callback of init_expr_arglist_functype.
See also:
tmplpro_set_option_FreeExprArglistFuncPtr

optional callback to specify a length of the loop.

Parameters:
ABSTRACT_ARRAY* optional pointer returned by callback of ABSTRACT_VALUE2ABSTRACT_ARRAY_functype.
Returns:
the length of the loop or a special value of -1 that indicates that loop has an undefined length (useful when one need to iterate over large number of records in database or lines in a file).
By default a stub is used that returns -1.

See also:
tmplpro_set_option_GetAbstractArrayLengthFuncPtr

required callback to transform into ABSTRACT_ARRAY a variable name passed to callback of get_ABSTRACT_VALUE_functype.

Parameters:
ABSTRACT_ARRAY* optional pointer returned by callback of ABSTRACT_VALUE2ABSTRACT_ARRAY_functype.
n - number of current loop iteration.
Returns:
NULL if loop can no nore be iterated or a non-null pointer that will be passed to callback of get_ABSTRACT_VALUE_functype.
See also:
tmplpro_set_option_GetAbstractMapFuncPtr

required callback to get a variable value.

Parameters:
PSTRING name - a name as in <TMPL_VAR NAME="var1">
ABSTRACT_MAP* pointer returned by callback of get_ABSTRACT_MAP_functype.
Returns:
NULL if NAME not found or a non-null pointer to be passed to callback of ABSTRACT_VALUE2PSTRING_functype or ABSTRACT_VALUE2ABSTRACT_ARRAY_functype.
See also:
tmplpro_set_option_GetAbstractValFuncPtr

optional callback to initialize the list of arguments for a user-provided function.

Note that if function calls are nested, then the calls to a callbacks of init_expr_arglist_functype, push_expr_arglist_functype, free_expr_arglist_functype will also be nested.

Parameters:
ABSTRACT_CALLER* optional pointer stored by tmplpro_set_option_ext_calluserfunc_state().
Returns:
value to be passed to callbacks of push_expr_arglist_functype, free_expr_arglist_functype and call_expr_userfnc_functype.
See also:
tmplpro_set_option_InitExprArglistFuncPtr

optional callback to fine-tune is ABSTRACT_VALUE* is true or false.

Parameters:
ABSTRACT_VALUE* optional pointer returned by callback of get_ABSTRACT_VALUE_functype.
Returns:
0(false) or 1(true).
By default a stub is used that guesses true or false according to PSTRING form of ABSTRACT_VALUE.

See also:
tmplpro_set_option_IsAbstractValTrueFuncPtr

optional callback for support of user-provided functions.

Parameters:
ABSTRACT_FUNCMAP* optional pointer stored by tmplpro_set_option_expr_func_map().
name name of function
Returns:
NULL if there is no user function with such a name or non-null value to be passed to callback of call_expr_userfnc_functype.
Warning:
if is_expr_userfnc_functype callback is set, then callbacks of init_expr_arglist_functype, push_expr_arglist_functype, free_expr_arglist_functype and call_expr_userfnc_functype also should be set.
See also:
tmplpro_set_option_IsExprUserfncFuncPtr

typedef PSTRING(* load_file_functype)(ABSTRACT_FILTER *, const char *filename)

optional callback to load and preprocess (filter) files.

Only called if filters option is true (set by tmplpro_set_option_filters() ).

Parameters:
ABSTRACT_FILTER* optional pointer stored by tmplpro_set_option_ext_filter_state().
filename fully qualified path to a file to be loaded (as returned by callback of find_file_functype).
Returns:
PSTRING of memory area loaded.
See also:
tmplpro_set_option_filters

tmplpro_set_option_LoadFileFuncPtr

optional callback to add new value to the list of arguments for a user-provided function.

Note that if function calls are nested, then the calls to a callbacks of init_expr_arglist_functype, push_expr_arglist_functype, free_expr_arglist_functype will also be nested.

Parameters:
ABSTRACT_ARGLIST* optional pointer returned by callback of init_expr_arglist_functype.
ABSTRACT_EXPRVAL* pointer required by tmplpro_get_expr_* functions to retrieve the value (a place the pushed value is stored).
A value to be added to the list of arguments for a user-provided function is not passed as argument to a callback of push_expr_arglist_functype. Instead, a pointer to struct tmplpro_param is passed, and the callback function should discover the value's type using tmplpro_get_expr_type() function, and then should retrieve the value using one of the functions
See also:
tmplpro_set_option_PushExprArglistFuncPtr

typedef int(* unload_file_functype)(ABSTRACT_FILTER *, PSTRING memarea)

optional callback to free memory accuired by a callback of load_file_functype.

Only called if filters option is true (set by tmplpro_set_option_filters() ).

Parameters:
ABSTRACT_FILTER* optional pointer stored by tmplpro_set_option_ext_filter_state().
memarea pointers to loaded area (as returned by callback of load_file_functype).
Returns:
0 on success, non-zero otherwise.
See also:
tmplpro_set_option_filters

tmplpro_set_option_UnloadFileFuncPtr

typedef void(* writer_functype)(ABSTRACT_WRITER *, const char *begin, const char *endnext)

optional callback for writing or accumulating a piece of generated text.

Parameters:
begin,endnext - pointers to memory area containing the output string.
ABSTRACT_WRITER* - pointer stored by tmplpro_set_option_ext_writer_state() or NULL if nothing was stored.
Note that outpot string is NOT 0-terminated. Instead, 2 pointers are used, as in PSTRING. This callback is called multiple times. This callback is optional: if not provided, a built-in stub will output to STDOUT.

See also:
tmplpro_set_option_WriterFuncPtr

tmplpro_set_option_ext_writer_state


Generated on Fri Mar 26 22:02:19 2010 for htmltmplpro by  doxygen 1.5.9