frozen.h (11529B)
1 /* 2 * Copyright (c) 2004-2013 Sergey Lyubka <valenok@gmail.com> 3 * Copyright (c) 2018 Cesanta Software Limited 4 * All rights reserved 5 * 6 * Licensed under the Apache License, Version 2.0 (the ""License""); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an ""AS IS"" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 19 #ifndef CS_FROZEN_FROZEN_H_ 20 #define CS_FROZEN_FROZEN_H_ 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif /* __cplusplus */ 25 26 #include <stdarg.h> 27 #include <stddef.h> 28 #include <stdio.h> 29 30 #if defined(_WIN32) && _MSC_VER < 1700 31 typedef int bool; 32 enum { false = 0, true = 1 }; 33 #else 34 #include <stdbool.h> 35 #endif 36 37 /* JSON token type */ 38 enum json_token_type { 39 JSON_TYPE_INVALID = 0, /* memsetting to 0 should create INVALID value */ 40 JSON_TYPE_STRING, 41 JSON_TYPE_NUMBER, 42 JSON_TYPE_TRUE, 43 JSON_TYPE_FALSE, 44 JSON_TYPE_NULL, 45 JSON_TYPE_OBJECT_START, 46 JSON_TYPE_OBJECT_END, 47 JSON_TYPE_ARRAY_START, 48 JSON_TYPE_ARRAY_END, 49 50 JSON_TYPES_CNT 51 }; 52 53 /* 54 * Structure containing token type and value. Used in `json_walk()` and 55 * `json_scanf()` with the format specifier `%T`. 56 */ 57 struct json_token { 58 const char *ptr; /* Points to the beginning of the value */ 59 int len; /* Value length */ 60 enum json_token_type type; /* Type of the token, possible values are above */ 61 }; 62 63 #define JSON_INVALID_TOKEN \ 64 { 0, 0, JSON_TYPE_INVALID } 65 66 /* Error codes */ 67 #define JSON_STRING_INVALID -1 68 #define JSON_STRING_INCOMPLETE -2 69 70 /* 71 * Callback-based SAX-like API. 72 * 73 * Property name and length is given only if it's available: i.e. if current 74 * event is an object's property. In other cases, `name` is `NULL`. For 75 * example, name is never given: 76 * - For the first value in the JSON string; 77 * - For events JSON_TYPE_OBJECT_END and JSON_TYPE_ARRAY_END 78 * 79 * E.g. for the input `{ "foo": 123, "bar": [ 1, 2, { "baz": true } ] }`, 80 * the sequence of callback invocations will be as follows: 81 * 82 * - type: JSON_TYPE_OBJECT_START, name: NULL, path: "", value: NULL 83 * - type: JSON_TYPE_NUMBER, name: "foo", path: ".foo", value: "123" 84 * - type: JSON_TYPE_ARRAY_START, name: "bar", path: ".bar", value: NULL 85 * - type: JSON_TYPE_NUMBER, name: "0", path: ".bar[0]", value: "1" 86 * - type: JSON_TYPE_NUMBER, name: "1", path: ".bar[1]", value: "2" 87 * - type: JSON_TYPE_OBJECT_START, name: "2", path: ".bar[2]", value: NULL 88 * - type: JSON_TYPE_TRUE, name: "baz", path: ".bar[2].baz", value: "true" 89 * - type: JSON_TYPE_OBJECT_END, name: NULL, path: ".bar[2]", value: "{ \"baz\": 90 *true }" 91 * - type: JSON_TYPE_ARRAY_END, name: NULL, path: ".bar", value: "[ 1, 2, { 92 *\"baz\": true } ]" 93 * - type: JSON_TYPE_OBJECT_END, name: NULL, path: "", value: "{ \"foo\": 123, 94 *\"bar\": [ 1, 2, { \"baz\": true } ] }" 95 */ 96 typedef void (*json_walk_callback_t)(void *callback_data, const char *name, 97 size_t name_len, const char *path, 98 const struct json_token *token); 99 100 /* 101 * Parse `json_string`, invoking `callback` in a way similar to SAX parsers; 102 * see `json_walk_callback_t`. 103 * Return number of processed bytes, or a negative error code. 104 */ 105 int json_walk(const char *json_string, int json_string_length, 106 json_walk_callback_t callback, void *callback_data); 107 108 /* 109 * JSON generation API. 110 * struct json_out abstracts output, allowing alternative printing plugins. 111 */ 112 struct json_out { 113 int (*printer)(struct json_out *, const char *str, size_t len); 114 union { 115 struct { 116 char *buf; 117 size_t size; 118 size_t len; 119 } buf; 120 void *data; 121 FILE *fp; 122 } u; 123 }; 124 125 extern int json_printer_buf(struct json_out *, const char *, size_t); 126 extern int json_printer_file(struct json_out *, const char *, size_t); 127 128 #define JSON_OUT_BUF(buf, len) \ 129 { \ 130 json_printer_buf, { \ 131 { buf, len, 0 } \ 132 } \ 133 } 134 #define JSON_OUT_FILE(fp) \ 135 { \ 136 json_printer_file, { \ 137 { (char *) fp, 0, 0 } \ 138 } \ 139 } 140 141 typedef int (*json_printf_callback_t)(struct json_out *, va_list *ap); 142 143 /* 144 * Generate formatted output into a given sting buffer. 145 * This is a superset of printf() function, with extra format specifiers: 146 * - `%B` print json boolean, `true` or `false`. Accepts an `int`. 147 * - `%Q` print quoted escaped string or `null`. Accepts a `const char *`. 148 * - `%.*Q` same as `%Q`, but with length. Accepts `int`, `const char *` 149 * - `%V` print quoted base64-encoded string. Accepts a `const char *`, `int`. 150 * - `%H` print quoted hex-encoded string. Accepts a `int`, `const char *`. 151 * - `%M` invokes a json_printf_callback_t function. That callback function 152 * can consume more parameters. 153 * 154 * Return number of bytes printed. If the return value is bigger than the 155 * supplied buffer, that is an indicator of overflow. In the overflow case, 156 * overflown bytes are not printed. 157 */ 158 int json_printf(struct json_out *, const char *fmt, ...); 159 int json_vprintf(struct json_out *, const char *fmt, va_list ap); 160 161 /* 162 * Same as json_printf, but prints to a file. 163 * File is created if does not exist. File is truncated if already exists. 164 */ 165 int json_fprintf(const char *file_name, const char *fmt, ...); 166 int json_vfprintf(const char *file_name, const char *fmt, va_list ap); 167 168 /* 169 * Print JSON into an allocated 0-terminated string. 170 * Return allocated string, or NULL on error. 171 * Example: 172 * 173 * ```c 174 * char *str = json_asprintf("{a:%H}", 3, "abc"); 175 * printf("%s\n", str); // Prints "616263" 176 * free(str); 177 * ``` 178 */ 179 char *json_asprintf(const char *fmt, ...); 180 char *json_vasprintf(const char *fmt, va_list ap); 181 182 /* 183 * Helper %M callback that prints contiguous C arrays. 184 * Consumes void *array_ptr, size_t array_size, size_t elem_size, char *fmt 185 * Return number of bytes printed. 186 */ 187 int json_printf_array(struct json_out *, va_list *ap); 188 189 /* 190 * Scan JSON string `str`, performing scanf-like conversions according to `fmt`. 191 * This is a `scanf()` - like function, with following differences: 192 * 193 * 1. Object keys in the format string may be not quoted, e.g. "{key: %d}" 194 * 2. Order of keys in an object is irrelevant. 195 * 3. Several extra format specifiers are supported: 196 * - %B: consumes `int *` (or `char *`, if `sizeof(bool) == sizeof(char)`), 197 * expects boolean `true` or `false`. 198 * - %Q: consumes `char **`, expects quoted, JSON-encoded string. Scanned 199 * string is malloc-ed, caller must free() the string. 200 * - %V: consumes `char **`, `int *`. Expects base64-encoded string. 201 * Result string is base64-decoded, malloced and NUL-terminated. 202 * The length of result string is stored in `int *` placeholder. 203 * Caller must free() the result. 204 * - %H: consumes `int *`, `char **`. 205 * Expects a hex-encoded string, e.g. "fa014f". 206 * Result string is hex-decoded, malloced and NUL-terminated. 207 * The length of the result string is stored in `int *` placeholder. 208 * Caller must free() the result. 209 * - %M: consumes custom scanning function pointer and 210 * `void *user_data` parameter - see json_scanner_t definition. 211 * - %T: consumes `struct json_token *`, fills it out with matched token. 212 * 213 * Return number of elements successfully scanned & converted. 214 * Negative number means scan error. 215 */ 216 int json_scanf(const char *str, int str_len, const char *fmt, ...); 217 int json_vscanf(const char *str, int str_len, const char *fmt, va_list ap); 218 219 /* json_scanf's %M handler */ 220 typedef void (*json_scanner_t)(const char *str, int len, void *user_data); 221 222 /* 223 * Helper function to scan array item with given path and index. 224 * Fills `token` with the matched JSON token. 225 * Return -1 if no array element found, otherwise non-negative token length. 226 */ 227 int json_scanf_array_elem(const char *s, int len, const char *path, int index, 228 struct json_token *token); 229 230 /* 231 * Unescape JSON-encoded string src,slen into dst, dlen. 232 * src and dst may overlap. 233 * If destination buffer is too small (or zero-length), result string is not 234 * written but the length is counted nevertheless (similar to snprintf). 235 * Return the length of unescaped string in bytes. 236 */ 237 int json_unescape(const char *src, int slen, char *dst, int dlen); 238 239 /* 240 * Escape a string `str`, `str_len` into the printer `out`. 241 * Return the number of bytes printed. 242 */ 243 int json_escape(struct json_out *out, const char *str, size_t str_len); 244 245 /* 246 * Read the whole file in memory. 247 * Return malloc-ed file content, or NULL on error. The caller must free(). 248 */ 249 char *json_fread(const char *file_name); 250 251 /* 252 * Update given JSON string `s,len` by changing the value at given `json_path`. 253 * The result is saved to `out`. If `json_fmt` == NULL, that deletes the key. 254 * If path is not present, missing keys are added. Array path without an 255 * index pushes a value to the end of an array. 256 * Return 1 if the string was changed, 0 otherwise. 257 * 258 * Example: s is a JSON string { "a": 1, "b": [ 2 ] } 259 * json_setf(s, len, out, ".a", "7"); // { "a": 7, "b": [ 2 ] } 260 * json_setf(s, len, out, ".b", "7"); // { "a": 1, "b": 7 } 261 * json_setf(s, len, out, ".b[]", "7"); // { "a": 1, "b": [ 2,7 ] } 262 * json_setf(s, len, out, ".b", NULL); // { "a": 1 } 263 */ 264 int json_setf(const char *s, int len, struct json_out *out, 265 const char *json_path, const char *json_fmt, ...); 266 267 int json_vsetf(const char *s, int len, struct json_out *out, 268 const char *json_path, const char *json_fmt, va_list ap); 269 270 /* 271 * Pretty-print JSON string `s,len` into `out`. 272 * Return number of processed bytes in `s`. 273 */ 274 int json_prettify(const char *s, int len, struct json_out *out); 275 276 /* 277 * Prettify JSON file `file_name`. 278 * Return number of processed bytes, or negative number of error. 279 * On error, file content is not modified. 280 */ 281 int json_prettify_file(const char *file_name); 282 283 /* 284 * Iterate over an object at given JSON `path`. 285 * On each iteration, fill the `key` and `val` tokens. It is OK to pass NULL 286 * for `key`, or `val`, in which case they won't be populated. 287 * Return an opaque value suitable for the next iteration, or NULL when done. 288 * 289 * Example: 290 * 291 * ```c 292 * void *h = NULL; 293 * struct json_token key, val; 294 * while ((h = json_next_key(s, len, h, ".foo", &key, &val)) != NULL) { 295 * printf("[%.*s] -> [%.*s]\n", key.len, key.ptr, val.len, val.ptr); 296 * } 297 * ``` 298 */ 299 void *json_next_key(const char *s, int len, void *handle, const char *path, 300 struct json_token *key, struct json_token *val); 301 302 /* 303 * Iterate over an array at given JSON `path`. 304 * Similar to `json_next_key`, but fills array index `idx` instead of `key`. 305 */ 306 void *json_next_elem(const char *s, int len, void *handle, const char *path, 307 int *idx, struct json_token *val); 308 309 #ifndef JSON_MAX_PATH_LEN 310 #define JSON_MAX_PATH_LEN 256 311 #endif 312 313 #ifndef JSON_MINIMAL 314 #define JSON_MINIMAL 0 315 #endif 316 317 #ifndef JSON_ENABLE_BASE64 318 #define JSON_ENABLE_BASE64 !JSON_MINIMAL 319 #endif 320 321 #ifndef JSON_ENABLE_HEX 322 #define JSON_ENABLE_HEX !JSON_MINIMAL 323 #endif 324 325 #ifdef __cplusplus 326 } 327 #endif /* __cplusplus */ 328 329 #endif /* CS_FROZEN_FROZEN_H_ */