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  * See t/helper/test-json-writer.c for various usage examples.
  32  *
  33  * LIMITATIONS:
  34  * ============
  35  *
  36  * The JSON specification [1,2] defines string values as Unicode data
  37  * and probably UTF-8 encoded.  The current json-writer API does not
  38  * enforce this and will write any string as received.  However, it will
  39  * properly quote and backslash-escape them as necessary.  It is up to
  40  * the caller to UTF-8 encode their strings *before* passing them to this
  41  * API.  This layer should not have to try to guess the encoding or locale
  42  * of the given strings.
  43  */
  44
  45 #include "strbuf.h"
  46
  47 struct json_writer
  48 {
  49         /*
  50          * Buffer of the in-progress JSON currently being composed.
  51          */
  52         struct strbuf json;
  53
  54         /*
  55          * Simple stack of the currently open array and object forms.
  56          * This is a string of '{' and '[' characters indicating the
  57          * currently unterminated forms.  This is used to ensure the
  58          * properly closing character is used when popping a level and
  59          * to know when the JSON is completely closed.
  60          */
  61         struct strbuf open_stack;
  62
  63         unsigned int need_comma:1;
  64         unsigned int pretty:1;
  65 };
  66
  67 #define JSON_WRITER_INIT { \
  68         .json = STRBUF_INIT, \
  69         .open_stack = STRBUF_INIT, \
  70 }
  71
  72 void jw_init(struct json_writer *jw);
  73 void jw_release(struct json_writer *jw);
  74
  75 void jw_object_begin(struct json_writer *jw, int pretty);
  76 void jw_array_begin(struct json_writer *jw, int pretty);
  77
  78 void jw_object_string(struct json_writer *jw, const char *key,
  79                       const char *value);
  80 void jw_object_intmax(struct json_writer *jw, const char *key, intmax_t value);
  81 void jw_object_double(struct json_writer *jw, const char *key, int precision,
  82                       double value);
  83 void jw_object_true(struct json_writer *jw, const char *key);
  84 void jw_object_false(struct json_writer *jw, const char *key);
  85 void jw_object_bool(struct json_writer *jw, const char *key, int value);
  86 void jw_object_null(struct json_writer *jw, const char *key);
  87 void jw_object_sub_jw(struct json_writer *jw, const char *key,
  88                       const struct json_writer *value);
  89
  90 void jw_object_inline_begin_object(struct json_writer *jw, const char *key);
  91 void jw_object_inline_begin_array(struct json_writer *jw, const char *key);
  92
  93 void jw_array_string(struct json_writer *jw, const char *value);
  94 void jw_array_intmax(struct json_writer *jw, intmax_t value);
  95 void jw_array_double(struct json_writer *jw, int precision, double value);
  96 void jw_array_true(struct json_writer *jw);
  97 void jw_array_false(struct json_writer *jw);
  98 void jw_array_bool(struct json_writer *jw, int value);
  99 void jw_array_null(struct json_writer *jw);
 100 void jw_array_sub_jw(struct json_writer *jw, const struct json_writer *value);
 101 void jw_array_argc_argv(struct json_writer *jw, int argc, const char **argv);
 102 void jw_array_argv(struct json_writer *jw, const char **argv);
 103
 104 void jw_array_inline_begin_object(struct json_writer *jw);
 105 void jw_array_inline_begin_array(struct json_writer *jw);
 106
 107 int jw_is_terminated(const struct json_writer *jw);
 108 void jw_end(struct json_writer *jw);
 109
 110 #endif /* JSON_WRITER_H */