Mercurial > sci

comparison extern/libmustache4c/mustache.h @ 26:7e10cace67a3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
scid: add basic mustache support
author David Demelier <markand@malikania.fr>
date Tue, 02 Aug 2022 13:24:13 +0200
parents
children
comparison
equal deleted inserted replaced
25:c40f98360ac9 26:7e10cace67a3
1 /*
2 * Mustache4C
3 * (http://github.com/mity/mustache4c)
4 *
5 * Copyright (c) 2017 Martin Mitas
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a
8 * copy of this software and associated documentation files (the "Software"),
9 * to deal in the Software without restriction, including without limitation
10 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
11 * and/or sell copies of the Software, and to permit persons to whom the
12 * Software is furnished to do so, subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
18 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
22 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
23 * IN THE SOFTWARE.
24 */
25
26 #ifndef MUSTACHE4C_H
27 #define MUSTACHE4C_H
28
29 #include <stdlib.h>
30
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34
35
36 typedef struct MUSTACHE_TEMPLATE MUSTACHE_TEMPLATE;
37
38
39 #define MUSTACHE_ERR_SUCCESS (0)
40 #define MUSTACHE_ERR_DANGLINGTAGOPENER (1)
41 #define MUSTACHE_ERR_DANGLINGTAGCLOSER (2)
42 #define MUSTACHE_ERR_INCOMPATIBLETAGCLOSER (3)
43 #define MUSTACHE_ERR_NOTAGNAME (4)
44 #define MUSTACHE_ERR_INVALIDTAGNAME (5)
45 #define MUSTACHE_ERR_DANGLINGSECTIONOPENER (6)
46 #define MUSTACHE_ERR_DANGLINGSECTIONCLOSER (7)
47 #define MUSTACHE_ERR_SECTIONNAMEMISMATCH (8)
48 #define MUSTACHE_ERR_SECTIONOPENERHERE (9)
49 #define MUSTACHE_ERR_INVALIDDELIMITERS (10)
50
51
52 typedef struct MUSTACHE_PARSER {
53 void (*parse_error)(int /*err_code*/, const char* /*msg*/,
54 unsigned /*line*/, unsigned /*column*/, void* /*parser_data*/);
55 } MUSTACHE_PARSER;
56
57
58 /**
59 * An interface the application has to implement, in order to output the result
60 * of template processing.
61 */
62 typedef struct MUSTACHE_RENDERER {
63 /**
64 * Called to output the given text as it is.
65 *
66 * Non-zero return value aborts mustache_process().
67 */
68 int (*out_verbatim)(const char* /*output*/, size_t /*size*/, void* /*renderer_data*/);
69
70 /**
71 * Called to output the given text. Implementation has to escape it
72 * appropriately with respect to the output format. E.g. for HTML output,
73 * "<" should be translated to "&lt;" etc.
74 *
75 * Non-zero return value aborts mustache_process().
76 *
77 * If no escaping is desired, it can be pointer to the same function
78 * as out_verbatim.
79 */
80 int (*out_escaped)(const char* /*output*/, size_t /*size*/, void* /*renderer_data*/);
81 } MUSTACHE_RENDERER;
82
83
84 /**
85 * An interface the application has to implement, in order to feed
86 * mustache_process() with data the template asks for.
87 *
88 * Tree hierarchy, immutable during the mustache_process() call, is assumed.
89 * Each node of the hierarchy has to be uniquely identified by some pointer.
90 *
91 * The mustache_process() never dereferences any of the pointers. It only
92 * uses them to refer to that node when calling any data provider callback.
93 */
94 typedef struct MUSTACHE_DATAPROVIDER {
95 /**
96 * Called to output contents of the given node. One of the MUSTACHE_PARSER
97 * output functions is provided, depending on the type of the mustache tag
98 * (`{{...}}` versus `{{{...}}}` ). Implementation of dump() may call that
99 * function arbitrarily.
100 *
101 * In many applications, it is not desirable/expected to be able dumping
102 * specific nodes (e.g. if the node is list or array forming the data
103 * tree hierarchy). In such cases, the implementation is allowed to just
104 * return zero without calling the provided callback at all, output some
105 * dummy string (e.g. "<<object>>"), or return non-zero value as an error
106 * sign, depending what makes better sense for the application.
107 *
108 * Implementation of dump() must propagate renderer_data into the
109 * callback as its last argument.
110 *
111 * Non-zero return value aborts mustache_process(). Typically, the
112 * implementations should do so if any call of out_fn callback fails.
113 */
114 int (*dump)(void* /*node*/, int (* /*out_fn*/)(const char*, size_t, void*),
115 void* /*renderer_data*/, void* /*provider_data*/);
116
117 /**
118 * Called once at the start of mustache_process(). It sets the initial
119 * lookup context. */
120 void* (*get_root)(void* /*provider_data*/);
121
122 /**
123 * Called to get named item of the current node, or NULL if there is no item.
124 *
125 * If the node is not of appropriate type (e.g. if it is an array of
126 * values), NULL has to be returned.
127 */
128 void* (*get_child_by_name)(void* /*node*/, const char* /*name*/,
129 size_t /*size*/, void* /*provider_data*/);
130
131 /**
132 * Called to get an indexed item of the current node, or NULL if there is
133 * no such item.
134 *
135 * The main use is for iterating over arrays.
136 *
137 * However note that accordingly to the mustache specification, single
138 * values (except FALSE, NULL, or empty lists) have to be iterable too.
139 * For such simple values, the callback should return the node itself
140 * for index 0, and NULL for any other index.
141 */
142 void* (*get_child_by_index)(void* /*node*/, unsigned /*index*/,
143 void* /*provider_data*/);
144
145 /**
146 * Called to get a partial template when mustache_process() handles
147 * a partial tag `{{>name}}`.
148 *
149 * Implementation should perform lookup for the template (compile it, if
150 * it is not), and return the template handle.
151 *
152 * If the lookup fails, the implementation reports it by returning NULL.
153 */
154 MUSTACHE_TEMPLATE* (*get_partial)(const char* /*name*/, size_t /*size*/,
155 void* /*provider_data*/);
156 } MUSTACHE_DATAPROVIDER;
157
158
159 /**
160 * Compile template text into a form suitable for mustache_process().
161 *
162 * If application processes multiple input data with a single template, it is
163 * recommended to cache and reuse the compiled template as much as possible,
164 * as the compiling may be relatively time-consuming operation.
165 *
166 * @param templ_data Text of the template.
167 * @param templ_size Length of the template text.
168 * @param parser Pointer to structure with parser callbacks. May be @c NULL.
169 * @param parser_data Pointer just propagated into the parser callbacks.
170 * @param flags Unused, use zero.
171 * @return Pointer to the compiled template, or @c NULL on an error.
172 */
173 MUSTACHE_TEMPLATE* mustache_compile(const char* templ_data, size_t templ_size,
174 const MUSTACHE_PARSER* parser, void* parser_data,
175 unsigned flags);
176
177 /**
178 * Release the template compiled with @c mustache_compile().
179 *
180 * @param t The template.
181 */
182 void mustache_release(MUSTACHE_TEMPLATE* t);
183
184 /**
185 * Process the template.
186 *
187 * The function outputs (via MUSTACHE_RENDERER::out_verbatim()) most of the
188 * text of the template. Whenever it reaches a mustache tag, it calls
189 * appropriate callback of MUSTACHE_DATAPROVIDER to change lookup context
190 * or a callback of MUSTACHE_RENDERER to output contents of the current
191 * context.
192 *
193 * @param t The template.
194 * @param renderer Pointer to structure with output callbacks.
195 * @param render_data Pointer just propagated to the output callbacks.
196 * @param provider Pointer to structure with data-providing callbacks.
197 * @param provider_dara Pointer just propagated to the data-providing callbacks.
198 * @return Zero on success, non-zero on failure.
199 *
200 * Note this operation can fail only if any callback returns an error
201 * and aborts the operation.
202 */
203 int mustache_process(const MUSTACHE_TEMPLATE* t,
204 const MUSTACHE_RENDERER* renderer, void* renderer_data,
205 const MUSTACHE_DATAPROVIDER* provider, void* provider_data);
206
207
208 #ifdef __cplusplus
209 }
210 #endif
211
212 #endif /* MUSTACHE4C_H */