1 #ifndef JSON_WRITER_H 2 #define JSON_WRITER_H 3 4 /* 5 * JSON data structures are defined at: 6 * [1] http://www.ietf.org/rfc/rfc7159.txt 7 * [2] http://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 */ 111