1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
|
/*
Author: José Bollo <jobol@nonadev.net>
Author: José Bollo <jose.bollo@iot.bzh>
https://gitlab.com/jobol/mustach
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
#ifndef _mustach_h_included_
#define _mustach_h_included_
struct mustach_sbuf; /* see below */
/**
* Current version of mustach and its derivates
*/
#define MUSTACH_VERSION 99
#define MUSTACH_VERSION_MAJOR (MUSTACH_VERSION / 100)
#define MUSTACH_VERSION_MINOR (MUSTACH_VERSION % 100)
/**
* Maximum nested imbrications supported
*/
#define MUSTACH_MAX_DEPTH 256
/**
* Maximum length of tags in mustaches {{...}}
*/
#define MUSTACH_MAX_LENGTH 1024
/**
* mustach_itf - interface for callbacks
*
* All of this function should return a negative value to stop
* the mustache processing. The returned negative value will be
* then returned to the caller of mustach as is.
*
* The functions enter and next should return 0 or 1.
*
* All other functions should normally return MUSTACH_OK (zero).
* If it returns a negative value, it means an error that stop
* the process and that is reported to the caller.
*
* @start: If defined (can be NULL), starts the mustach processing
* of the closure, called at the very beginning before any
* mustach processing occurs.
*
* @put: If defined (can be NULL), writes the value of 'name'
* to 'file' with 'escape' or not.
* As an extension (see NO_ALLOW_EMPTY_TAG), the 'name' can be
* the empty string. In that later case an implementation can
* return MUSTACH_ERROR_EMPTY_TAG to refuse empty names.
* If NULL and 'get' NULL the error MUSTACH_ERROR_INVALID_ITF
* is returned.
*
* @enter: Enters the section of 'name' if possible.
* Musts return 1 if entered or 0 if not entered.
* When 1 is returned, the function 'leave' will always be called.
* Conversely 'leave' is never called when enter returns 0 or
* a negative value.
* When 1 is returned, the function must activate the first
* item of the section.
*
* @next: Activates the next item of the section if it exists.
* Musts return 1 when the next item is activated.
* Musts return 0 when there is no item to activate.
*
* @leave: Leaves the last entered section
*
* @partial: If defined (can be NULL), returns in 'sbuf' the content of the
* partial of 'name'. @see mustach_sbuf
* If NULL but 'get' not NULL, 'get' is used instead of partial.
* If NULL and 'get' NULL and 'put' not NULL, 'put' is called with
* a true FILE.
*
* @emit: If defined (can be NULL), writes the 'buffer' of 'size' with 'escape'.
* If NULL the standard function 'fwrite' is used with a true FILE.
* If not NULL that function is called instead of 'fwrite' to output
* text.
* It implies that if you define either 'partial' or 'get' callback,
* the meaning of 'FILE *file' is abstract for mustach's process and
* then you can use 'FILE*file' pass any kind of pointer (including NULL)
* to the function 'fmustach'. An example of a such behaviour is given by
* the implementation of 'umustach_json_c'.
*
* @get: If defined (can be NULL), returns in 'sbuf' the value of 'name'.
* As an extension (see NO_ALLOW_EMPTY_TAG), the 'name' can be
* the empty string. In that later case an implementation can
* return MUSTACH_ERROR_EMPTY_TAG to refuse empty names.
* If NULL and 'put' NULL the error MUSTACH_ERROR_INVALID_ITF
* is returned.
*
* @stop: If defined (can be NULL), stops the mustach processing
* of the closure, called at the very end after all mustach
* processing occurerd. The status returned by the processing
* is passed to the stop.
*
* The array below summarize status of callbacks:
*
* FULLY OPTIONAL: start partial
* MANDATORY: enter next leave
* COMBINATORIAL: put emit get
*
* Not definig a MANDATORY callback returns error MUSTACH_ERROR_INVALID_ITF.
*
* For COMBINATORIAL callbacks the array below summarize possible combinations:
*
* combination : put : emit : get : abstract FILE
* -------------+---------+---------+---------+-----------------------
* HISTORIC : defined : NULL : NULL : NO: standard FILE
* MINIMAL : NULL : NULL : defined : NO: standard FILE
* CUSTOM : NULL : defined : defined : YES: abstract FILE
* DUCK : defined : NULL : defined : NO: standard FILE
* DANGEROUS : defined : defined : any : YES or NO, depends on 'partial'
* INVALID : NULL : any : NULL : -
*
* The DUCK case runs on one leg. 'get' is not used if 'partial' is defined
* but is used for 'partial' if 'partial' is NULL. Thus for clarity, do not use
* it that way but define 'partial' and let 'get' NULL.
*
* The DANGEROUS case is special: it allows abstract FILE if 'partial' is defined
* but forbids abstract FILE when 'partial' is NULL.
*
* The INVALID case returns error MUSTACH_ERROR_INVALID_ITF.
*/
struct mustach_itf {
int (*start)(void *closure);
int (*put)(void *closure, const char *name, int escape, FILE *file);
int (*enter)(void *closure, const char *name);
int (*next)(void *closure);
int (*leave)(void *closure);
int (*partial)(void *closure, const char *name, struct mustach_sbuf *sbuf);
int (*emit)(void *closure, const char *buffer, size_t size, int escape, FILE *file);
int (*get)(void *closure, const char *name, struct mustach_sbuf *sbuf);
void (*stop)(void *closure, int status);
};
/**
* mustach_sbuf - Interface for handling zero terminated strings
*
* That structure is used for returning zero terminated strings -in 'value'-
* to mustach. The callee can provide a function for releasing the returned
* 'value'. Three methods for releasing the string are possible.
*
* 1. no release: set either 'freecb' or 'releasecb' with NULL (done by default)
* 2. release without closure: set 'freecb' to its expected value
* 3. release with closure: set 'releasecb' and 'closure' to their expected values
*
* @value: The value of the string. That value is not changed by mustach -const-.
*
* @freecb: The function to call for freeing the value without closure.
* For convenience, signature of that callback is compatible with 'free'.
* Can be NULL.
*
* @releasecb: The function to release with closure.
* Can be NULL.
*
* @closure: The closure to use for 'releasecb'.
*/
struct mustach_sbuf {
const char *value;
union {
void (*freecb)(void*);
void (*releasecb)(const char *value, void *closure);
};
void *closure;
};
/*
* Definition of error codes returned by mustach
*/
#define MUSTACH_OK 0
#define MUSTACH_ERROR_SYSTEM -1
#define MUSTACH_ERROR_UNEXPECTED_END -2
#define MUSTACH_ERROR_EMPTY_TAG -3
#define MUSTACH_ERROR_TAG_TOO_LONG -4
#define MUSTACH_ERROR_BAD_SEPARATORS -5
#define MUSTACH_ERROR_TOO_DEEP -6
#define MUSTACH_ERROR_CLOSING -7
#define MUSTACH_ERROR_BAD_UNESCAPE_TAG -8
#define MUSTACH_ERROR_INVALID_ITF -9
#define MUSTACH_ERROR_ITEM_NOT_FOUND -10
#define MUSTACH_ERROR_PARTIAL_NOT_FOUND -11
/* You can use definition below for user specific error */
#define MUSTACH_ERROR_USER_BASE -100
#define MUSTACH_ERROR_USER(x) (MUSTACH_ERROR_USER_BASE-(x))
/**
* fmustach - Renders the mustache 'template' in 'file' for 'itf' and 'closure'.
*
* @template: the template string to instantiate
* @itf: the interface to the functions that mustach calls
* @closure: the closure to pass to functions called
* \@file: the file where to write the result
*
* Returns 0 in case of success, -1 with errno set in case of system error
* a other negative value in case of error.
*/
extern int fmustach(const char *template, struct mustach_itf *itf, void *closure, FILE *file);
/**
* fmustach - Renders the mustache 'template' in 'fd' for 'itf' and 'closure'.
*
* @template: the template string to instantiate
* @itf: the interface to the functions that mustach calls
* @closure: the closure to pass to functions called
* @fd: the file descriptor number where to write the result
*
* Returns 0 in case of success, -1 with errno set in case of system error
* a other negative value in case of error.
*/
extern int fdmustach(const char *template, struct mustach_itf *itf, void *closure, int fd);
/**
* fmustach - Renders the mustache 'template' in 'result' for 'itf' and 'closure'.
*
* @template: the template string to instantiate
* @itf: the interface to the functions that mustach calls
* @closure: the closure to pass to functions called
* @result: the pointer receiving the result when 0 is returned
* @size: the size of the returned result
*
* Returns 0 in case of success, -1 with errno set in case of system error
* a other negative value in case of error.
*/
extern int mustach(const char *template, struct mustach_itf *itf, void *closure, char **result, size_t *size);
#endif
|
