freshlybakedca.ke
Git fork
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
75struct 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 */
103void jw_init(struct json_writer *jw);
104
105/*
106 * Release the internal buffers of a json_writer.
107 */
108void 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 */
115void 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 */
122void 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 */
128void 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 */
135void 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 */
143void 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 */
150void 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 */
156void 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 */
162void 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 */
168void 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 */
175void 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 */
182void 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 */
188void 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 */
194void 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 */
200void 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 */
207void 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 */
213void 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 */
219void 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 */
225void 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 */
231void 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 */
237void 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 */
246void 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 */
252void 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 */
258void 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 */
264void 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 */
270int 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 */
279void jw_end(struct json_writer *jw);
280
281#endif /* JSON_WRITER_H */