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.
-
enumerator yajl_gen_status_ok
-
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
-
enumerator yajl_gen_beautify
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)
-
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
orNaN
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
orfalse
value fromboolean
.
-
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).