android13/external/libwebsockets/READMEs/README.json-lejp.md

LEJP JSON Stream Parser

cmake	LWS_WITH_LEJP
Header	./include/libwebsockets/lws-lejp.h
api-test	./minimal-examples/api-tests/api-test-lejp/
test app	./test-apps/test-lejp.c -> libwebsockets-test-lejp

LEJP is a lightweight JSON stream parser.

The features are:

• completely immune to input fragmentation, give it any size blocks of JSON as they become available, 1 byte, or 100K at a time give identical parsing results
• input chunks discarded as they are parsed, whole JSON never needed in memory
• nonrecursive, fixed stack usage of a few dozen bytes
• no heap allocations at all, just requires ~500 byte context usually on caller stack
• creates callbacks to a user-provided handler as members are parsed out
• no payload size limit, supports huge / endless strings bigger than system memory
• collates utf-8 text payloads into a 250-byte chunk buffer in the json parser context object for ease of access

Type handling

LEJP leaves all numbers in text form, they are signalled in different callbacks according to int or float, but delivered as text strings in the first ctx->npos chars of ctx->buf.

For numeric types, you would typically use atoi() or similar to recover the number as a host type.

Callback reasons

The user callback does not have to handle any callbacks, it only needs to process the data for the ones it is interested in.

Callback reason	JSON structure	Associated data
LEJPCB_CONSTRUCTED	Created the parse context
LEJPCB_DESTRUCTED	Destroyed the parse context
LEJPCB_COMPLETE	The parsing completed OK
LEJPCB_FAILED	The parsing failed
LEJPCB_VAL_TRUE	boolean true
LEJPCB_VAL_FALSE	boolean false
LEJPCB_VAL_NULL	explicit NULL
LEJPCB_PAIR_NAME	The name part of a JSON key: value map pair	ctx->buf
LEJPCB_VAL_STR_START	A UTF-8 string is starting
LEJPCB_VAL_STR_CHUNK	The next string chunk	ctx->npos bytes in ctx->buf
LEJPCB_VAL_STR_END	The last string chunk	ctx->npos bytes in ctx->buf
LEJPCB_ARRAY_START	An array is starting
LEJPCB_ARRAY_END	An array has ended
LEJPCB_OBJECT_START	A JSON object is starting
LEJPCB_OBJECT_END	A JSON object has ended

Handling JSON UTF-8 strings

When a string is parsed, an advisory callback of LECPCB_VAL_STR_START occurs first. No payload is delivered with the START callback.

Payload is collated into ctx->buf[], the valid length is in ctx->npos.

For short strings or blobs where the length is known, the whole payload is delivered in a single LECPCB_VAL_STR_END callback.

For payloads larger than the size of ctx->buf[], LECPCB_VAL_STR_CHUNK callbacks occur delivering each sequential bufferload.

The last chunk (which may be zero length) is delievered by LECPCB_VAL_STR_END.

Parsing paths

LEJP maintains a "parsing path" in ctx->path that represents the context of the callback events. As a convenience, at LEJP context creation time, you can pass in an array of path strings you want to match on, and have any match checkable in the callback using ctx->path_match, it's 0 if no active match, or the match index from your path array starting from 1 for the first entry.

CBOR element	Representation in path
JSON Array	[]
JSON Map	.
JSON Map entry key string	keystring

Comparison with LECP (CBOR parser)

LECP is based on the same principles as LEJP and shares most of the callbacks. The major differences:

• LEJP value callbacks all appear in ctx->buf[], ie, floating-point is provided to the callback in ascii form like "1.0". CBOR provides a more strict typing system, and the different type values are provided either in ctx->buf[] for blobs or utf-8 text strtings, or the item.u union for converted types, with additional callback reasons specific to each type.

• CBOR "maps" use _OBJECT_START and _END parsing callbacks around the key / value pairs. LEJP has a special callback type PAIR_NAME for the key string / integer, but in LECP these are provided as generic callbacks dependent on type, ie, generic string callbacks or integer ones, and the value part is represented according to whatever comes.