1 /*! \file pabstract.h 2 \brief description of callbacks. 3 4 In order to interact with core library a wrapper should provide 5 some callback functions. 6 This file specifies which callbacks can be provided. 7 8 \author Igor Vlasenko <vlasenko@imath.kiev.ua> 9 \warning This header file should never be included directly. 10 Include <tmplpro.h> instead. 11 */ 12 13 #ifndef _PROABSTRACT_H 14 #define _PROABSTRACT_H 1 15 16 #include "pstring.h" 17 #include "pabidecl.h" 18 19 struct tmplpro_param; 20 struct exprval; 21 22 typedef void ABSTRACT_WRITER; 23 typedef void ABSTRACT_FINDFILE; 24 typedef void ABSTRACT_FILTER; 25 typedef void ABSTRACT_CALLER; 26 typedef void ABSTRACT_DATASTATE; 27 28 typedef void ABSTRACT_ARRAY; 29 typedef void ABSTRACT_MAP; 30 typedef void ABSTRACT_VALUE; 31 32 typedef void ABSTRACT_FUNCMAP; 33 typedef void ABSTRACT_ARGLIST; 34 typedef void ABSTRACT_USERFUNC; 35 typedef struct exprval ABSTRACT_EXPRVAL; 36 37 38 typedef void BACKCALL (*writer_functype) (ABSTRACT_WRITER*,const char* begin, const char* endnext); 39 40 typedef ABSTRACT_VALUE* BACKCALL (*get_ABSTRACT_VALUE_functype) (ABSTRACT_DATASTATE*, ABSTRACT_MAP*, PSTRING name); 41 typedef PSTRING BACKCALL (*ABSTRACT_VALUE2PSTRING_functype) (ABSTRACT_DATASTATE*, ABSTRACT_VALUE*); 42 /* optional */ 43 typedef int BACKCALL (*is_ABSTRACT_VALUE_true_functype) (ABSTRACT_DATASTATE*, ABSTRACT_VALUE*); 44 45 typedef ABSTRACT_ARRAY* BACKCALL (*ABSTRACT_VALUE2ABSTRACT_ARRAY_functype) (ABSTRACT_DATASTATE*, ABSTRACT_VALUE*); 46 typedef int BACKCALL (*get_ABSTRACT_ARRAY_length_functype) (ABSTRACT_DATASTATE*, ABSTRACT_ARRAY*); 47 typedef ABSTRACT_MAP* BACKCALL (*get_ABSTRACT_MAP_functype) (ABSTRACT_DATASTATE*, ABSTRACT_ARRAY*,int); 48 49 /* optional notifier */ 50 typedef void BACKCALL (*exit_loop_scope_functype) (ABSTRACT_DATASTATE*, ABSTRACT_ARRAY*); 51 52 typedef const char* BACKCALL (*find_file_functype) (ABSTRACT_FINDFILE*, const char* filename, const char* prevfilename); 53 54 /* optional; we can use wrapper to load file and apply its filters before running itself */ 55 /* note that this function should allocate region 1 byte nore than the file size */ 56 typedef PSTRING BACKCALL (*load_file_functype) (ABSTRACT_FILTER*, const char* filename); 57 typedef int BACKCALL (*unload_file_functype) (ABSTRACT_FILTER*, PSTRING memarea); 58 59 /* -------- Expr extension------------ */ 60 61 /* those are needed for EXPR= extension */ 62 typedef ABSTRACT_USERFUNC* BACKCALL (*is_expr_userfnc_functype) (ABSTRACT_FUNCMAP*, PSTRING name); 63 typedef ABSTRACT_ARGLIST* BACKCALL (*init_expr_arglist_functype) (ABSTRACT_CALLER*); 64 typedef void BACKCALL (*push_expr_arglist_functype) (ABSTRACT_ARGLIST*, ABSTRACT_EXPRVAL*); 65 typedef void BACKCALL (*free_expr_arglist_functype) (ABSTRACT_ARGLIST*); 66 typedef void BACKCALL (*call_expr_userfnc_functype) (ABSTRACT_CALLER*, ABSTRACT_ARGLIST*, ABSTRACT_USERFUNC*, ABSTRACT_EXPRVAL* return_value); 67 68 /* ------- end Expr extension -------- */ 69 70 #endif /* _PROABSTRACT_H */ 71 72 /** \typedef typedef void (*writer_functype) (ABSTRACT_WRITER*,const char* begin, const char* endnext); 73 74 \brief optional callback for writing or accumulating a piece of generated text. 75 76 \param begin, endnext - pointers to memory area containing the output string. 77 \param ABSTRACT_WRITER* - pointer stored by tmplpro_set_option_ext_writer_state() or NULL if nothing was stored. 78 79 Note that outpot string is NOT 0-terminated. Instead, 2 pointers are used, as in PSTRING. 80 This callback is called multiple times. 81 This callback is optional: if not provided, a built-in stub will output to STDOUT. 82 83 @see tmplpro_set_option_WriterFuncPtr 84 @see tmplpro_set_option_ext_writer_state 85 */ 86 87 /** \typedef typedef ABSTRACT_VALUE* (*get_ABSTRACT_VALUE_functype) (ABSTRACT_MAP*, PSTRING name); 88 \brief required callback to get a variable value. 89 90 \param PSTRING name - a name as in <TMPL_VAR NAME="var1"> 91 \param ABSTRACT_MAP* pointer returned by callback of get_ABSTRACT_MAP_functype. 92 \return NULL if NAME not found or a non-null pointer to be passed to callback 93 of ABSTRACT_VALUE2PSTRING_functype or ABSTRACT_VALUE2ABSTRACT_ARRAY_functype. 94 @see tmplpro_set_option_GetAbstractValFuncPtr 95 */ 96 97 /** \typedef typedef PSTRING (*ABSTRACT_VALUE2PSTRING_functype) (ABSTRACT_VALUE*); 98 \brief required callback to transform into PSTRING a variable name passed to callback of get_ABSTRACT_VALUE_functype. 99 100 \param ABSTRACT_VALUE* optional pointer returned by callback of get_ABSTRACT_VALUE_functype. 101 \return PSTRING to a memory area. The memery area can be safely freed in the next call 102 to ABSTRACT_VALUE2PSTRING_functype. 103 104 @see tmplpro_set_option_AbstractVal2pstringFuncPtr 105 */ 106 107 /** \typedef typedef int (*is_ABSTRACT_VALUE_true_functype) (ABSTRACT_VALUE*); 108 \brief optional callback to fine-tune is ABSTRACT_VALUE* is true or false. 109 110 \param ABSTRACT_VALUE* optional pointer returned by callback of get_ABSTRACT_VALUE_functype. 111 \return 0(false) or 1(true). 112 113 By default a stub is used that guesses true or false according to PSTRING form of ABSTRACT_VALUE. 114 115 @see tmplpro_set_option_IsAbstractValTrueFuncPtr 116 */ 117 118 /** \typedef typedef ABSTRACT_ARRAY* (*ABSTRACT_VALUE2ABSTRACT_ARRAY_functype) (ABSTRACT_VALUE*); 119 \brief required callback to transform into ABSTRACT_ARRAY a variable name passed to callback of get_ABSTRACT_VALUE_functype. 120 121 \param ABSTRACT_VALUE* optional pointer returned by callback of get_ABSTRACT_VALUE_functype. 122 \return NULL if NAME can not be converted to ABSTRACT_ARRAY or a non-null pointer that will be passed 123 then to callbacks of get_ABSTRACT_ARRAY_length_functype and get_ABSTRACT_MAP_functype. 124 125 @see tmplpro_set_option_AbstractVal2abstractArrayFuncPtr 126 */ 127 128 /** \typedef typedef int (*get_ABSTRACT_ARRAY_length_functype) (ABSTRACT_ARRAY*); 129 \brief optional callback to specify a length of the loop. 130 131 \param ABSTRACT_ARRAY* optional pointer returned by callback of ABSTRACT_VALUE2ABSTRACT_ARRAY_functype. 132 \return the length of the loop or a special value of -1 that indicates that loop has an undefined length 133 (useful when one need to iterate over large number of records in database or lines in a file). 134 135 By default a stub is used that returns -1. 136 137 @see tmplpro_set_option_GetAbstractArrayLengthFuncPtr 138 */ 139 140 /** \typedef typedef ABSTRACT_MAP* (*get_ABSTRACT_MAP_functype) (ABSTRACT_ARRAY*,int n); 141 \brief required callback to transform into ABSTRACT_ARRAY a variable name passed to callback of get_ABSTRACT_VALUE_functype. 142 143 \param ABSTRACT_ARRAY* optional pointer returned by callback of ABSTRACT_VALUE2ABSTRACT_ARRAY_functype. 144 \param n - number of current loop iteration. 145 \return NULL if loop can no nore be iterated or a non-null pointer that will be passed 146 to callback of get_ABSTRACT_VALUE_functype. 147 148 @see tmplpro_set_option_GetAbstractMapFuncPtr 149 */ 150 151 /** \typedef typedef void (*end_loop_functype) (ABSTRACT_MAP* root_param_map, int newlevel); 152 \brief optional callback to notify a front-end that the current loop is exited. 153 154 \param ABSTRACT_MAP* optional pointer stored by tmplpro_set_option_root_param_map(). 155 \param newlevel current depth of nested loops (0 means a root scope). 156 157 This callback is useful for front-end implementations which does not return pointers 158 to real objects. In that case the corresponding ABSTRACT_MAP*, ABSTRACT_ARRAY*, and ABSTRACT_VALUE* 159 pointers are fake non-null values, so instead of those pointers this callback can be used. 160 161 @see tmplpro_set_option_EndLoopFuncPtr 162 */ 163 164 /** \typedef typedef void (*select_loop_scope_functype) (ABSTRACT_MAP* root_param_map, int level); 165 \brief optional callback to select a loop. 166 167 \param ABSTRACT_MAP* optional pointer stored by tmplpro_set_option_root_param_map(). 168 \param int level level at which a loop will be selected. 169 170 This callback is useful for front-end implementations which does not return pointers 171 to real objects. In that case the corresponding ABSTRACT_MAP*, ABSTRACT_ARRAY*, and ABSTRACT_VALUE* 172 pointers are fake non-null values, so instead of those pointers this callback can be used. 173 174 @see tmplpro_set_option_SelectLoopScopeFuncPtr 175 */ 176 177 /** \typedef typedef const char* (*find_file_functype) (ABSTRACT_FINDFILE*, const char* filename, const char* prevfilename); 178 \brief optional callback to fine-tune the algorythm of finding template file by name. 179 180 \param ABSTRACT_FINDFILE* optional pointer stored by tmplpro_set_option_ext_writer_state(). 181 \param filename file to be found. 182 \param prevfilename fully qualified path to containing file, if any. 183 \return fully qualified path to a file to be loaded. 184 185 By default a stub is used (as of 0.82, with limited functionality). 186 187 @see tmplpro_set_option_FindFileFuncPtr 188 */ 189 190 /** \typedef typedef PSTRING (*load_file_functype) (ABSTRACT_FILTER*, const char* filename); 191 \brief optional callback to load and preprocess (filter) files. 192 193 Only called if filters option is true (set by tmplpro_set_option_filters() ). 194 195 \param ABSTRACT_FILTER* optional pointer stored by tmplpro_set_option_ext_filter_state(). 196 \param filename fully qualified path to a file to be loaded 197 (as returned by callback of find_file_functype). 198 \return PSTRING of memory area loaded. 199 200 @see tmplpro_set_option_filters 201 @see tmplpro_set_option_LoadFileFuncPtr 202 */ 203 204 /** \typedef typedef int (*unload_file_functype) (ABSTRACT_FILTER*, PSTRING memarea); 205 \brief optional callback to free memory accuired by a callback of load_file_functype. 206 207 Only called if filters option is true (set by tmplpro_set_option_filters() ). 208 209 \param ABSTRACT_FILTER* optional pointer stored by tmplpro_set_option_ext_filter_state(). 210 \param memarea pointers to loaded area 211 (as returned by callback of load_file_functype). 212 \return 0 on success, non-zero otherwise. 213 214 @see tmplpro_set_option_filters 215 @see tmplpro_set_option_UnloadFileFuncPtr 216 */ 217 218 /** \typedef typedef ABSTRACT_USERFUNC* (*is_expr_userfnc_functype) (ABSTRACT_FUNCMAP*, PSTRING name); 219 \brief optional callback for support of user-provided functions. 220 221 \param ABSTRACT_FUNCMAP* optional pointer stored by tmplpro_set_option_expr_func_map(). 222 \param name name of function 223 \return NULL if there is no user function with such a name or non-null value to be passed 224 to callback of call_expr_userfnc_functype. 225 226 \warning if is_expr_userfnc_functype callback is set, then callbacks of 227 init_expr_arglist_functype, push_expr_arglist_functype, free_expr_arglist_functype 228 and call_expr_userfnc_functype also should be set. 229 230 @see tmplpro_set_option_IsExprUserfncFuncPtr 231 */ 232 233 /** \typedef typedef ABSTRACT_ARGLIST* (*init_expr_arglist_functype) (ABSTRACT_CALLER*); 234 \brief optional callback to initialize the list of arguments for a user-provided function. 235 236 Note that if function calls are nested, then the calls to a callbacks of 237 ::init_expr_arglist_functype, ::push_expr_arglist_functype, ::free_expr_arglist_functype 238 will also be nested. 239 240 \param ABSTRACT_CALLER* optional pointer stored by tmplpro_set_option_ext_calluserfunc_state(). 241 \return value to be passed to callbacks of push_expr_arglist_functype, 242 free_expr_arglist_functype and call_expr_userfnc_functype. 243 244 @see tmplpro_set_option_InitExprArglistFuncPtr 245 */ 246 247 /** \typedef typedef void (*free_expr_arglist_functype) (ABSTRACT_ARGLIST*); 248 \brief optional callback to release the list of arguments for a user-provided function. 249 250 Note that if function calls are nested, then the calls to a callbacks of 251 ::init_expr_arglist_functype, ::push_expr_arglist_functype, ::free_expr_arglist_functype 252 will also be nested. 253 254 \param ABSTRACT_ARGLIST* optional pointer returned by callback of init_expr_arglist_functype. 255 256 @see tmplpro_set_option_FreeExprArglistFuncPtr 257 */ 258 259 /** \typedef typedef void (*push_expr_arglist_functype) (ABSTRACT_ARGLIST*, ABSTRACT_EXPRVAL*); 260 \brief optional callback to add new value to the list of arguments for a user-provided function. 261 262 Note that if function calls are nested, then the calls to a callbacks of 263 ::init_expr_arglist_functype, ::push_expr_arglist_functype, ::free_expr_arglist_functype 264 will also be nested. 265 266 \param ABSTRACT_ARGLIST* optional pointer returned by callback of init_expr_arglist_functype. 267 \param ABSTRACT_EXPRVAL* pointer required by tmplpro_get_expr_* functions to retrieve the value 268 (a place the pushed value is stored). 269 270 A value to be added to the list of arguments for a user-provided function is not passed 271 as argument to a callback of push_expr_arglist_functype. Instead, a pointer to 272 struct tmplpro_param is passed, and the callback function should discover the value's type 273 using tmplpro_get_expr_type() function, and then should retrieve the value 274 using one of the functions 275 \li tmplpro_get_expr_as_int64() 276 \li tmplpro_get_expr_as_double() 277 \li tmplpro_get_expr_as_pstring() 278 279 @see tmplpro_set_option_PushExprArglistFuncPtr 280 */ 281 282 /** \typedef typedef void (*call_expr_userfnc_functype) (ABSTRACT_CALLER*, ABSTRACT_ARGLIST*, ABSTRACT_USERFUNC*, ABSTRACT_EXPRVAL*); 283 284 \brief optional callback to call a user-provided function with a current list of arguments. 285 286 \param ABSTRACT_CALLER* optional pointer stored by tmplpro_set_option_ext_calluserfunc_state(). 287 \param ABSTRACT_ARGLIST* optional pointer returned by callback of init_expr_arglist_functype. 288 \param ABSTRACT_USERFUNC* optional pointer returned by callback of is_expr_userfnc_functype. 289 \param ABSTRACT_EXPRVAL* pointer required by tmplpro_set_expr_as_* functions 290 (a place the return value will be stored). 291 292 To return the result user function returned the callback of call_expr_userfnc_functype should 293 call one of the functions 294 \li tmplpro_set_expr_as_null() 295 \li tmplpro_set_expr_as_int64() 296 \li tmplpro_set_expr_as_double() 297 \li tmplpro_set_expr_as_string() 298 \li tmplpro_set_expr_as_pstring() 299 passing them the ABSTRACT_EXPRVAL* as argument. 300 301 @see tmplpro_set_option_CallExprUserfncFuncPtr 302 */ 303 304 /** \typedef typedef void ABSTRACT_WRITER 305 306 \brief optional pointer to be passed to a callback of ::writer_functype. 307 308 Optional pointer to store internal state for a callback of ::writer_functype. 309 If used, it should be stored beforehand with tmplpro_set_option_ext_writer_state(). 310 @see tmplpro_set_option_ext_writer_state 311 */ 312 313 /** \typedef typedef void ABSTRACT_FINDFILE 314 315 \brief optional pointer to be passed to a callback of ::find_file_functype. 316 317 Optional pointer to store internal state for a callback of ::find_file_functype. 318 If used, it should be stored beforehand with tmplpro_set_option_ext_findfile_state(). 319 @see tmplpro_set_option_ext_findfile_state 320 */ 321 322 /** \typedef typedef void ABSTRACT_FILTER 323 324 \brief optional pointer to be passed to a callback of ::load_file_functype / ::unload_file_functype. 325 326 Optional pointer to store internal state for a callback of ::load_file_functype / ::unload_file_functype. 327 If used, it should be stored beforehand with tmplpro_set_option_ext_filter_state(). 328 @see tmplpro_set_option_ext_filter_state 329 */ 330 331 /** \typedef typedef void ABSTRACT_CALLER 332 333 \brief optional pointer to be passed to a callback of ::call_expr_userfnc_functype. 334 335 Optional pointer to store internal state for a callback of ::call_expr_userfnc_functype. 336 If used, it should be stored beforehand with tmplpro_set_option_ext_calluserfunc_state(). 337 @see tmplpro_set_option_ext_calluserfunc_state 338 */ 339 340 /** \typedef typedef void ABSTRACT_DATASTATE 341 342 \brief optional pointer to be passed to data manipulation callbacks of 343 ::get_ABSTRACT_VALUE_functype, ::ABSTRACT_VALUE2ABSTRACT_ARRAY_functype, 344 ::get_ABSTRACT_ARRAY_length_functype, ::is_ABSTRACT_VALUE_true_functype, 345 ::get_ABSTRACT_MAP_functype, exit_loop_scope_functype. 346 347 Optional pointer to store internal state for a callback of 348 ::get_ABSTRACT_VALUE_functype, ::ABSTRACT_VALUE2ABSTRACT_ARRAY_functype, 349 ::get_ABSTRACT_ARRAY_length_functype, ::is_ABSTRACT_VALUE_true_functype, 350 ::get_ABSTRACT_MAP_functype, exit_loop_scope_functype. 351 If used, it should be stored beforehand with tmplpro_set_option_ext_data_state(). 352 @see tmplpro_set_option_ext_data_state 353 */ 354 355 356 /** \typedef typedef void ABSTRACT_ARRAY 357 358 \brief optional pointer representing a loop. 359 360 It is returned from a callback of ::ABSTRACT_VALUE2ABSTRACT_ARRAY_functype 361 and is passed to callbacks of ::get_ABSTRACT_ARRAY_length_functype 362 and ::get_ABSTRACT_MAP_functype. 363 */ 364 365 /** \typedef typedef void ABSTRACT_MAP 366 367 \brief optional pointer representing a root scope or a loop scope. 368 369 Pointer for the loop scope is returned from a callback of ::get_ABSTRACT_MAP_functype. 370 Pointer of the root scope should be stored beforehead using tmplpro_set_option_root_param_map(). 371 Both types of pointers are passed to callback of ::get_ABSTRACT_VALUE_functype. 372 Also, root scope pointer is passed to callbacks of ::end_loop_functype and 373 ::select_loop_scope_functype. 374 @see tmplpro_set_option_root_param_map 375 */ 376 377 /** \typedef typedef void ABSTRACT_VALUE 378 379 \brief optional pointer representing an abstract value that can be converted to a sting or loop. 380 381 It is returned from callback of ::get_ABSTRACT_VALUE_functype and passed to 382 callbacks of ::ABSTRACT_VALUE2ABSTRACT_ARRAY_functype and ::ABSTRACT_VALUE2PSTRING_functype. 383 */ 384 385 /** \typedef typedef void ABSTRACT_FUNCMAP 386 387 \brief optional pointer to be passed to a callback of ::is_expr_userfnc_functype. 388 389 If used, it should be stored beforehand with tmplpro_set_option_expr_func_map(). 390 @see tmplpro_set_option_expr_func_map 391 */ 392 393 /** \typedef typedef void ABSTRACT_ARGLIST 394 395 \brief optional pointer representing a list accumulating arguments to user function call. 396 397 It is returned from a callback of ::init_expr_arglist_functype 398 and is passed to callbacks of ::push_expr_arglist_functype, ::call_expr_userfnc_functype 399 and ::free_expr_arglist_functype. 400 */ 401 402 /** \typedef typedef void ABSTRACT_USERFUNC 403 404 \brief optional pointer representing user function. 405 406 It is returned from a callback of ::is_expr_userfnc_functype 407 and is passed to callback of ::call_expr_userfnc_functype. 408 */ 409 410 /** \typedef typedef void ABSTRACT_EXPRVAL 411 412 \brief optional pointer representing user function argument or return value. 413 414 It is passed to callbacks of ::push_expr_arglist_functype and ::call_expr_userfnc_functype. 415 */ 416 417 /* 418 * Local Variables: 419 * mode: c 420 * End: 421 */ 422