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