yajl_parse.h

Interface to YAJL’s JSON stream parsing facilities.

Author

Lloyd Hilaiel

Typedefs

typedef struct yajl_handle_t *yajl_handle

An opaque handle to a parser.

Enums

enum yajl_status

Error codes returned from this interface.

Values:

enumerator yajl_status_ok

No error was encountered.

enumerator yajl_status_client_canceled

A client callback returned zero, stopping the parse.

enumerator yajl_status_error

An error occured during the parse. Call yajl_get_error() for more information about the encountered error.

enum yajl_option

Configuration parameters for the parser. These should be passed to yajl_config() followed by any option specific argument(s). In general, all boolean configuration parameters default to off.

Values:

enumerator yajl_allow_comments

Ignore javascript style comments present in the input. These are not standard in JSON but can be enabled with this. Turning on the yajl_allow_json5 option enables this option automatically.

yajl_config() argument type: int (boolean)

Example:

yajl_config(h, yajl_allow_comments, 1); // turn comment support on

enumerator yajl_dont_validate_strings

When set the parser will verify that all strings in JSON input are valid UTF8, and will emit a parse error if this is not so. When set, this option makes parsing slightly more expensive (~7% depending on the processor and compiler in use)

yajl_config() argument type: int (boolean)

Example:

yajl_config(h, yajl_dont_validate_strings, 1); // disable utf8 checking

enumerator yajl_allow_trailing_garbage

By default, upon calls to yajl_complete_parse(), yajl will ensure the entire input text was consumed and will raise an error otherwise. Turning this flag on causes YAJL to disable the garbage check. This can be useful when parsing JSON out of an input stream that contains more than a single JSON document.

yajl_config() argument type: int (boolean)

Example:

yajl_config(h, yajl_allow_trailing_garbage, 1); // non-JSON follows

enumerator yajl_allow_multiple_values

Allow multiple values to be parsed by a single handle. The entire text must be valid JSON, and values can be separated by any kind of whitespace. This flag will change the behavior of the parser, and cause it to continue parsing after a value is parsed, rather than transitioning into a complete state. This option can be useful when parsing multiple values from an input stream.

yajl_config() argument type: int (boolean)

Example:

yajl_config(h, yajl_allow_multiple_values, 1); // multi-doc stream

enumerator yajl_allow_partial_values

When yajl_complete_parse() is called the parser will check that the top level value was completely consumed. If called whilst in the middle of parsing a value, yajl will enter an error state (premature EOF). Setting this flag suppresses that check and the corresponding error.

yajl_config() argument type: int (boolean)

Example:

yajl_config(h, yajl_allow_partial_values, 1); // might stop early

enumerator yajl_allow_json5

The JSON5 standard allows additional formats for numbers, strings and object keys which are not permitted by the JSON standard. Setting this flag tells yajl to accept JSON5 standard input. This flag also enables yajl_allow_comments since comments are part of the JSON5 standard. In the EPICS build this option is enabled by default, it must be turned off to disable JSON5.

yajl_config() argument type: int (boolean)

Example:

yajl_config(h, yajl_allow_json5, 1); // We accept JSON5!

Functions

const char *yajl_status_to_string(yajl_status code)

Return a human readable, English, string for an error.

yajl_handle yajl_alloc(const yajl_callbacks *callbacks, yajl_alloc_funcs *afs, void *ctx)

Allocate a parser handle.

Parameters:
  • callbacks – A yajl_callbacks structure specifying the functions to call when different JSON entities are encountered in the input text. May be NULL, which is only useful for validation.

  • afs – Memory allocation functions, pass NULL to use the C runtime library routines (malloc() and friends).

  • ctx – A context pointer that will be passed to callbacks.

int yajl_config(yajl_handle hand, int option, ...)

Set parser options associated with a parser handle. See the yajl_option documentation for details of the available options and their arguments.

Returns:

Zero in case of error, non-zero otherwise.

void yajl_free(yajl_handle hand)

Free a parser handle.

yajl_status yajl_parse(yajl_handle hand, const unsigned char *jsonText, size_t jsonTextLength)

Parse some json!

Parameters:
  • hand – A handle to the json parser allocated with yajl_alloc().

  • jsonText – A pointer to the UTF8 json text to be parsed.

  • jsonTextLength – The length, in bytes, of input text.

yajl_status yajl_complete_parse(yajl_handle hand)

Parse any remaining buffered json.

Since yajl is a stream-based parser, without an explicit end of input, yajl sometimes can’t decide if content at the end of the stream is valid or not. For example, if “1” has been received, yajl can’t know whether another digit is next or some character that would terminate the integer token.

Parameters:

hand – a handle to the json parser allocated with yajl_alloc().

unsigned char *yajl_get_error(yajl_handle hand, int verbose, const unsigned char *jsonText, size_t jsonTextLength)

Get an error string describing the state of the parse.

If verbose is non-zero, the message will include the JSON text where the error occured, along with an arrow pointing to the specific char.

Returns:

A dynamically allocated string will be returned which should be freed with yajl_free_error().

size_t yajl_get_bytes_consumed(yajl_handle hand)

Get the amount of data consumed from the last chunk passed to YAJL.

In the case of a successful parse this can help you understand if the entire buffer was consumed (which will allow you to handle “junk at end of input”).

In the event an error is encountered during parsing, this function affords the client a way to get the offset into the most recent chunk where the error occured. 0 will be returned if no error was encountered.

void yajl_free_error(yajl_handle hand, unsigned char *str)

Free an error string returned from yajl_get_error().

struct yajl_callbacks
#include <yajl_parse.h>

YAJL is an event driven parser. This means as json elements are parsed, you are called back to do something with the data. The functions in this table indicate the various events for which you will be called back. Each callback accepts a “context” pointer, this is a void * that is passed into the yajl_parse() function which the client code may use to pass around context.

All callbacks return an integer. If non-zero, the parse will continue. If zero, the parse will be canceled and yajl_status_client_canceled will be returned from the parse.

Attention

A note about the handling of numbers: YAJL will only convert numbers that can be represented in a double or a 64 bit (long long) int. All other numbers will be passed to the client in string form using the yajl_number() callback. Furthermore, if yajl_number() is not NULL, it will always be used to return numbers, that is yajl_integer() and yajl_double() will be ignored. If yajl_number() is NULL but one of yajl_integer() or yajl_double() are defined, parsing of a number larger than is representable in a double or 64 bit integer will result in a parse error.

Public Members

int (*yajl_null)(void *ctx)
int (*yajl_boolean)(void *ctx, int boolVal)
int (*yajl_integer)(void *ctx, long long integerVal)
int (*yajl_double)(void *ctx, double doubleVal)
int (*yajl_number)(void *ctx, const char *numberVal, size_t numberLen)

A callback which passes the string representation of the number back to the client. Will be used for all numbers when present.

int (*yajl_string)(void *ctx, const unsigned char *stringVal, size_t stringLen)

Strings are returned as pointers into the JSON text when possible. As a result they are not zero-terminated.

int (*yajl_start_map)(void *ctx)
int (*yajl_map_key)(void *ctx, const unsigned char *key, size_t stringLen)
int (*yajl_end_map)(void *ctx)
int (*yajl_start_array)(void *ctx)
int (*yajl_end_array)(void *ctx)