| 1 | #ifndef JSON_WRITER_H |
| 2 | #define JSON_WRITER_H |
| 3 | |
| 4 | /* |
| 5 | * JSON data structures are defined at: |
| 6 | * [1] https://www.ietf.org/rfc/rfc7159.txt |
| 7 | * [2] https://www.json.org/ |
| 8 | * |
| 9 | * The JSON-writer API allows one to build JSON data structures using a |
| 10 | * simple wrapper around a "struct strbuf" buffer. It is intended as a |
| 11 | * simple API to build output strings; it is not intended to be a general |
| 12 | * object model for JSON data. In particular, it does not re-order keys |
| 13 | * in an object (dictionary), it does not de-dup keys in an object, and |
| 14 | * it does not allow lookup or parsing of JSON data. |
| 15 | * |
| 16 | * All string values (both keys and string r-values) are properly quoted |
| 17 | * and escaped if they contain special characters. |
| 18 | * |
| 19 | * These routines create compact JSON data (with no unnecessary whitespace, |
| 20 | * newlines, or indenting). If you get an unexpected response, verify |
| 21 | * that you're not expecting a pretty JSON string. |
| 22 | * |
| 23 | * Both "JSON objects" (aka sets of k/v pairs) and "JSON array" can be |
| 24 | * constructed using a 'begin append* end' model. |
| 25 | * |
| 26 | * Nested objects and arrays can either be constructed bottom up (by |
| 27 | * creating sub object/arrays first and appending them to the super |
| 28 | * object/array) -or- by building them inline in one pass. This is a |
| 29 | * personal style and/or data shape choice. |
| 30 | * |
| 31 | * USAGE: |
| 32 | * ====== |
| 33 | * |
| 34 | * - Initialize the json_writer with jw_init. |
| 35 | * |
| 36 | * - Open an object as the main data structure with jw_object_begin. |
| 37 | * Append a key-value pair to it using the jw_object_<type> functions. |
| 38 | * Conclude with jw_end. |
| 39 | * |
| 40 | * - Alternatively, open an array as the main data structure with |
| 41 | * jw_array_begin. Append a value to it using the jw_array_<type> |
| 42 | * functions. Conclude with jw_end. |
| 43 | * |
| 44 | * - Append a new, unterminated array or object to the current |
| 45 | * object using the jw_object_inline_begin_{array, object} functions. |
| 46 | * Similarly, append a new, unterminated array or object to |
| 47 | * the current array using the jw_array_inline_begin_{array, object} |
| 48 | * functions. |
| 49 | * |
| 50 | * - Append other json_writer as a value to the current array or object |
| 51 | * using the jw_{array, object}_sub_jw functions. |
| 52 | * |
| 53 | * - Extend the current array with an null-terminated array of strings |
| 54 | * by using jw_array_argv or with a fixed number of elements of a |
| 55 | * array of string by using jw_array_argc_argv. |
| 56 | * |
| 57 | * - Release the json_writer after using it by calling jw_release. |
| 58 | * |
| 59 | * See t/helper/test-json-writer.c for various usage examples. |
| 60 | * |
| 61 | * LIMITATIONS: |
| 62 | * ============ |
| 63 | * |
| 64 | * The JSON specification [1,2] defines string values as Unicode data |
| 65 | * and probably UTF-8 encoded. The current json-writer API does not |
| 66 | * enforce this and will write any string as received. However, it will |
| 67 | * properly quote and backslash-escape them as necessary. It is up to |
| 68 | * the caller to UTF-8 encode their strings *before* passing them to this |
| 69 | * API. This layer should not have to try to guess the encoding or locale |
| 70 | * of the given strings. |
| 71 | */ |
| 72 | |
| 73 | #include "strbuf.h" |
| 74 | |
| 75 | struct json_writer |
| 76 | { |
| 77 | /* |
| 78 | * Buffer of the in-progress JSON currently being composed. |
| 79 | */ |
| 80 | struct strbuf json; |
| 81 | |
| 82 | /* |
| 83 | * Simple stack of the currently open array and object forms. |
| 84 | * This is a string of '{' and '[' characters indicating the |
| 85 | * currently unterminated forms. This is used to ensure the |
| 86 | * properly closing character is used when popping a level and |
| 87 | * to know when the JSON is completely closed. |
| 88 | */ |
| 89 | struct strbuf open_stack; |
| 90 | |
| 91 | unsigned int need_comma:1; |
| 92 | unsigned int pretty:1; |
| 93 | }; |
| 94 | |
| 95 | #define JSON_WRITER_INIT { \ |
| 96 | .json = STRBUF_INIT, \ |
| 97 | .open_stack = STRBUF_INIT, \ |
| 98 | } |
| 99 | |
| 100 | /* |
| 101 | * Initialize a json_writer with empty values. |
| 102 | */ |
| 103 | void jw_init(struct json_writer *jw); |
| 104 | |
| 105 | /* |
| 106 | * Release the internal buffers of a json_writer. |
| 107 | */ |
| 108 | void jw_release(struct json_writer *jw); |
| 109 | |
| 110 | /* |
| 111 | * Begin the json_writer using an object as the top-level data structure. If |
| 112 | * pretty is set to 1, the result will be a human-readable and indented JSON, |
| 113 | * and if it is set to 0 the result will be minified single-line JSON. |
| 114 | */ |
| 115 | void jw_object_begin(struct json_writer *jw, int pretty); |
| 116 | |
| 117 | /* |
| 118 | * Begin the json_writer using an array as the top-level data structure. If |
| 119 | * pretty is set to 1, the result will be a human-readable and indented JSON, |
| 120 | * and if it is set to 0 the result will be minified single-line JSON. |
| 121 | */ |
| 122 | void jw_array_begin(struct json_writer *jw, int pretty); |
| 123 | |
| 124 | /* |
| 125 | * Append a string field to the current object of the json_writer, given its key |
| 126 | * and its value. Trigger a BUG when not in an object. |
| 127 | */ |
| 128 | void jw_object_string(struct json_writer *jw, const char *key, |
| 129 | const char *value); |
| 130 | |
| 131 | /* |
| 132 | * Append an int field to the current object of the json_writer, given its key |
| 133 | * and its value. Trigger a BUG when not in an object. |
| 134 | */ |
| 135 | void jw_object_intmax(struct json_writer *jw, const char *key, intmax_t value); |
| 136 | |
| 137 | /* |
| 138 | * Append a double field to the current object of the json_writer, given its key |
| 139 | * and its value. The precision parameter defines the number of significant |
| 140 | * digits, where -1 can be used for maximum precision. Trigger a BUG when not in |
| 141 | * an object. |
| 142 | */ |
| 143 | void jw_object_double(struct json_writer *jw, const char *key, int precision, |
| 144 | double value); |
| 145 | |
| 146 | /* |
| 147 | * Append a boolean field set to true to the current object of the json_writer, |
| 148 | * given its key. Trigger a BUG when not in an object. |
| 149 | */ |
| 150 | void jw_object_true(struct json_writer *jw, const char *key); |
| 151 | |
| 152 | /* |
| 153 | * Append a boolean field set to false to the current object of the json_writer, |
| 154 | * given its key. Trigger a BUG when not in an object. |
| 155 | */ |
| 156 | void jw_object_false(struct json_writer *jw, const char *key); |
| 157 | |
| 158 | /* |
| 159 | * Append a boolean field to the current object of the json_writer, given its |
| 160 | * key and its value. Trigger a BUG when not in an object. |
| 161 | */ |
| 162 | void jw_object_bool(struct json_writer *jw, const char *key, int value); |
| 163 | |
| 164 | /* |
| 165 | * Append a null field to the current object of the json_writer, given its key. |
| 166 | * Trigger a BUG when not in an object. |
| 167 | */ |
| 168 | void jw_object_null(struct json_writer *jw, const char *key); |
| 169 | |
| 170 | /* |
| 171 | * Append a field to the current object of the json_writer, given its key and |
| 172 | * another json_writer that represents its content. Trigger a BUG when not in |
| 173 | * an object. |
| 174 | */ |
| 175 | void jw_object_sub_jw(struct json_writer *jw, const char *key, |
| 176 | const struct json_writer *value); |
| 177 | |
| 178 | /* |
| 179 | * Start an object as the value of a field in the current object of the |
| 180 | * json_writer. Trigger a BUG when not in an object. |
| 181 | */ |
| 182 | void jw_object_inline_begin_object(struct json_writer *jw, const char *key); |
| 183 | |
| 184 | /* |
| 185 | * Start an array as the value of a field in the current object of the |
| 186 | * json_writer. Trigger a BUG when not in an object. |
| 187 | */ |
| 188 | void jw_object_inline_begin_array(struct json_writer *jw, const char *key); |
| 189 | |
| 190 | /* |
| 191 | * Append a string value to the current array of the json_writer. Trigger a BUG |
| 192 | * when not in an array. |
| 193 | */ |
| 194 | void jw_array_string(struct json_writer *jw, const char *value); |
| 195 | |
| 196 | /* |
| 197 | * Append an int value to the current array of the json_writer. Trigger a BUG |
| 198 | * when not in an array. |
| 199 | */ |
| 200 | void jw_array_intmax(struct json_writer *jw, intmax_t value); |
| 201 | |
| 202 | /* |
| 203 | * Append a double value to the current array of the json_writer. The precision |
| 204 | * parameter defines the number of significant digits, where -1 can be used for |
| 205 | * maximum precision. Trigger a BUG when not in an array. |
| 206 | */ |
| 207 | void jw_array_double(struct json_writer *jw, int precision, double value); |
| 208 | |
| 209 | /* |
| 210 | * Append a true value to the current array of the json_writer. Trigger a BUG |
| 211 | * when not in an array. |
| 212 | */ |
| 213 | void jw_array_true(struct json_writer *jw); |
| 214 | |
| 215 | /* |
| 216 | * Append a false value to the current array of the json_writer. Trigger a BUG |
| 217 | * when not in an array. |
| 218 | */ |
| 219 | void jw_array_false(struct json_writer *jw); |
| 220 | |
| 221 | /* |
| 222 | * Append a boolean value to the current array of the json_writer. Trigger a BUG |
| 223 | * when not in an array. |
| 224 | */ |
| 225 | void jw_array_bool(struct json_writer *jw, int value); |
| 226 | |
| 227 | /* |
| 228 | * Append a null value to the current array of the json_writer. Trigger a BUG |
| 229 | * when not in an array. |
| 230 | */ |
| 231 | void jw_array_null(struct json_writer *jw); |
| 232 | |
| 233 | /* |
| 234 | * Append a json_writer as a value to the current array of the |
| 235 | * json_writer. Trigger a BUG when not in an array. |
| 236 | */ |
| 237 | void jw_array_sub_jw(struct json_writer *jw, const struct json_writer *value); |
| 238 | |
| 239 | /* |
| 240 | * Append the first argc values from the argv array of strings to the current |
| 241 | * array of the json_writer. Trigger a BUG when not in an array. |
| 242 | * |
| 243 | * This function does not provide safety for cases where the array has less than |
| 244 | * argc values. |
| 245 | */ |
| 246 | void jw_array_argc_argv(struct json_writer *jw, int argc, const char **argv); |
| 247 | |
| 248 | /* |
| 249 | * Append a null-terminated array of strings to the current array of the |
| 250 | * json_writer. Trigger a BUG when not in an array. |
| 251 | */ |
| 252 | void jw_array_argv(struct json_writer *jw, const char **argv); |
| 253 | |
| 254 | /* |
| 255 | * Start an object as a value in the current array of the json_writer. Trigger a |
| 256 | * BUG when not in an array. |
| 257 | */ |
| 258 | void jw_array_inline_begin_object(struct json_writer *jw); |
| 259 | |
| 260 | /* |
| 261 | * Start an array as a value in the current array. Trigger a BUG when not in an |
| 262 | * array. |
| 263 | */ |
| 264 | void jw_array_inline_begin_array(struct json_writer *jw); |
| 265 | |
| 266 | /* |
| 267 | * Return whether the json_writer is terminated. In other words, if the all the |
| 268 | * objects and arrays are already closed. |
| 269 | */ |
| 270 | int jw_is_terminated(const struct json_writer *jw); |
| 271 | |
| 272 | /* |
| 273 | * Terminates the current object or array of the json_writer. In other words, |
| 274 | * append a ] if the current array is not closed or } if the current object |
| 275 | * is not closed. |
| 276 | * |
| 277 | * Abort the execution if there's no object or array that can be terminated. |
| 278 | */ |
| 279 | void jw_end(struct json_writer *jw); |
| 280 | |
| 281 | #endif /* JSON_WRITER_H */ |