Mercurial > paster
comparison extern/libmustach/mustach.h @ 74:67b3d13a5035
pasterd: make own HTML code for good
author | David Demelier <markand@malikania.fr> |
---|---|
date | Wed, 15 Mar 2023 19:34:00 +0100 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
73:6792975da9a0 | 74:67b3d13a5035 |
---|---|
1 /* | |
2 Author: José Bollo <jobol@nonadev.net> | |
3 | |
4 https://gitlab.com/jobol/mustach | |
5 | |
6 SPDX-License-Identifier: ISC | |
7 */ | |
8 | |
9 #ifndef _mustach_h_included_ | |
10 #define _mustach_h_included_ | |
11 | |
12 struct mustach_sbuf; /* see below */ | |
13 | |
14 /** | |
15 * Current version of mustach and its derivates | |
16 */ | |
17 #define MUSTACH_VERSION 102 | |
18 #define MUSTACH_VERSION_MAJOR (MUSTACH_VERSION / 100) | |
19 #define MUSTACH_VERSION_MINOR (MUSTACH_VERSION % 100) | |
20 | |
21 /** | |
22 * Maximum nested imbrications supported | |
23 */ | |
24 #define MUSTACH_MAX_DEPTH 256 | |
25 | |
26 /** | |
27 * Maximum length of tags in mustaches {{...}} | |
28 */ | |
29 #define MUSTACH_MAX_LENGTH 4096 | |
30 | |
31 /** | |
32 * Maximum length of delimitors (2 normally but extended here) | |
33 */ | |
34 #define MUSTACH_MAX_DELIM_LENGTH 8 | |
35 | |
36 /** | |
37 * Flags specific to mustach core | |
38 */ | |
39 #define Mustach_With_NoExtensions 0 | |
40 #define Mustach_With_Colon 1 | |
41 #define Mustach_With_EmptyTag 2 | |
42 #define Mustach_With_AllExtensions 3 | |
43 | |
44 /* | |
45 * Definition of error codes returned by mustach | |
46 */ | |
47 #define MUSTACH_OK 0 | |
48 #define MUSTACH_ERROR_SYSTEM -1 | |
49 #define MUSTACH_ERROR_UNEXPECTED_END -2 | |
50 #define MUSTACH_ERROR_EMPTY_TAG -3 | |
51 #define MUSTACH_ERROR_TAG_TOO_LONG -4 | |
52 #define MUSTACH_ERROR_BAD_SEPARATORS -5 | |
53 #define MUSTACH_ERROR_TOO_DEEP -6 | |
54 #define MUSTACH_ERROR_CLOSING -7 | |
55 #define MUSTACH_ERROR_BAD_UNESCAPE_TAG -8 | |
56 #define MUSTACH_ERROR_INVALID_ITF -9 | |
57 #define MUSTACH_ERROR_ITEM_NOT_FOUND -10 | |
58 #define MUSTACH_ERROR_PARTIAL_NOT_FOUND -11 | |
59 #define MUSTACH_ERROR_UNDEFINED_TAG -12 | |
60 | |
61 /* | |
62 * You can use definition below for user specific error | |
63 * | |
64 * The macro MUSTACH_ERROR_USER is involutive so for any value | |
65 * value = MUSTACH_ERROR_USER(MUSTACH_ERROR_USER(value)) | |
66 */ | |
67 #define MUSTACH_ERROR_USER_BASE -100 | |
68 #define MUSTACH_ERROR_USER(x) (MUSTACH_ERROR_USER_BASE-(x)) | |
69 #define MUSTACH_IS_ERROR_USER(x) (MUSTACH_ERROR_USER(x) >= 0) | |
70 | |
71 /** | |
72 * mustach_itf - pure abstract mustach - interface for callbacks | |
73 * | |
74 * The functions enter and next should return 0 or 1. | |
75 * | |
76 * All other functions should normally return MUSTACH_OK (zero). | |
77 * | |
78 * If any function returns a negative value, it means an error that | |
79 * stop the processing and that is reported to the caller. Mustach | |
80 * also has its own error codes. Using the macros MUSTACH_ERROR_USER | |
81 * and MUSTACH_IS_ERROR_USER could help to avoid clashes. | |
82 * | |
83 * @start: If defined (can be NULL), starts the mustach processing | |
84 * of the closure, called at the very beginning before any | |
85 * mustach processing occurs. | |
86 * | |
87 * @put: If defined (can be NULL), writes the value of 'name' | |
88 * to 'file' with 'escape' or not. | |
89 * As an extension (see NO_ALLOW_EMPTY_TAG), the 'name' can be | |
90 * the empty string. In that later case an implementation can | |
91 * return MUSTACH_ERROR_EMPTY_TAG to refuse empty names. | |
92 * If NULL and 'get' NULL the error MUSTACH_ERROR_INVALID_ITF | |
93 * is returned. | |
94 * | |
95 * @enter: Enters the section of 'name' if possible. | |
96 * Musts return 1 if entered or 0 if not entered. | |
97 * When 1 is returned, the function 'leave' will always be called. | |
98 * Conversely 'leave' is never called when enter returns 0 or | |
99 * a negative value. | |
100 * When 1 is returned, the function must activate the first | |
101 * item of the section. | |
102 * | |
103 * @next: Activates the next item of the section if it exists. | |
104 * Musts return 1 when the next item is activated. | |
105 * Musts return 0 when there is no item to activate. | |
106 * | |
107 * @leave: Leaves the last entered section | |
108 * | |
109 * @partial: If defined (can be NULL), returns in 'sbuf' the content of the | |
110 * partial of 'name'. @see mustach_sbuf | |
111 * If NULL but 'get' not NULL, 'get' is used instead of partial. | |
112 * If NULL and 'get' NULL and 'put' not NULL, 'put' is called with | |
113 * a true FILE. | |
114 * | |
115 * @emit: If defined (can be NULL), writes the 'buffer' of 'size' with 'escape'. | |
116 * If NULL the standard function 'fwrite' is used with a true FILE. | |
117 * If not NULL that function is called instead of 'fwrite' to output | |
118 * text. | |
119 * It implies that if you define either 'partial' or 'get' callback, | |
120 * the meaning of 'FILE *file' is abstract for mustach's process and | |
121 * then you can use 'FILE*file' pass any kind of pointer (including NULL) | |
122 * to the function 'fmustach'. An example of a such behaviour is given by | |
123 * the implementation of 'mustach_json_c_write'. | |
124 * | |
125 * @get: If defined (can be NULL), returns in 'sbuf' the value of 'name'. | |
126 * As an extension (see NO_ALLOW_EMPTY_TAG), the 'name' can be | |
127 * the empty string. In that later case an implementation can | |
128 * return MUSTACH_ERROR_EMPTY_TAG to refuse empty names. | |
129 * If 'get' is NULL and 'put' NULL the error MUSTACH_ERROR_INVALID_ITF | |
130 * is returned. | |
131 * | |
132 * @stop: If defined (can be NULL), stops the mustach processing | |
133 * of the closure, called at the very end after all mustach | |
134 * processing occurered. The status returned by the processing | |
135 * is passed to the stop. | |
136 * | |
137 * The array below summarize status of callbacks: | |
138 * | |
139 * FULLY OPTIONAL: start partial | |
140 * MANDATORY: enter next leave | |
141 * COMBINATORIAL: put emit get | |
142 * | |
143 * Not definig a MANDATORY callback returns error MUSTACH_ERROR_INVALID_ITF. | |
144 * | |
145 * For COMBINATORIAL callbacks the array below summarize possible combinations: | |
146 * | |
147 * combination : put : emit : get : abstract FILE | |
148 * -------------+---------+---------+---------+----------------------- | |
149 * HISTORIC : defined : NULL : NULL : NO: standard FILE | |
150 * MINIMAL : NULL : NULL : defined : NO: standard FILE | |
151 * CUSTOM : NULL : defined : defined : YES: abstract FILE | |
152 * DUCK : defined : NULL : defined : NO: standard FILE | |
153 * DANGEROUS : defined : defined : any : YES or NO, depends on 'partial' | |
154 * INVALID : NULL : any : NULL : - | |
155 * | |
156 * The DUCK case runs on one leg. 'get' is not used if 'partial' is defined | |
157 * but is used for 'partial' if 'partial' is NULL. Thus for clarity, do not use | |
158 * it that way but define 'partial' and let 'get' be NULL. | |
159 * | |
160 * The DANGEROUS case is special: it allows abstract FILE if 'partial' is defined | |
161 * but forbids abstract FILE when 'partial' is NULL. | |
162 * | |
163 * The INVALID case returns error MUSTACH_ERROR_INVALID_ITF. | |
164 */ | |
165 struct mustach_itf { | |
166 int (*start)(void *closure); | |
167 int (*put)(void *closure, const char *name, int escape, FILE *file); | |
168 int (*enter)(void *closure, const char *name); | |
169 int (*next)(void *closure); | |
170 int (*leave)(void *closure); | |
171 int (*partial)(void *closure, const char *name, struct mustach_sbuf *sbuf); | |
172 int (*emit)(void *closure, const char *buffer, size_t size, int escape, FILE *file); | |
173 int (*get)(void *closure, const char *name, struct mustach_sbuf *sbuf); | |
174 void (*stop)(void *closure, int status); | |
175 }; | |
176 | |
177 /** | |
178 * mustach_sbuf - Interface for handling zero terminated strings | |
179 * | |
180 * That structure is used for returning zero terminated strings -in 'value'- | |
181 * to mustach. The callee can provide a function for releasing the returned | |
182 * 'value'. Three methods for releasing the string are possible. | |
183 * | |
184 * 1. no release: set either 'freecb' or 'releasecb' with NULL (done by default) | |
185 * 2. release without closure: set 'freecb' to its expected value | |
186 * 3. release with closure: set 'releasecb' and 'closure' to their expected values | |
187 * | |
188 * @value: The value of the string. That value is not changed by mustach -const-. | |
189 * | |
190 * @freecb: The function to call for freeing the value without closure. | |
191 * For convenience, signature of that callback is compatible with 'free'. | |
192 * Can be NULL. | |
193 * | |
194 * @releasecb: The function to release with closure. | |
195 * Can be NULL. | |
196 * | |
197 * @closure: The closure to use for 'releasecb'. | |
198 * | |
199 * @length: Length of the value or zero if unknown and value null terminated. | |
200 * To return the empty string, let it to zero and let value to NULL. | |
201 */ | |
202 struct mustach_sbuf { | |
203 const char *value; | |
204 union { | |
205 void (*freecb)(void*); | |
206 void (*releasecb)(const char *value, void *closure); | |
207 }; | |
208 void *closure; | |
209 size_t length; | |
210 }; | |
211 | |
212 /** | |
213 * mustach_file - Renders the mustache 'template' in 'file' for 'itf' and 'closure'. | |
214 * | |
215 * @template: the template string to instantiate | |
216 * @length: length of the template or zero if unknown and template null terminated | |
217 * @itf: the interface to the functions that mustach calls | |
218 * @closure: the closure to pass to functions called | |
219 * @file: the file where to write the result | |
220 * | |
221 * Returns 0 in case of success, -1 with errno set in case of system error | |
222 * a other negative value in case of error. | |
223 */ | |
224 extern int mustach_file(const char *template, size_t length, const struct mustach_itf *itf, void *closure, int flags, FILE *file); | |
225 | |
226 /** | |
227 * mustach_fd - Renders the mustache 'template' in 'fd' for 'itf' and 'closure'. | |
228 * | |
229 * @template: the template string to instantiate | |
230 * @length: length of the template or zero if unknown and template null terminated | |
231 * @itf: the interface to the functions that mustach calls | |
232 * @closure: the closure to pass to functions called | |
233 * @fd: the file descriptor number where to write the result | |
234 * | |
235 * Returns 0 in case of success, -1 with errno set in case of system error | |
236 * a other negative value in case of error. | |
237 */ | |
238 extern int mustach_fd(const char *template, size_t length, const struct mustach_itf *itf, void *closure, int flags, int fd); | |
239 | |
240 /** | |
241 * mustach_mem - Renders the mustache 'template' in 'result' for 'itf' and 'closure'. | |
242 * | |
243 * @template: the template string to instantiate | |
244 * @length: length of the template or zero if unknown and template null terminated | |
245 * @itf: the interface to the functions that mustach calls | |
246 * @closure: the closure to pass to functions called | |
247 * @result: the pointer receiving the result when 0 is returned | |
248 * @size: the size of the returned result | |
249 * | |
250 * Returns 0 in case of success, -1 with errno set in case of system error | |
251 * a other negative value in case of error. | |
252 */ | |
253 extern int mustach_mem(const char *template, size_t length, const struct mustach_itf *itf, void *closure, int flags, char **result, size_t *size); | |
254 | |
255 /*************************************************************************** | |
256 * compatibility with version before 1.0 | |
257 */ | |
258 #ifdef __GNUC__ | |
259 #define DEPRECATED_MUSTACH(func) func __attribute__ ((deprecated)) | |
260 #elif defined(_MSC_VER) | |
261 #define DEPRECATED_MUSTACH(func) __declspec(deprecated) func | |
262 #elif !defined(DEPRECATED_MUSTACH) | |
263 #pragma message("WARNING: You need to implement DEPRECATED_MUSTACH for this compiler") | |
264 #define DEPRECATED_MUSTACH(func) func | |
265 #endif | |
266 /** | |
267 * OBSOLETE use mustach_file | |
268 * | |
269 * fmustach - Renders the mustache 'template' in 'file' for 'itf' and 'closure'. | |
270 * | |
271 * @template: the template string to instantiate, null terminated | |
272 * @itf: the interface to the functions that mustach calls | |
273 * @closure: the closure to pass to functions called | |
274 * @file: the file where to write the result | |
275 * | |
276 * Returns 0 in case of success, -1 with errno set in case of system error | |
277 * a other negative value in case of error. | |
278 */ | |
279 DEPRECATED_MUSTACH(extern int fmustach(const char *template, const struct mustach_itf *itf, void *closure, FILE *file)); | |
280 | |
281 /** | |
282 * OBSOLETE use mustach_fd | |
283 * | |
284 * fdmustach - Renders the mustache 'template' in 'fd' for 'itf' and 'closure'. | |
285 * | |
286 * @template: the template string to instantiate, null terminated | |
287 * @itf: the interface to the functions that mustach calls | |
288 * @closure: the closure to pass to functions called | |
289 * @fd: the file descriptor number where to write the result | |
290 * | |
291 * Returns 0 in case of success, -1 with errno set in case of system error | |
292 * a other negative value in case of error. | |
293 */ | |
294 DEPRECATED_MUSTACH(extern int fdmustach(const char *template, const struct mustach_itf *itf, void *closure, int fd)); | |
295 | |
296 /** | |
297 * OBSOLETE use mustach_mem | |
298 * | |
299 * mustach - Renders the mustache 'template' in 'result' for 'itf' and 'closure'. | |
300 * | |
301 * @template: the template string to instantiate, null terminated | |
302 * @itf: the interface to the functions that mustach calls | |
303 * @closure: the closure to pass to functions called | |
304 * @result: the pointer receiving the result when 0 is returned | |
305 * @size: the size of the returned result | |
306 * | |
307 * Returns 0 in case of success, -1 with errno set in case of system error | |
308 * a other negative value in case of error. | |
309 */ | |
310 DEPRECATED_MUSTACH(extern int mustach(const char *template, const struct mustach_itf *itf, void *closure, char **result, size_t *size)); | |
311 | |
312 #endif | |
313 |