armsrc/frozen.h

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