Stream Output

Functions
JSONOut *	jsonOutBegin (StreamBuffer *sb, flags_t flags)
bool	jsonOut (JSONOut *jo, const JSONParseEvent *ev)
void	jsonOutEnd (JSONOut **jo)
void	jsonStrEscape (string *out, strref val, flags_t flags)

Detailed Description

Event-driven JSON output using parse events.

Function Documentation

jsonOut()

bool jsonOut	(	JSONOut *	jo,
		const JSONParseEvent *	ev
	)

bool jsonOut(JSONOut *jo, const JSONParseEvent *ev)

Writes a JSON element using a parse event.

Call this repeatedly with appropriate JSONParseEvent structures to build the JSON output. Events should be sent in a valid sequence (e.g., object keys must be followed by values).

Parameters

jo	JSON output context from jsonOutBegin()
ev	Parse event describing the element to output

Returns

true on success, false on error

jsonOutBegin()

JSONOut * jsonOutBegin	(	StreamBuffer *	sb,
		flags_t	flags
	)

JSONOut *jsonOutBegin(StreamBuffer *sb, flags_t flags)

Begins event-driven JSON output to a stream buffer.

Initializes a JSON output context that writes one document to the stream buffer as a push producer. After calling this, repeatedly call jsonOut() with JSONParseEvent structures to build the output, then call jsonOutEnd() to finalize.

The stream buffer is only borrowed and outlives the document, so several documents may be written to the same buffer – one jsonOutBegin()/jsonOutEnd() pair each, with any framing bytes the format needs written in between.

Parameters

sb	Stream buffer to write to
flags	Output formatting flags from JSON_OUT_FLAGS

Returns

JSON output context

Example:

StreamBuffer *sb = sbufCreate(4096);
string output = 0;
sbufStrCRegisterPush(sb, &output);
 
JSONOut *jo = jsonOutBegin(sb, JSON_Pretty);
 
JSONParseEvent ev = {0};
ev.etype = JSON_Object_Begin;
jsonOut(jo, &ev);
 
ev.etype = JSON_Object_Key;
ev.edata.strData = _SL("name");
jsonOut(jo, &ev);
 
ev.etype = JSON_String;
ev.edata.strData = _SL("value");
jsonOut(jo, &ev);
 
ev.etype = JSON_Object_End;
jsonOut(jo, &ev);
 
jsonOutEnd(&jo);

jsonOutEnd()

void jsonOutEnd

(

JSONOut **

jo

)

void jsonOutEnd(JSONOut **jo)

Finalizes JSON output and cleans up the context.

Writes the document's trailing line ending and frees the JSON output context. The stream buffer is left open; end it with sbufClose() once no more documents are going into it.

Parameters

jo	Pointer to JSON output context (set to NULL after call)

jsonStrEscape()

void jsonStrEscape	(	string *	out,
		strref	val,
		flags_t	flags
	)

Appends a string to another, escaped for use inside JSON quotes

The quotes themselves are not written, and the destination is appended to rather than replaced, so a caller assembling a JSON document by hand can use this for keys and values alike. Control characters become their short escapes where JSON defines one and \uXXXX otherwise; non-ASCII passes through as UTF-8 unless JSON_ASCII_Only is set.

This is the same escaping jsonOut() applies, exposed for callers that are producing single small JSON values and do not want a stream buffer to do it – an NDJSON log line, for instance.

Parameters

out	String to append the escaped text to
val	String to escape; NULL appends nothing
flags	JSON output flags; only JSON_ASCII_Only is consulted

Example:

string line = 0;
strAppend(&line, _SL("{\"msg\":\""));
jsonStrEscape(&line, msg, 0);
strAppend(&line, _SL("\"}"));