/*! \file tmplpro.h
\brief libhtmltmplpro API header.
An official libhtmltmplpro API header.
\author Igor Vlasenko <vlasenko@imath.kiev.ua>
*/
#ifndef _TMPLPRO_H
#define _TMPLPRO_H 1
#include "pabidecl.h"
#include "pstring.h"
#include "exprtype.h"
#include "pabstract.h"
#include "proparam.h"
/*
* generic load/first use library and unload/last use library hooks.
*/
TMPLPRO_API void APICALL tmplpro_procore_init(void);
TMPLPRO_API void APICALL tmplpro_procore_done(void);
TMPLPRO_API const char* APICALL tmplpro_version(void);
struct tmplpro_param;
/*
* Constructor and destructor of tmplpro_param.
* Note that struct tmplpro_param is not part of the interface
* and is subject to change without notice.
*/
TMPLPRO_API struct tmplpro_param* APICALL tmplpro_param_init(void);
TMPLPRO_API void APICALL tmplpro_param_free(struct tmplpro_param*);
TMPLPRO_API int APICALL tmplpro_exec_tmpl (struct tmplpro_param*);
TMPLPRO_API PSTRING APICALL tmplpro_tmpl2pstring (struct tmplpro_param *param, int *exitcode);
TMPLPRO_API void APICALL tmplpro_clear_option_param_map(struct tmplpro_param *param);
TMPLPRO_API int APICALL tmplpro_count_option_param_map(struct tmplpro_param *param);
TMPLPRO_API int APICALL tmplpro_push_option_param_map(struct tmplpro_param *param, ABSTRACT_MAP* map, EXPR_int64 flags);
TMPLPRO_API int APICALL tmplpro_get_int_option(struct tmplpro_param* param, const char *p, int* failure_ptr);
TMPLPRO_API int APICALL tmplpro_set_int_option(struct tmplpro_param* param, const char *p, int value);
TMPLPRO_API void APICALL tmplpro_reset_int_options(struct tmplpro_param* param);
TMPLPRO_API int APICALL tmplpro_errno(struct tmplpro_param* param);
TMPLPRO_API const char* APICALL tmplpro_errmsg(struct tmplpro_param* param);
TMPLPRO_API int APICALL tmplpro_set_log_file(struct tmplpro_param* param, const char* logfilename);
TMPLPRO_API size_t APICALL tmplpro_param_allocated_memory_info(struct tmplpro_param* param);
struct exprval;
TMPLPRO_API void APICALL tmplpro_set_expr_as_int64 (ABSTRACT_EXPRVAL*,EXPR_int64);
TMPLPRO_API void APICALL tmplpro_set_expr_as_double (ABSTRACT_EXPRVAL*,double);
TMPLPRO_API void APICALL tmplpro_set_expr_as_string (ABSTRACT_EXPRVAL*, const char*);
TMPLPRO_API void APICALL tmplpro_set_expr_as_pstring (ABSTRACT_EXPRVAL*,PSTRING);
TMPLPRO_API void APICALL tmplpro_set_expr_as_null (ABSTRACT_EXPRVAL*);
TMPLPRO_API int APICALL tmplpro_get_expr_type (ABSTRACT_EXPRVAL*);
TMPLPRO_API EXPR_int64 APICALL tmplpro_get_expr_as_int64 (ABSTRACT_EXPRVAL*);
TMPLPRO_API double APICALL tmplpro_get_expr_as_double (ABSTRACT_EXPRVAL*);
TMPLPRO_API PSTRING APICALL tmplpro_get_expr_as_pstring (ABSTRACT_EXPRVAL*);
#define ASK_NAME_DEFAULT 0
#define ASK_NAME_AS_IS 1
#define ASK_NAME_LOWERCASE 2
#define ASK_NAME_UPPERCASE 4
#define ASK_NAME_MASK (ASK_NAME_AS_IS|ASK_NAME_LOWERCASE|ASK_NAME_UPPERCASE)
/* future compatibility: not yet implemented */
#define ASK_NAME_CAPITALIZED 8
#define ASK_NAME_LCFIRST 16
#define ASK_NAME_UCFIRST 32
/* define ASK_NAME_MASK (ASK_NAME_AS_IS|ASK_NAME_LOWERCASE|ASK_NAME_UPPERCASE|ASK_NAME_CAPITALIZED|ASK_NAME_LCFIRST|ASK_NAME_UCFIRST) */
#define HTML_TEMPLATE_OPT_ESCAPE_NO 0
#define HTML_TEMPLATE_OPT_ESCAPE_HTML 1
#define HTML_TEMPLATE_OPT_ESCAPE_URL 2
#define HTML_TEMPLATE_OPT_ESCAPE_JS 3
#endif /* tmplpro.h */
/*! \fn void tmplpro_procore_init(void);
\brief generic load library/first use initializer.
Initializer of global internal structures.
Should be called before first use of the library.
\warning May not be thread safe. Should be called once.
*/
/*! \fn void tmplpro_procore_done(void);
\brief generic load/first use library and unload/last use library hooks.
Deinitializer of global internal structures.
Should be called before unloading the library.
\warning May not be thread safe. Should be called once.
*/
/*! \fn const char* tmplpro_version(void);
\brief version of the library
\return version string.
*/
/*! \fn struct tmplpro_param* tmplpro_param_init(void);
\brief Constructor of tmplpro_param.
*/
/*! \fn void tmplpro_param_free(struct tmplpro_param*);
\brief Destructor of tmplpro_param.
*/
/*! \fn int tmplpro_exec_tmpl (struct tmplpro_param*);
\brief main method of libhtmltmplpro.
*/
/*! \fn PSTRING tmplpro_tmpl2pstring (struct tmplpro_param*, int* exitcode);
\brief main method of libhtmltmplpro. Returns processed template as a C string.
Note that returned PSTRING resides in an internal tmplpro buffer.
A caller should copy its contents as it will be rewritten in the next
call to tmplpro_tmpl2pstring. It is libhtmltmplpro ( tmplpro_param_free() )
responsibility to free the buffer's memory during the destruction
of param object.
*/
/*! \fn void tmplpro_set_expr_as_int64 (ABSTRACT_EXPRVAL*,EXPR_int64);
\brief method to return int64 value from callback of call_expr_userfnc_functype.
It should only be used in a callback of call_expr_userfnc_functype.
*/
/*! \fn void tmplpro_set_expr_as_double (ABSTRACT_EXPRVAL*,double);
\brief method to return double value from callback of call_expr_userfnc_functype.
It should only be used in a callback of call_expr_userfnc_functype.
*/
/*! \fn void tmplpro_set_expr_as_string (ABSTRACT_EXPRVAL*,char*);
\brief method to return C string value from callback of call_expr_userfnc_functype.
It should only be used in a callback of call_expr_userfnc_functype.
*/
/*! \fn void tmplpro_set_expr_as_pstring (ABSTRACT_EXPRVAL*,PSTRING);
\brief method to return PSTRING value from callback of call_expr_userfnc_functype.
It should only be used in a callback of call_expr_userfnc_functype.
*/
/*! \fn void tmplpro_set_expr_as_null (ABSTRACT_EXPRVAL*);
\brief method to return null from callback of call_expr_userfnc_functype.
It should only be used in a callback of call_expr_userfnc_functype.
*/
/*! \fn EXPR_int64 tmplpro_get_expr_as_int64 (ABSTRACT_EXPRVAL*);
\brief method for callback of push_expr_arglist_functype to retrieve a value as int64.
*/
/*! \fn double tmplpro_get_expr_as_double (ABSTRACT_EXPRVAL*);
\brief method for callback of push_expr_arglist_functype to retrieve a value as double.
It should only be used in a callback of push_expr_arglist_functype.
*/
/*! \fn PSTRING tmplpro_get_expr_as_pstring (ABSTRACT_EXPRVAL*);
\brief method for callback of push_expr_arglist_functype to retrieve a value as PSTRING.
It should only be used in a callback of push_expr_arglist_functype.
*/
/*! \fn int tmplpro_get_expr_type (ABSTRACT_EXPRVAL*);
\brief method for callback of push_expr_arglist_functype to determine the type of a value.
It should only be used in a callback of push_expr_arglist_functype.
*/
/*! \fn int tmplpro_get_int_option(struct tmplpro_param* param, const char *p, int* failure_ptr);
\brief string-based option getter, useful for dynamic languages.
non-NULL failure_ptr is used to return exit code.
Note that exit code is also available via tmplpro_errno/tmplpro_errmsg.
Non-null exit code indicates failure (invalid option).
*/
/*! \fn int tmplpro_set_int_option(struct tmplpro_param* param, const char *p, int val);
\brief string-based option setter, useful for dynamic languages.
returns exit code, also available via tmplpro_errno/tmplpro_errmsg.
Non-null exit code indicates failure (invalid option or invalid option value).
*/
/*! \fn void tmplpro_reset_int_options(struct tmplpro_param* param);
\brief reset integer userspace options to their default values.
*/
/*! \fn int tmplpro_errno(struct tmplpro_param* param);
\brief exit code of the last function call.
Exit code of the last function call.
(For functions that return exit status).
*/
/*! \fn const char* tmplpro_errmsg(struct tmplpro_param* param);
\brief exit message of the last function call.
A exit status message of the last function call.
(For functions that return exit status).
*/
/** \struct tmplpro_param
\brief main htmltmplpro class.
Main htmltmplpro class. Passed by reference.
Its internal structure is hidden and is not part of the API.
Constructor is tmplpro_param_init()
Destructor is tmplpro_param_free()
Main methods are tmplpro_exec_tmpl(), tmplpro_tmpl2pstring()
*/
/** \struct exprval
\brief EXPR="..." variable class.
EXPR="..." expression variable class. Passed by reference.
Its internal structure is hidden and is not part of the API.
It can contain string, 64-bit integer or double.
Methods:
\li tmplpro_set_expr_as_null(ABSTRACT_EXPRVAL*)
\li tmplpro_set_expr_as_int64(ABSTRACT_EXPRVAL*,EXPR_int64)
\li tmplpro_set_expr_as_double(ABSTRACT_EXPRVAL*,double)
\li tmplpro_set_expr_as_string(ABSTRACT_EXPRVAL*,const char*)
\li tmplpro_set_expr_as_pstring(ABSTRACT_EXPRVAL*,PSTRING)
\li tmplpro_get_expr_type(ABSTRACT_EXPRVAL*)
\li tmplpro_get_expr_as_int64(ABSTRACT_EXPRVAL*)
\li tmplpro_get_expr_as_double(ABSTRACT_EXPRVAL*)
\li tmplpro_get_expr_as_pstring(ABSTRACT_EXPRVAL*)
*/
/*! \mainpage
*
* \section intro_sec Introduction
*
* \include README
*
* \section compile_sec Compilation
*
* \subsection autoconf
*
* \subsection CMake
* etc...
*
* \section api_sec History of API and ABI changes
*
* \include API
*
*/