git.ozlabs.org Git - ccan/blob - 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 */