Mercurial > paster

comparison extern/libmustach/mustach.h @ 74:67b3d13a5035

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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