json_out: new module for authoring JSON strings.
[ccan] / ccan / json_out / json_out.h
1 /* MIT (BSD) license - see LICENSE file for details */
2 #ifndef CCAN_JSON_OUT_H
3 #define CCAN_JSON_OUT_H
4 #include <ccan/compiler/compiler.h>
5 #include <ccan/tal/tal.h>
6 #include <ccan/typesafe_cb/typesafe_cb.h>
7 #include <stddef.h>
8
9 struct json_out;
10
11 /**
12  * json_out_new - allocate a json_out stream.
13  * @ctx: the tal_context to allocate from, or NULL
14  */
15 struct json_out *json_out_new(const tal_t *ctx);
16
17 /**
18  * json_out_call_on_move - callback for when buffer is reallocated.
19  * @jout: the json_out object to attach to.
20  * @cb: the callback to call.
21  * @arg: the argument to @cb (must match type).
22  *
23  * A NULL @cb disables.  You can't currently have more than one callback.
24  * The @delta argument to @cb is the difference between the old location
25  * and the new one, and is never zero.
26  */
27 #define json_out_call_on_move(jout, cb, arg)                            \
28         json_out_call_on_move_((jout),                                  \
29                                typesafe_cb_preargs(void, void *,        \
30                                                    (cb), (arg),         \
31                                                    struct json_out *,   \
32                                                    ptrdiff_t),          \
33                                (arg))
34
35 void json_out_call_on_move_(struct json_out *jout,
36                             void (*cb)(struct json_out *jout, ptrdiff_t delta,
37                                        void *arg),
38                             void *arg);
39
40 /**
41  * json_out_dup - duplicate a json_out stream.
42  * @ctx: the tal_context to allocate from, or NULL
43  * @src: the json_out to copy.
44  */
45 struct json_out *json_out_dup(const tal_t *ctx, const struct json_out *src);
46
47 /**
48  * json_out_start - start an array or object.
49  * @jout: the json_out object to write into.
50  * @fieldname: the fieldname, if inside an object, or NULL if inside an array.
51  * @type: '[' or '{' to start an array or object, respectively.
52  *
53  * Literally writes '"@fieldname": @type' or '@type ' if fieldname is NULL.
54  * @fieldname must not need JSON escaping.
55  */
56 void json_out_start(struct json_out *jout, const char *fieldname, char type);
57
58 /**
59  * json_out_end - end an array or object.
60  * @jout: the json_out object to write into.
61  * @type: '}' or ']' to end an array or object, respectively.
62  *
63  * Literally writes ']' or '}', keeping track of whether we need to append
64  * a comma.
65  */
66 void json_out_end(struct json_out *jout, char type);
67
68 /**
69  * json_out_add - add a formatted member.
70  * @jout: the json_out object to write into.
71  * @fieldname: optional fieldname to prepend (must not need escaping).
72  * @quote: if true, surround fmt by " and ".
73  * @fmt...: the printf-style format
74  *
75  * If you're in an array, @fieldname must be NULL.  If you're in an
76  * object, @fieldname must be non-NULL.  This is checked if
77  * CCAN_JSON_OUT_DEBUG is defined.
78  * @fieldname must not need JSON escaping.
79  *
80  * If the resulting string requires escaping, we call json_escape().
81  */
82 PRINTF_FMT(4,5)
83 void json_out_add(struct json_out *jout,
84                   const char *fieldname,
85                   bool quote,
86                   const char *fmt, ...);
87
88 /**
89  * json_out_addv - add a formatted member (vararg variant)
90  * @jout: the json_out object to write into.
91  * @fieldname: optional fieldname to prepend.
92  * @quote: if true, surround fmt by " and ".
93  * @fmt: the printf-style format
94  * @ap: the argument list.
95  *
96  * See json_out_add() above.
97  */
98 void json_out_addv(struct json_out *jout,
99                    const char *fieldname,
100                    bool quote,
101                    const char *fmt,
102                    va_list ap);
103
104 /**
105  * json_out_addstr - convenience helper to add a string field.
106  * @jout: the json_out object to write into.
107  * @fieldname: optional fieldname to prepend.
108  * @str: the string to add (must not be NULL).
109  *
110  * Equivalent to json_out_add(@jout, @fieldname, true, "%s", @str);
111  */
112 void json_out_addstr(struct json_out *jout,
113                      const char *fieldname,
114                      const char *str);
115
116 /**
117  * json_out_member_direct - add a field, with direct access.
118  * @jout: the json_out object to write into.
119  * @fieldname: optional fieldname to prepend.
120  * @extra: how many bytes to allocate.
121  *
122  * @fieldname must not need JSON escaping.  Returns a direct pointer into
123  * the @extra bytes.
124  *
125  * This allows you to write your own efficient type-specific helpers.
126  */
127 char *json_out_member_direct(struct json_out *jout,
128                              const char *fieldname, size_t extra);
129
130 /**
131  * json_out_direct - make room in output and access directly.
132  * @jout: the json_out object to write into.
133  * @len: the length to allocate.
134  *
135  * This lets you access the json_out stream directly, to save a copy,
136  * if you know exactly how much you will write.
137  *
138  * Returns a pointer to @len bytes at the end of @jout.
139  *
140  * This is dangerous, since it doesn't automatically prepend a ","
141  * like the internal logic does, but can be used (carefully) to add
142  * entire objects, or whitespace.
143  */
144 char *json_out_direct(struct json_out *jout, size_t extra);
145
146 /**
147  * json_out_add_splice - copy a field from another json_out.
148  * @jout: the json_out object to write into.
149  * @fieldname: optional fieldname to prepend.
150  * @src: the json_out object to copy from.
151  *
152  * This asserts that @src is well-formed (as per json_out_finished()),
153  * then places it into @jout with optional @fieldname prepended.  This
154  * can be used to assemble sub-objects for your JSON and then copy
155  * them in.
156  *
157  * Note that it will call json_out_contents(@src), so it expects that
158  * object to be unconsumed.
159  */
160 void json_out_add_splice(struct json_out *jout,
161                          const char *fieldname,
162                          const struct json_out *src);
163
164 /**
165  * json_out_finished - assert that the json buffer is finished.
166  * @jout: the json_out object written to.
167  *
168  * This simply causes internal assertions that all arrays and objects are
169  * finished.  It needs CCAN_JSON_OUT_DEBUG defined to have any effect.
170  */
171 void json_out_finished(const struct json_out *jout);
172
173 /**
174  * json_out_contents - read contents from json_out stream.
175  * @jout: the json_out object we want to read from.
176  * @len: set to the length of the buffer returned.
177  *
178  * This returns a pointer into the JSON written so far.  Returns NULL
179  * and sets @len to 0 if there's nothing left in the buffer.
180  */
181 const char *json_out_contents(const struct json_out *jout, size_t *len);
182
183 /**
184  * json_out_consume - discard contents from json_out stream.
185  * @jout: the json_out object we read from.
186  * @len: the length to consume (must be <= @len from json_out_contents)
187  */
188 void json_out_consume(struct json_out *jout, size_t len);
189 #endif /* CCAN_JSON_OUT_H */