yajl_gen.h File Reference

Interface to YAJL's JSON generation facilities. More...

#include "yajl_common.h"

Include dependency graph for yajl_gen.h:

Go to the source code of this file.

Typedefs
typedef struct yajl_gen_t *	yajl_gen
typedef void(*	yajl_print_t )(void *ctx, const char *str, size_t len)

Enumerations
enum	yajl_gen_status {   yajl_gen_status_ok = 0, yajl_gen_keys_must_be_strings, yajl_max_depth_exceeded, yajl_gen_in_error_state,   yajl_gen_generation_complete, yajl_gen_invalid_number, yajl_gen_no_buf, yajl_gen_invalid_string }
enum	yajl_gen_option {   yajl_gen_beautify = 0x01, yajl_gen_indent_string = 0x02, yajl_gen_print_callback = 0x04, yajl_gen_validate_utf8 = 0x08,   yajl_gen_escape_solidus = 0x10, yajl_gen_json5 = 0x20 }

Functions
YAJL_API int	yajl_gen_config (yajl_gen hand, int option,...)
YAJL_API yajl_gen	yajl_gen_alloc (const yajl_alloc_funcs *allocFuncs)
YAJL_API void	yajl_gen_free (yajl_gen handle)
YAJL_API yajl_gen_status	yajl_gen_integer (yajl_gen hand, long long int number)
YAJL_API yajl_gen_status	yajl_gen_double (yajl_gen hand, double number)
YAJL_API yajl_gen_status	yajl_gen_number (yajl_gen hand, const char *num, size_t len)
YAJL_API yajl_gen_status	yajl_gen_string (yajl_gen hand, const unsigned char *str, size_t len)
YAJL_API yajl_gen_status	yajl_gen_null (yajl_gen hand)
YAJL_API yajl_gen_status	yajl_gen_bool (yajl_gen hand, int boolean)
YAJL_API yajl_gen_status	yajl_gen_map_open (yajl_gen hand)
YAJL_API yajl_gen_status	yajl_gen_map_close (yajl_gen hand)
YAJL_API yajl_gen_status	yajl_gen_array_open (yajl_gen hand)
YAJL_API yajl_gen_status	yajl_gen_array_close (yajl_gen hand)
YAJL_API yajl_gen_status	yajl_gen_get_buf (yajl_gen hand, const unsigned char **buf, size_t *len)
YAJL_API void	yajl_gen_clear (yajl_gen hand)
YAJL_API void	yajl_gen_reset (yajl_gen hand, const char *sep)

Detailed Description

Author

Lloyd Hilaiel

Definition in file yajl_gen.h.

Typedef Documentation

typedef struct yajl_gen_t* yajl_gen

An opaque handle to a generator.

Definition at line 59 of file yajl_gen.h.

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

A callback used for "printing" the results.

Definition at line 62 of file yajl_gen.h.

Enumeration Type Documentation

enum yajl_gen_status

Generator status codes.

Enumerator
yajl_gen_status_ok	No error.
yajl_gen_keys_must_be_strings	At a point where a map key is generated, a function other than yajl_gen_string() was called.
yajl_max_depth_exceeded	YAJL's maximum generation depth was exceeded. See YAJL_MAX_DEPTH
yajl_gen_in_error_state	A yajl_gen_XXX() generator function was called while in an error state.
yajl_gen_generation_complete	A complete JSON document has been generated.
yajl_gen_invalid_number	yajl_gen_double() was passed an invalid floating point value (infinity or NaN) without yajl_gen_json5 set.
yajl_gen_no_buf	A print callback was passed in, so there is no internal buffer to get from.
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.

Definition at line 32 of file yajl_gen.h.

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.

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
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 * Example: yajl_gen_config(g, yajl_gen_indent_string, " "); // 2 spaces
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);
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
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)
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

Definition at line 69 of file yajl_gen.h.

Function Documentation

YAJL_API 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_API 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_API void yajl_gen_free

(

yajl_gen

handle

)

Free a generator handle.

YAJL_API yajl_gen_status yajl_gen_integer	(	yajl_gen	hand,
		long long int	number
	)

Generate an integer number.

YAJL_API 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_API 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_API 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_API yajl_gen_status yajl_gen_null

(

yajl_gen

hand

)

Generate a null value.

YAJL_API yajl_gen_status yajl_gen_bool	(	yajl_gen	hand,
		int	boolean
	)

Generate a true or false value from boolean.

YAJL_API 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_API yajl_gen_status yajl_gen_map_close

(

yajl_gen

hand

)

Finish generating a JSON map.

YAJL_API yajl_gen_status yajl_gen_array_open

(

yajl_gen

hand

)

Start generating a JSON array.

YAJL_API yajl_gen_status yajl_gen_array_close

(

yajl_gen

hand

)

Finish generating a JSON array.

YAJL_API 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.

YAJL_API 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.

YAJL_API 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.

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).

Note: This call does not clear yajl's output buffer, which must be accomplished explicitly by calling yajl_gen_clear().