json-writer.h

   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 */