Usage information is added
[tedtools.git] / template.h
1 /*
2  * Copyright (c) 2008 Teodor Sigaev <teodor@sigaev.ru>
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  *        notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  *        notice, this list of conditions and the following disclaimer in the
12  *        documentation and/or other materials provided with the distribution.
13  * 3. Neither the name of the author nor the names of any co-contributors
14  *        may be used to endorse or promote products derived from this software
15  *        without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY CONTRIBUTORS ``AS IS'' AND ANY EXPRESS
18  * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
19  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20  * ARE DISCLAIMED. IN NO EVENT SHALL CONTRIBUTORS BE LIABLE FOR ANY
21  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
23  * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
25  * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
26  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
27  * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28  */
29
30 /******************************************************************************
31  *                         Html template library                              *
32  ******************************************************************************
33  ******************************************************************************
34  *                                  SYNTAX                                    *
35  ******************************************************************************
36  * <% EXPRESSION , "FORMAT"] [# "DEFAULTVALUE"] [|(h|u)]%>
37  *    - format value should be as in strftime for time value and printf
38  *      for all other. Currently, bool values have only "true"/"false"
39  *      string values
40  * <@IF EXPRESSION @>
41  * <@ELSE@>
42  * <@ENDIF@>
43  *
44  * Expression is classical with support following:
45  *    -  ['^'] VARNAME     
46  *              variable defined from C-code. Mark '^' means global 
47  *       variable, not local in loop.
48  *    -  expression (+|-|*|/|%) expression
49  *               ariphmetic operations
50  *    -  expression ( || | && ) expression
51  *               ! expression
52  *       logical OR, AND and NOT
53  *    - expression ( < | <= | == | >= | > | != | <> ) expression 
54  *              compare expression
55  *    - LENGTH(expression)
56  *      computes length of string
57  *    - DEFINED(expression)
58  *      returns true if expression is defined
59  *        - expression ? expression : expression
60  *    - ( expression )
61  *    - USERDEFINEDFUNCTION( [expression[,expression[...]]] )
62  *      User defined function call. Function should be defined at 
63  *      C-level.
64  *
65  * <@LOOP MARKNAME@>
66  * <@ENDLOOP@>
67  * Loop has predefined variables:
68  *    __FIRST   - true for first iteration
69  *    __LAST    - true for last iteration
70  *    __COUNTER - iteration's number
71  *    __SIZE    - number of iterations
72  *    __ODD     - true for odd iteraion
73  *    __EVEN    - true for even iteraion
74  *
75  * <& FILENAME &>
76  *
77  * <# comment #>
78  *
79  ******************************************************************************
80  *                                C-Interface                                 *
81  ******************************************************************************
82  * - setTemplateValueInt
83  *   setTemplateValueString
84  *   setTemplateValueTime
85  *   setTemplateValueBool
86  *   setTemplateValueDouble
87  *   setTemplateValueUndefined
88  *   Sets varibale's value
89  * - addTemplateRow
90  *   Add one iteration to the pointed loop. Local variable in loop should 
91  *   pointed with predecence loop's mark(s) separated by dot. Example:
92  *       HTML:
93  *   <@Loop outerLoop@>
94  *              <% var1 %>
95  *      <@Loop innerLoop@>
96  *                      <% var2 %>
97  *              <@endloop@>
98  *       <@endloop@>
99  *      C:
100  *      addTemplateRow("outerLoop");
101  *  setTemplateValueBool("outerLoop.var1");
102  *      addTemplateRow("innerLoop");
103  *  setTemplateValueBool("outerLoop.innerLoop.var2");
104  *
105  ******************************************************************************
106  *                               Memory management                            * 
107  ******************************************************************************
108  * Unfortunatly, I'm too lazy to unify memory usage by several pieces
109  * in library. So, library uses mixed plain malloc and memory context
110  * concepts (tmalloc.h).
111  * To work with library it's needed to allocate persitent memory context
112  * for initTemplate() call and temprorary memory context for usual work.
113  * after printTemplate is called it's needed to call resetTemplate() and 
114  * then resetMemoryContext() for second context. 
115  * 
116  ******************************************************************************/
117
118 #ifndef __TEMPLATE_H__
119 #define __TEMPLATE_H__
120
121 #include <sys/types.h>
122 #include <time.h>
123 #include "glist.h"
124 #include "sfxstr.h"
125 #include "tmalloc.h"
126
127 typedef enum TemplateNodeType {
128         /* node tree types */
129         TextNode = 100,
130         VariableNode,
131         IncludeNode,
132         LoopNode,
133         ConditionNode,
134         CollectionNode,
135         ExpressionNode,
136         PrintNode,
137         ConstNode,
138
139         /* value's types of variables */
140         valueInt = 200, /* smallest of any values type */
141         valueString,
142         valueTime,
143         valueBool,
144         valueDouble,
145         valuePointer
146 } TemplateNodeType;
147
148 #define TND_HTMLESCAPE          (0x0001)
149 #define TND_URLESCAPE           (0x0002)
150 #define TND_GLOBAL                      (0x0004)
151
152 #define TND___FIRST                     (0x0008)
153 #define TND___LAST                      (0x0010)
154 #define TND___COUNTER           (0x0020)
155 #define TND___SIZE                      (0x0040)
156 #define TND___ODD                       (0x0080)
157 #define TND___EVEN                      (0x0100)
158
159 #define TND_DEFINED                     (0x0200)
160
161 #define TND__SPECIALMASK        (TND___FIRST | TND___LAST | TND___COUNTER | TND___SIZE | TND___ODD | TND___EVEN)
162
163 typedef struct TemplateData *Template;
164
165 typedef struct TemplateNodeData *TemplateNode;
166
167 typedef struct VariableValueData * VariableValue;
168 typedef struct VariableValueData {
169         TemplateNodeType        type; /* should be first, see resetTemplate/freeTemplate */
170         int                                     flags;
171         union {
172                 int                             intValue;
173                 char                    *stringValue;
174                 time_t                  timeValue;
175                 int                             boolValue;
176                 double                  doubleValue;
177                 VariableValue   ptrValue; /* special value to handle loop variables,
178                                                                          points to members of loopValues */
179         } value;
180 } VariableValueData;
181
182
183 typedef struct executeFunctionDescData *executeFunctionDesc;
184 typedef struct executeFunctionDescData {
185         char                    *name;
186         int                             nargs; /* -1 - variable number */
187         VariableValue   (*execFn)(Template, int, VariableValue*);
188 } executeFunctionDescData;
189
190 typedef struct LoopInstanceData * LoopInstance;
191 typedef struct LoopInstanceData {
192         int                             nrow;
193         GList                   *rowValues;
194 } LoopInstanceData;
195
196 typedef struct  TemplateNodeData {
197         TemplateNodeType        type; /* should be first, see resetTemplate/freeTemplate */
198
199         union {
200                 /* TextNode */
201                 struct {
202                         char    *value;
203                         int             valueLength;
204                 } text;
205
206                 /* VariableNode */
207                 struct {
208                         char                    *varName;
209                         int                             varNameLength;
210                         VariableValue   value;
211                         int                             flags;
212                 } variable;
213
214                 /* ExpressionNode */
215                 struct {
216                         VariableValue           *argsValue;
217                         int                                     nargs;
218                         char                            *functionName;
219                         executeFunctionDesc     function;
220                         GList                           *argsNode; /* list of nodes after parsing 
221                                                                                                 but before compile */   
222                 } expression;
223
224                 /* ConstNode */
225                 VariableValueData               value;
226
227                 /* PrintNode */
228                 struct {
229                         TemplateNode    expressionNode;
230                         char                    *formatValue;
231                         char                    *defaultValue;
232                         int                             flags;
233                 } print; 
234
235                 /* IncludeNode */
236                 char    *includeFile;
237
238                 /* LoopNode */
239                 struct {
240                         char                    *varName;
241                         int                     varNameLength;
242                         TemplateNode    bodyNode;
243                         int                             counter;
244                         GList                   *childrenLoop;  /* to reset instance  */
245                         GList                   *listVarValues; /* list of loop variables */
246                         GList                   *listInstance;
247                 } loop;
248
249                 /* ConditionNode */
250                 struct {
251                         TemplateNode    expressionNode;
252                         TemplateNode    ifNode;
253                         TemplateNode    elseNode;
254                 } condition;
255
256                 /* CollectionNode */
257                 GList   *children;
258         } nodeData;
259         
260 } TemplateNodeData;
261
262 /* prints result */
263 typedef void  (*outFn)(char *, int);
264
265 typedef char*   (*urlEscapeFn)(char *, int * /* in/out */);
266 typedef char*   (*htmlEscapeFn)(char *, int * /* in/out */);
267
268 typedef struct TemplateData {
269         TemplateNode            tree;
270         MemoryContext           *templateContext;
271         SFSTree                         variables;
272         outFn                           printString;
273         urlEscapeFn                     urlEscape;
274         htmlEscapeFn            htmlEscape;
275         executeFunctionDesc functions;
276 } TemplateData;
277
278 int parseTemplateFile(Template tmpl, char* filename );  /* return non-zero if error */
279 int initTemplate( Template tmpl, MemoryContext *mc, executeFunctionDesc functions, char *basedir, char *filename );
280 void freeTemplate( Template tmpl );
281 void resetTemplate( Template tmpl );
282 int printTemplate( Template tmpl );
283
284 #define TVAR_OK                 (0)
285 #define TVAR_NOTFOUND   (1)
286 #define TVAR_FORBIDDEN  (2)
287 #define TVAR_NOROW              (3)
288 #define TVAR_LOOPMARK   (4)
289
290 int setTemplateValueInt( Template tmpl, char * key, int val );
291 int setTemplateValueString( Template tmpl, char * key, char * val );
292 int setTemplateValueTime( Template tmpl, char * key, time_t val );
293 int setTemplateValueBool( Template tmpl, char * key, int val );
294 int setTemplateValueUndefined( Template tmpl, char * key );
295 int setTemplateValueDouble( Template tmpl, char * key, double val );
296 int addTemplateRow( Template tmpl, char * key );
297
298 void dumpTemplate( Template tmpl );
299 #endif