Merge branch 'cb/do-not-use-test-cmp-with-a'
[git/git.git] / json-writer.h
CommitLineData
75459410
JH
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
bc2133c9
RJ
45#include "strbuf.h"
46
75459410
JH
47struct 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 { STRBUF_INIT, STRBUF_INIT, 0, 0 }
68
69void jw_init(struct json_writer *jw);
70void jw_release(struct json_writer *jw);
71
72void jw_object_begin(struct json_writer *jw, int pretty);
73void jw_array_begin(struct json_writer *jw, int pretty);
74
75void jw_object_string(struct json_writer *jw, const char *key,
76 const char *value);
77void jw_object_intmax(struct json_writer *jw, const char *key, intmax_t value);
78void jw_object_double(struct json_writer *jw, const char *key, int precision,
79 double value);
80void jw_object_true(struct json_writer *jw, const char *key);
81void jw_object_false(struct json_writer *jw, const char *key);
82void jw_object_bool(struct json_writer *jw, const char *key, int value);
83void jw_object_null(struct json_writer *jw, const char *key);
84void jw_object_sub_jw(struct json_writer *jw, const char *key,
85 const struct json_writer *value);
86
87void jw_object_inline_begin_object(struct json_writer *jw, const char *key);
88void jw_object_inline_begin_array(struct json_writer *jw, const char *key);
89
90void jw_array_string(struct json_writer *jw, const char *value);
91void jw_array_intmax(struct json_writer *jw, intmax_t value);
92void jw_array_double(struct json_writer *jw, int precision, double value);
93void jw_array_true(struct json_writer *jw);
94void jw_array_false(struct json_writer *jw);
95void jw_array_bool(struct json_writer *jw, int value);
96void jw_array_null(struct json_writer *jw);
97void jw_array_sub_jw(struct json_writer *jw, const struct json_writer *value);
98void jw_array_argc_argv(struct json_writer *jw, int argc, const char **argv);
99void jw_array_argv(struct json_writer *jw, const char **argv);
100
101void jw_array_inline_begin_object(struct json_writer *jw);
102void jw_array_inline_begin_array(struct json_writer *jw);
103
104int jw_is_terminated(const struct json_writer *jw);
105void jw_end(struct json_writer *jw);
106
107#endif /* JSON_WRITER_H */