mustach-wrap.h (9762B)
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_wrap_h_included_ 10 #define _mustach_wrap_h_included_ 11 12 /* 13 * mustach-wrap is intended to make integration of JSON 14 * libraries easier by wrapping mustach extensions in a 15 * single place. 16 * 17 * As before, using mustach and only mustach is possible 18 * (by using only mustach.h) but does not implement high 19 * level features coming with extensions implemented by 20 * this high level wrapper. 21 */ 22 #include "mustach.h" 23 /* 24 * Definition of the writing callbacks for mustach functions 25 * producing output to callbacks. 26 * 27 * Two callback types are defined: 28 * 29 * @mustach_write_cb_t: 30 * 31 * callback receiving the escaped data to be written as 3 parameters: 32 * 33 * 1. the 'closure', the same given to the wmustach_... function 34 * 2. a pointer to a 'buffer' containing the characters to be written 35 * 3. the size in bytes of the data pointed by 'buffer' 36 * 37 * @mustach_emit_cb_t: 38 * 39 * callback receiving the data to be written and a flag indicating 40 * if escaping should be done or not as 4 parameters: 41 * 42 * 1. the 'closure', the same given to the emustach_... function 43 * 2. a pointer to a 'buffer' containing the characters to be written 44 * 3. the size in bytes of the data pointed by 'buffer' 45 * 4. a boolean indicating if 'escape' should be done 46 */ 47 #ifndef _mustach_output_callbacks_defined_ 48 #define _mustach_output_callbacks_defined_ 49 typedef int mustach_write_cb_t(void *closure, const char *buffer, size_t size); 50 typedef int mustach_emit_cb_t(void *closure, const char *buffer, size_t size, int escape); 51 #endif 52 53 /** 54 * Flags specific to mustach wrap 55 */ 56 #define Mustach_With_SingleDot 4 /* obsolete, always set */ 57 #define Mustach_With_Equal 8 58 #define Mustach_With_Compare 16 59 #define Mustach_With_JsonPointer 32 60 #define Mustach_With_ObjectIter 64 61 #define Mustach_With_IncPartial 128 /* obsolete, always set */ 62 #define Mustach_With_EscFirstCmp 256 63 #define Mustach_With_PartialDataFirst 512 64 #define Mustach_With_ErrorUndefined 1024 65 66 #undef Mustach_With_AllExtensions 67 #define Mustach_With_AllExtensions 1023 /* don't include ErrorUndefined */ 68 69 /** 70 * mustach_wrap_itf - high level wrap of mustach - interface for callbacks 71 * 72 * The functions sel, subsel, enter and next should return 0 or 1. 73 * 74 * All other functions should normally return MUSTACH_OK (zero). 75 * 76 * If any function returns a negative value, it means an error that 77 * stop the processing and that is reported to the caller. Mustach 78 * also has its own error codes. Using the macros MUSTACH_ERROR_USER 79 * and MUSTACH_IS_ERROR_USER could help to avoid clashes. 80 * 81 * @start: If defined (can be NULL), starts the mustach processing 82 * of the closure, called at the very beginning before any 83 * mustach processing occurs. 84 * 85 * @stop: If defined (can be NULL), stops the mustach processing 86 * of the closure, called at the very end after all mustach 87 * processing occurered. The status returned by the processing 88 * is passed to the stop. 89 * 90 * @compare: If defined (can be NULL), compares the value of the 91 * currently selected item with the given value and returns 92 * a negative value if current value is lesser, a positive 93 * value if the current value is greater or zero when 94 * values are equals. 95 * If 'compare' is NULL, any comparison in mustach 96 * is going to fails. 97 * 98 * @sel: Selects the item of the given 'name'. If 'name' is NULL 99 * Selects the current item. Returns 1 if the selection is 100 * effective or else 0 if the selection failed. 101 * 102 * @subsel: Selects from the currently selected object the value of 103 * the field of given name. Returns 1 if the selection is 104 * effective or else 0 if the selection failed. 105 * 106 * @enter: Enters the section of 'name' if possible. 107 * Musts return 1 if entered or 0 if not entered. 108 * When 1 is returned, the function 'leave' will always be called. 109 * Conversely 'leave' is never called when enter returns 0 or 110 * a negative value. 111 * When 1 is returned, the function must activate the first 112 * item of the section. 113 * 114 * @next: Activates the next item of the section if it exists. 115 * Musts return 1 when the next item is activated. 116 * Musts return 0 when there is no item to activate. 117 * 118 * @leave: Leaves the last entered section 119 * 120 * @get: Returns in 'sbuf' the value of the current selection if 'key' 121 * is zero. Otherwise, when 'key' is not zero, return in 'sbuf' 122 * the name of key of the current selection, or if no such key 123 * exists, the empty string. Must return 1 if possible or 124 * 0 when not possible or an error code. 125 */ 126 struct mustach_wrap_itf { 127 int (*start)(void *closure); 128 void (*stop)(void *closure, int status); 129 int (*compare)(void *closure, const char *value); 130 int (*sel)(void *closure, const char *name); 131 int (*subsel)(void *closure, const char *name); 132 int (*enter)(void *closure, int objiter); 133 int (*next)(void *closure); 134 int (*leave)(void *closure); 135 int (*get)(void *closure, struct mustach_sbuf *sbuf, int key); 136 }; 137 138 /** 139 * Mustach interface used internally by mustach wrapper functions. 140 * Can be used for overriding behaviour. 141 */ 142 extern const struct mustach_itf mustach_wrap_itf; 143 144 /** 145 * Global hook for providing partials. When set to a not NULL value, the pointed 146 * function replaces the default behaviour and is called to provide the partial 147 * of the given 'name' in 'sbuf'. 148 * The function must return MUSTACH_OK when it filled 'sbuf' with value of partial 149 * or must return an error code if it failed. But if MUSTACH_ERROR_PARTIAL_NOT_FOUND 150 * is returned, the default behavior is evaluated. 151 */ 152 extern int (*mustach_wrap_get_partial)(const char *name, struct mustach_sbuf *sbuf); 153 154 /** 155 * mustach_wrap_file - Renders the mustache 'template' in 'file' for an abstract 156 * wrapper of interface 'itf' and 'closure'. 157 * 158 * @template: the template string to instantiate 159 * @length: length of the template or zero if unknown and template null terminated 160 * @itf: the interface of the abstract wrapper 161 * @closure: the closure of the abstract wrapper 162 * @file: the file where to write the result 163 * 164 * Returns 0 in case of success, -1 with errno set in case of system error 165 * a other negative value in case of error. 166 */ 167 extern int mustach_wrap_file(const char *template, size_t length, const struct mustach_wrap_itf *itf, void *closure, int flags, FILE *file); 168 169 /** 170 * mustach_wrap_fd - Renders the mustache 'template' in 'fd' for an abstract 171 * wrapper of interface 'itf' and 'closure'. 172 * 173 * @template: the template string to instantiate 174 * @length: length of the template or zero if unknown and template null terminated 175 * @itf: the interface of the abstract wrapper 176 * @closure: the closure of the abstract wrapper 177 * @fd: the file descriptor number where to write the result 178 * 179 * Returns 0 in case of success, -1 with errno set in case of system error 180 * a other negative value in case of error. 181 */ 182 extern int mustach_wrap_fd(const char *template, size_t length, const struct mustach_wrap_itf *itf, void *closure, int flags, int fd); 183 184 /** 185 * mustach_wrap_mem - Renders the mustache 'template' in 'result' for an abstract 186 * wrapper of interface 'itf' and 'closure'. 187 * 188 * @template: the template string to instantiate 189 * @length: length of the template or zero if unknown and template null terminated 190 * @itf: the interface of the abstract wrapper 191 * @closure: the closure of the abstract wrapper 192 * @result: the pointer receiving the result when 0 is returned 193 * @size: the size of the returned result 194 * 195 * Returns 0 in case of success, -1 with errno set in case of system error 196 * a other negative value in case of error. 197 */ 198 extern int mustach_wrap_mem(const char *template, size_t length, const struct mustach_wrap_itf *itf, void *closure, int flags, char **result, size_t *size); 199 200 /** 201 * mustach_wrap_write - Renders the mustache 'template' for an abstract 202 * wrapper of interface 'itf' and 'closure' to custom writer 203 * 'writecb' with 'writeclosure'. 204 * 205 * @template: the template string to instantiate 206 * @length: length of the template or zero if unknown and template null terminated 207 * @itf: the interface of the abstract wrapper 208 * @closure: the closure of the abstract wrapper 209 * @writecb: the function that write values 210 * @closure: the closure for the write function 211 * 212 * Returns 0 in case of success, -1 with errno set in case of system error 213 * a other negative value in case of error. 214 */ 215 extern int mustach_wrap_write(const char *template, size_t length, const struct mustach_wrap_itf *itf, void *closure, int flags, mustach_write_cb_t *writecb, void *writeclosure); 216 217 /** 218 * mustach_wrap_emit - Renders the mustache 'template' for an abstract 219 * wrapper of interface 'itf' and 'closure' to custom emiter 'emitcb' 220 * with 'emitclosure'. 221 * 222 * @template: the template string to instantiate 223 * @length: length of the template or zero if unknown and template null terminated 224 * @itf: the interface of the abstract wrapper 225 * @closure: the closure of the abstract wrapper 226 * @emitcb: the function that emit values 227 * @closure: the closure for the write function 228 * 229 * Returns 0 in case of success, -1 with errno set in case of system error 230 * a other negative value in case of error. 231 */ 232 extern int mustach_wrap_emit(const char *template, size_t length, const struct mustach_wrap_itf *itf, void *closure, int flags, mustach_emit_cb_t *emitcb, void *emitclosure); 233 234 #endif 235