yajl_gen.h

Interface to YAJL’s JSON generation facilities.

Author

Lloyd Hilaiel

Typedefs

typedef struct yajl_gen_t *yajl_gen

An opaque handle to a generator.

typedef void (*yajl_print_t)(void *ctx, const char *str, size_t len)

A callback used for “printing” the results.

Enums

enum yajl_gen_status

Generator status codes.

Values:

enumerator yajl_gen_status_ok

No error.

enumerator yajl_gen_keys_must_be_strings

At a point where a map key is generated, a function other than yajl_gen_string() was called.

enumerator yajl_max_depth_exceeded

YAJL’s maximum generation depth was exceeded. See YAJL_MAX_DEPTH

enumerator yajl_gen_in_error_state

A yajl_gen_XXX() generator function was called while in an error state.

enumerator yajl_gen_generation_complete

A complete JSON document has been generated.

enumerator yajl_gen_invalid_number

yajl_gen_double() was passed an invalid floating point value (infinity or NaN) without yajl_gen_json5 set.

enumerator yajl_gen_no_buf

A print callback was passed in, so there is no internal buffer to get from.

enumerator yajl_gen_invalid_string

Returned from yajl_gen_string() when the yajl_gen_validate_utf8 option is enabled and an invalid UTF8 code was passed by client.

enum yajl_gen_option

Configuration parameters for the parser, these may be passed to yajl_gen_config() along with option-specific argument(s). In general, all configuration parameters default to off.

Values:

enumerator yajl_gen_beautify

Generate indented (beautiful) output.

   yajl_gen_config() argument type: int (boolean)

   Example: \code{.cpp}
   yajl_gen_config(g, yajl_gen_beautify, 1); // Human format please
   \endcode

enumerator yajl_gen_indent_string

Set the indent string which is used when yajl_gen_beautify is enabled, which may only contain whitespace characters such as \t or some number of spaces. The default is four spaces ‘ ‘.

yajl_gen_config() argument type: const char *

The pointer argument passed is stored (not copied) and must remain valid for the lifetime of the handle, or until replaced.

Example:

yajl_gen_config(g, yajl_gen_indent_string, "  "); // 2 spaces

enumerator yajl_gen_print_callback

Set a function and context argument that should be used to output the generated json. The function should conform to the yajl_print_t prototype while the context argument may be any void * of your choosing.

yajl_gen_config() arguments: yajl_print_t, void *

Example:

yajl_gen_config(g, yajl_gen_print_callback, myFunc, myVoidPtr);

enumerator yajl_gen_validate_utf8

Normally the generator does not validate that strings you pass to it via yajl_gen_string() are valid UTF8. Enabling this option will cause it to do so.

yajl_gen_config() argument type: int (boolean)

Example:

yajl_gen_config(g, yajl_gen_validate_utf8, 1); // Check UTF8

enumerator yajl_gen_escape_solidus

The forward solidus (slash or ‘/’ in human) is not required to be escaped in JSON text. By default, YAJL will not escape it in the interest of saving bytes. Setting this flag will cause YAJL to always escape ‘/’ in generated JSON strings.

yajl_gen_config() argument type: int (boolean)

enumerator yajl_gen_json5

JSON5 is an updated version of JSON with additional capabilities. Special numbers such as NaN and Infinity cannot be represented in the original JSON, but are permitted in JSON5. Setting this flag allows YAJL to output the JSON5 representation of these special numbers instead of returning with an error, and to emit map keys that are valid javascript identifiers without quotes.

yajl_gen_config() argument type: int (boolean)

Example:

yajl_gen_config(g, yajl_gen_json5, 1); // Output JSON5

Functions

int yajl_gen_config(yajl_gen hand, int option, ...)

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

Returns:

Zero in case of error, non-zero otherwise.

yajl_gen yajl_gen_alloc(const yajl_alloc_funcs *allocFuncs)

Allocate a generator handle.

Parameters:

allocFuncs – An optional pointer to a structure which allows the client to provide memory allocation functions for use by yajl. May be NULL to use the C runtime library’s malloc(), free() and realloc().

Returns:

An allocated handle on success, NULL on failure (bad params)

void yajl_gen_free(yajl_gen handle)

Free a generator handle.

yajl_gen_status yajl_gen_integer(yajl_gen hand, long long int number)

Generate an integer number.

yajl_gen_status yajl_gen_double(yajl_gen hand, double number)

Generate a floating point number.

Parameters:
  • hand – The generator handle.

  • number – The value to output. The values Infinity or NaN are only accepted if the yajl_gen_json5 option is set, as these values have no legal representation in JSON; the generator will return yajl_gen_invalid_number otherwise.

yajl_gen_status yajl_gen_number(yajl_gen hand, const char *num, size_t len)

Generate a number from the string given in num.

yajl_gen_status yajl_gen_string(yajl_gen hand, const unsigned char *str, size_t len)

Generate a string value or map key from str.

yajl_gen_status yajl_gen_null(yajl_gen hand)

Generate a null value.

yajl_gen_status yajl_gen_bool(yajl_gen hand, int boolean)

Generate a true or false value from boolean.

yajl_gen_status yajl_gen_map_open(yajl_gen hand)

Start generating a JSON map. This should be followed by calls to yajl_gen_string() to provide a key and another yajl_gen routine to provide the value associated with that key.

yajl_gen_status yajl_gen_map_close(yajl_gen hand)

Finish generating a JSON map.

yajl_gen_status yajl_gen_array_open(yajl_gen hand)

Start generating a JSON array.

yajl_gen_status yajl_gen_array_close(yajl_gen hand)

Finish generating a JSON array.

yajl_gen_status yajl_gen_get_buf(yajl_gen hand, const unsigned char **buf, size_t *len)

Access the zero-terminated generator buffer. If incrementally outputting JSON, one should call yajl_gen_clear() to clear the buffer. This allows stream generation.

void yajl_gen_clear(yajl_gen hand)

Clear yajl’s output buffer, but maintain all internal generation state. This function will not reset the generator state, and is intended to enable incremental JSON output.

void yajl_gen_reset(yajl_gen hand, const char *sep)

Reset the generator state. Allows a client to generate multiple JSON entities in a stream.

Note: This call does not clear yajl’s output buffer, which must be accomplished explicitly by calling

yajl_gen_clear().

Parameters:
  • hand – The generator handle.

  • sep – This string will be inserted to separate the previously generated output from the following; passing NULL means no separation of entities (beware that generating multiple JSON numbers without a separator creates ambiguous output).