/*! \file pabstract.h
\brief 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.
*/
#ifndef _PROABSTRACT_H
#define _PROABSTRACT_H 1
#include "pstring.h"
#include "pabidecl.h"
struct tmplpro_param;
struct exprval;
typedef void ABSTRACT_WRITER;
typedef void ABSTRACT_FINDFILE;
typedef void ABSTRACT_FILTER;
typedef void ABSTRACT_CALLER;
typedef void ABSTRACT_DATASTATE;
typedef void ABSTRACT_ARRAY;
typedef void ABSTRACT_MAP;
typedef void ABSTRACT_VALUE;
typedef void ABSTRACT_FUNCMAP;
typedef void ABSTRACT_ARGLIST;
typedef void ABSTRACT_USERFUNC;
typedef struct exprval ABSTRACT_EXPRVAL;
typedef void BACKCALL (*writer_functype) (ABSTRACT_WRITER*,const char* begin, const char* endnext);
typedef ABSTRACT_VALUE* BACKCALL (*get_ABSTRACT_VALUE_functype) (ABSTRACT_DATASTATE*, ABSTRACT_MAP*, PSTRING name);
typedef PSTRING BACKCALL (*ABSTRACT_VALUE2PSTRING_functype) (ABSTRACT_DATASTATE*, ABSTRACT_VALUE*);
/* optional */
typedef int BACKCALL (*is_ABSTRACT_VALUE_true_functype) (ABSTRACT_DATASTATE*, ABSTRACT_VALUE*);
typedef ABSTRACT_ARRAY* BACKCALL (*ABSTRACT_VALUE2ABSTRACT_ARRAY_functype) (ABSTRACT_DATASTATE*, ABSTRACT_VALUE*);
typedef int BACKCALL (*get_ABSTRACT_ARRAY_length_functype) (ABSTRACT_DATASTATE*, ABSTRACT_ARRAY*);
typedef ABSTRACT_MAP* BACKCALL (*get_ABSTRACT_MAP_functype) (ABSTRACT_DATASTATE*, ABSTRACT_ARRAY*,int);
/* optional notifier */
typedef void BACKCALL (*exit_loop_scope_functype) (ABSTRACT_DATASTATE*, ABSTRACT_ARRAY*);
typedef const char* BACKCALL (*find_file_functype) (ABSTRACT_FINDFILE*, const char* filename, const char* prevfilename);
/* optional; we can use wrapper to load file and apply its filters before running itself */
/* note that this function should allocate region 1 byte nore than the file size */
typedef PSTRING BACKCALL (*load_file_functype) (ABSTRACT_FILTER*, const char* filename);
typedef int BACKCALL (*unload_file_functype) (ABSTRACT_FILTER*, PSTRING memarea);
/* -------- Expr extension------------ */
/* those are needed for EXPR= extension */
typedef ABSTRACT_USERFUNC* BACKCALL (*is_expr_userfnc_functype) (ABSTRACT_FUNCMAP*, PSTRING name);
typedef ABSTRACT_ARGLIST* BACKCALL (*init_expr_arglist_functype) (ABSTRACT_CALLER*);
typedef void BACKCALL (*push_expr_arglist_functype) (ABSTRACT_ARGLIST*, ABSTRACT_EXPRVAL*);
typedef void BACKCALL (*free_expr_arglist_functype) (ABSTRACT_ARGLIST*);
typedef void BACKCALL (*call_expr_userfnc_functype) (ABSTRACT_CALLER*, ABSTRACT_ARGLIST*, ABSTRACT_USERFUNC*, ABSTRACT_EXPRVAL* return_value);
/* ------- end Expr extension -------- */
#endif /* _PROABSTRACT_H */
/** \typedef typedef void (*writer_functype) (ABSTRACT_WRITER*,const char* begin, const char* endnext);
\brief optional callback for writing or accumulating a piece of generated text.
\param begin, endnext - pointers to memory area containing the output string.
\param 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 tmplpro_set_option_WriterFuncPtr
@see tmplpro_set_option_ext_writer_state
*/
/** \typedef typedef ABSTRACT_VALUE* (*get_ABSTRACT_VALUE_functype) (ABSTRACT_MAP*, PSTRING name);
\brief required callback to get a variable value.
\param PSTRING name - a name as in <TMPL_VAR NAME="var1">
\param ABSTRACT_MAP* pointer returned by callback of get_ABSTRACT_MAP_functype.
\return 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 tmplpro_set_option_GetAbstractValFuncPtr
*/
/** \typedef typedef PSTRING (*ABSTRACT_VALUE2PSTRING_functype) (ABSTRACT_VALUE*);
\brief required callback to transform into PSTRING a variable name passed to callback of get_ABSTRACT_VALUE_functype.
\param ABSTRACT_VALUE* optional pointer returned by callback of get_ABSTRACT_VALUE_functype.
\return PSTRING to a memory area. The memery area can be safely freed in the next call
to ABSTRACT_VALUE2PSTRING_functype.
@see tmplpro_set_option_AbstractVal2pstringFuncPtr
*/
/** \typedef typedef int (*is_ABSTRACT_VALUE_true_functype) (ABSTRACT_VALUE*);
\brief optional callback to fine-tune is ABSTRACT_VALUE* is true or false.
\param ABSTRACT_VALUE* optional pointer returned by callback of get_ABSTRACT_VALUE_functype.
\return 0(false) or 1(true).
By default a stub is used that guesses true or false according to PSTRING form of ABSTRACT_VALUE.
@see tmplpro_set_option_IsAbstractValTrueFuncPtr
*/
/** \typedef typedef ABSTRACT_ARRAY* (*ABSTRACT_VALUE2ABSTRACT_ARRAY_functype) (ABSTRACT_VALUE*);
\brief required callback to transform into ABSTRACT_ARRAY a variable name passed to callback of get_ABSTRACT_VALUE_functype.
\param ABSTRACT_VALUE* optional pointer returned by callback of get_ABSTRACT_VALUE_functype.
\return 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 tmplpro_set_option_AbstractVal2abstractArrayFuncPtr
*/
/** \typedef typedef int (*get_ABSTRACT_ARRAY_length_functype) (ABSTRACT_ARRAY*);
\brief optional callback to specify a length of the loop.
\param ABSTRACT_ARRAY* optional pointer returned by callback of ABSTRACT_VALUE2ABSTRACT_ARRAY_functype.
\return 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 tmplpro_set_option_GetAbstractArrayLengthFuncPtr
*/
/** \typedef typedef ABSTRACT_MAP* (*get_ABSTRACT_MAP_functype) (ABSTRACT_ARRAY*,int n);
\brief required callback to transform into ABSTRACT_ARRAY a variable name passed to callback of get_ABSTRACT_VALUE_functype.
\param ABSTRACT_ARRAY* optional pointer returned by callback of ABSTRACT_VALUE2ABSTRACT_ARRAY_functype.
\param n - number of current loop iteration.
\return 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 tmplpro_set_option_GetAbstractMapFuncPtr
*/
/** \typedef typedef void (*end_loop_functype) (ABSTRACT_MAP* root_param_map, int newlevel);
\brief optional callback to notify a front-end that the current loop is exited.
\param ABSTRACT_MAP* optional pointer stored by tmplpro_set_option_root_param_map().
\param newlevel current depth of nested loops (0 means a root scope).
This callback is useful for front-end implementations which does not return pointers
to real objects. In that case the corresponding ABSTRACT_MAP*, ABSTRACT_ARRAY*, and ABSTRACT_VALUE*
pointers are fake non-null values, so instead of those pointers this callback can be used.
@see tmplpro_set_option_EndLoopFuncPtr
*/
/** \typedef typedef void (*select_loop_scope_functype) (ABSTRACT_MAP* root_param_map, int level);
\brief optional callback to select a loop.
\param ABSTRACT_MAP* optional pointer stored by tmplpro_set_option_root_param_map().
\param int level level at which a loop will be selected.
This callback is useful for front-end implementations which does not return pointers
to real objects. In that case the corresponding ABSTRACT_MAP*, ABSTRACT_ARRAY*, and ABSTRACT_VALUE*
pointers are fake non-null values, so instead of those pointers this callback can be used.
@see tmplpro_set_option_SelectLoopScopeFuncPtr
*/
/** \typedef typedef const char* (*find_file_functype) (ABSTRACT_FINDFILE*, const char* filename, const char* prevfilename);
\brief optional callback to fine-tune the algorythm of finding template file by name.
\param ABSTRACT_FINDFILE* optional pointer stored by tmplpro_set_option_ext_writer_state().
\param filename file to be found.
\param prevfilename fully qualified path to containing file, if any.
\return fully qualified path to a file to be loaded.
By default a stub is used (as of 0.82, with limited functionality).
@see tmplpro_set_option_FindFileFuncPtr
*/
/** \typedef typedef PSTRING (*load_file_functype) (ABSTRACT_FILTER*, const char* filename);
\brief optional callback to load and preprocess (filter) files.
Only called if filters option is true (set by tmplpro_set_option_filters() ).
\param ABSTRACT_FILTER* optional pointer stored by tmplpro_set_option_ext_filter_state().
\param filename fully qualified path to a file to be loaded
(as returned by callback of find_file_functype).
\return PSTRING of memory area loaded.
@see tmplpro_set_option_filters
@see tmplpro_set_option_LoadFileFuncPtr
*/
/** \typedef typedef int (*unload_file_functype) (ABSTRACT_FILTER*, PSTRING memarea);
\brief 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() ).
\param ABSTRACT_FILTER* optional pointer stored by tmplpro_set_option_ext_filter_state().
\param memarea pointers to loaded area
(as returned by callback of load_file_functype).
\return 0 on success, non-zero otherwise.
@see tmplpro_set_option_filters
@see tmplpro_set_option_UnloadFileFuncPtr
*/
/** \typedef typedef ABSTRACT_USERFUNC* (*is_expr_userfnc_functype) (ABSTRACT_FUNCMAP*, PSTRING name);
\brief optional callback for support of user-provided functions.
\param ABSTRACT_FUNCMAP* optional pointer stored by tmplpro_set_option_expr_func_map().
\param name name of function
\return 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 tmplpro_set_option_IsExprUserfncFuncPtr
*/
/** \typedef typedef ABSTRACT_ARGLIST* (*init_expr_arglist_functype) (ABSTRACT_CALLER*);
\brief 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.
\param ABSTRACT_CALLER* optional pointer stored by tmplpro_set_option_ext_calluserfunc_state().
\return value to be passed to callbacks of push_expr_arglist_functype,
free_expr_arglist_functype and call_expr_userfnc_functype.
@see tmplpro_set_option_InitExprArglistFuncPtr
*/
/** \typedef typedef void (*free_expr_arglist_functype) (ABSTRACT_ARGLIST*);
\brief 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.
\param ABSTRACT_ARGLIST* optional pointer returned by callback of init_expr_arglist_functype.
@see tmplpro_set_option_FreeExprArglistFuncPtr
*/
/** \typedef typedef void (*push_expr_arglist_functype) (ABSTRACT_ARGLIST*, ABSTRACT_EXPRVAL*);
\brief 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.
\param ABSTRACT_ARGLIST* optional pointer returned by callback of init_expr_arglist_functype.
\param 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
\li tmplpro_get_expr_as_int64()
\li tmplpro_get_expr_as_double()
\li tmplpro_get_expr_as_pstring()
@see tmplpro_set_option_PushExprArglistFuncPtr
*/
/** \typedef typedef void (*call_expr_userfnc_functype) (ABSTRACT_CALLER*, ABSTRACT_ARGLIST*, ABSTRACT_USERFUNC*, ABSTRACT_EXPRVAL*);
\brief optional callback to call a user-provided function with a current list of arguments.
\param ABSTRACT_CALLER* optional pointer stored by tmplpro_set_option_ext_calluserfunc_state().
\param ABSTRACT_ARGLIST* optional pointer returned by callback of init_expr_arglist_functype.
\param ABSTRACT_USERFUNC* optional pointer returned by callback of is_expr_userfnc_functype.
\param 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
\li tmplpro_set_expr_as_null()
\li tmplpro_set_expr_as_int64()
\li tmplpro_set_expr_as_double()
\li tmplpro_set_expr_as_string()
\li tmplpro_set_expr_as_pstring()
passing them the ABSTRACT_EXPRVAL* as argument.
@see tmplpro_set_option_CallExprUserfncFuncPtr
*/
/** \typedef typedef void ABSTRACT_WRITER
\brief 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 tmplpro_set_option_ext_writer_state
*/
/** \typedef typedef void ABSTRACT_FINDFILE
\brief 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 tmplpro_set_option_ext_findfile_state
*/
/** \typedef typedef void ABSTRACT_FILTER
\brief 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 tmplpro_set_option_ext_filter_state
*/
/** \typedef typedef void ABSTRACT_CALLER
\brief 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 tmplpro_set_option_ext_calluserfunc_state
*/
/** \typedef typedef void ABSTRACT_DATASTATE
\brief 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 tmplpro_set_option_ext_data_state
*/
/** \typedef typedef void ABSTRACT_ARRAY
\brief 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 typedef void ABSTRACT_MAP
\brief 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 tmplpro_set_option_root_param_map
*/
/** \typedef typedef void ABSTRACT_VALUE
\brief 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.
*/
/** \typedef typedef void ABSTRACT_FUNCMAP
\brief 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 tmplpro_set_option_expr_func_map
*/
/** \typedef typedef void ABSTRACT_ARGLIST
\brief 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 typedef void ABSTRACT_USERFUNC
\brief 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 typedef void ABSTRACT_EXPRVAL
\brief optional pointer representing user function argument or return value.
It is passed to callbacks of ::push_expr_arglist_functype and ::call_expr_userfnc_functype.
*/
/*
* Local Variables:
* mode: c
* End:
*/