yajl_gen.h File Reference

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

#include "yajl_common.h"

Include dependency graph for yajl_gen.h:

This graph shows which files directly or indirectly include this file:

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 }

Functions
YAJL_API int	yajl_gen_config (yajl_gen g, yajl_gen_option opt,...)
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)

Detailed Description

Interface to YAJL's JSON generation facilities.

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_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_indent_string	Set an indent string which is used when yajl_gen_beautify() is enabled. Maybe something like \t or some number of spaces. The default is four spaces ' '.
yajl_gen_print_callback	Set a function and context argument that should be used to output generated json. the function should conform to the yajl_print_t() prototype while the context argument is a void * of your choosing. 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_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 iterest of saving bytes. Setting this flag will cause YAJL to always escape '/' in generated JSON strings.

Definition at line 69 of file yajl_gen.h.

                 {
        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_option;

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 generator function (yajl_gen_XXX) 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).
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 was passed by client code.

Definition at line 32 of file yajl_gen.h.

                 {
        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
    } yajl_gen_status;

Function Documentation

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 overide the memory allocation used by yajl. May be NULL, in which case malloc(), free() and realloc() will be used.

Returns

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

Definition at line 97 of file yajl_gen.c.

{
    yajl_gen g = NULL;
    yajl_alloc_funcs afsBuffer;

    /* first order of business is to set up memory allocation routines */
    if (afs != NULL) {
        if (afs->malloc == NULL || afs->realloc == NULL || afs->free == NULL)
        {
            return NULL;
        }
    } else {
        yajl_set_default_alloc_funcs(&afsBuffer);
        afs = &afsBuffer;
    }

    g = (yajl_gen) YA_MALLOC(afs, sizeof(struct yajl_gen_t));
    if (!g) return NULL;

    memset((void *) g, 0, sizeof(struct yajl_gen_t));
    /* copy in pointers to allocation routines */
    memcpy((void *) &(g->alloc), (void *) afs, sizeof(yajl_alloc_funcs));

    g->print = (yajl_print_t)&yajl_buf_append;
    g->ctx = yajl_buf_alloc(&(g->alloc));
    g->indentString = "    ";

    return g;
}

YAJL_API yajl_gen_status yajl_gen_array_close

(

yajl_gen

hand

)

Finish generating a JSON array.

Definition at line 318 of file yajl_gen.c.

{
    ENSURE_VALID_STATE;
    DECREMENT_DEPTH;
    if ((g->flags & yajl_gen_beautify)) g->print(g->ctx, "\n", 1);
    APPENDED_ATOM;
    INSERT_WHITESPACE;
    g->print(g->ctx, "]", 1);
    FINAL_NEWLINE;
    return yajl_gen_status_ok;
}

YAJL_API yajl_gen_status yajl_gen_array_open

(

yajl_gen

hand

)

Start generating a JSON array.

Definition at line 306 of file yajl_gen.c.

{
    ENSURE_VALID_STATE; ENSURE_NOT_KEY; INSERT_SEP; INSERT_WHITESPACE;
    INCREMENT_DEPTH;
    g->state[g->depth] = yajl_gen_array_start;
    g->print(g->ctx, "[", 1);
    if ((g->flags & yajl_gen_beautify)) g->print(g->ctx, "\n", 1);
    FINAL_NEWLINE;
    return yajl_gen_status_ok;
}

YAJL_API yajl_gen_status yajl_gen_bool	(	yajl_gen	hand,
		int	boolean
	)

Generate a true or false value from boolean.

Definition at line 267 of file yajl_gen.c.

{
    const char * val = boolean ? "true" : "false";

    ENSURE_VALID_STATE; ENSURE_NOT_KEY; INSERT_SEP; INSERT_WHITESPACE;
    g->print(g->ctx, val, (unsigned int)strlen(val));
    APPENDED_ATOM;
    FINAL_NEWLINE;
    return yajl_gen_status_ok;
}

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

Definition at line 341 of file yajl_gen.c.

{
    if (g->print == (yajl_print_t)&yajl_buf_append) yajl_buf_clear((yajl_buf)g->ctx);
}

YAJL_API int yajl_gen_config	(	yajl_gen	g,
		yajl_gen_option	opt,
			...
	)

Allow the modification of generator options subsequent to handle allocation (via yajl_alloc())

Returns

zero in case of errors, non-zero otherwise

Definition at line 51 of file yajl_gen.c.

{
    int rv = 1;
    va_list ap;
    va_start(ap, opt);

    switch(opt) {
        case yajl_gen_beautify:
        case yajl_gen_validate_utf8:
            if (va_arg(ap, int)) g->flags |= opt;
            else g->flags &= ~opt;
            break;
        case yajl_gen_indent_string: {
            const char *indent = va_arg(ap, const char *);
            g->indentString = indent;
            for (; *indent; indent++) {
                if (*indent != '\n'
                    && *indent != '\v'
                    && *indent != '\f'
                    && *indent != '\t'
                    && *indent != '\r'
                    && *indent != ' ')
                {
                    g->indentString = NULL;
                    rv = 0;
                }
            }
            break;
        }
        case yajl_gen_print_callback:
            yajl_buf_free(g->ctx);
            g->print = va_arg(ap, const yajl_print_t);
            g->ctx = va_arg(ap, void *);
            break;
        default:
            rv = 0;
    }

    va_end(ap);

    return rv;
}

YAJL_API yajl_gen_status yajl_gen_double	(	yajl_gen	hand,
		double	number
	)

Generate a floating point number. number may not be infinity or NaN, as these have no representation in JSON. In these cases the generator will return yajl_gen_invalid_number

Definition at line 212 of file yajl_gen.c.

{
    char i[32];
    ENSURE_VALID_STATE; ENSURE_NOT_KEY;
    if (isnan(number) || isinf(number)) return yajl_gen_invalid_number;
    INSERT_SEP; INSERT_WHITESPACE;
    sprintf(i, "%.20g", number);
    g->print(g->ctx, i, (unsigned int)strlen(i));
    APPENDED_ATOM;
    FINAL_NEWLINE;
    return yajl_gen_status_ok;
}

YAJL_API void yajl_gen_free

(

yajl_gen

handle

)

Free a generator handle

Definition at line 128 of file yajl_gen.c.

{
    if (g->print == (yajl_print_t)&yajl_buf_append) yajl_buf_free((yajl_buf)g->ctx);
    YA_FREE(&(g->alloc), g);
}

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

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

Definition at line 331 of file yajl_gen.c.

{
    if (g->print != (yajl_print_t)&yajl_buf_append) return yajl_gen_no_buf;
    *buf = yajl_buf_data((yajl_buf)g->ctx);
    *len = yajl_buf_len((yajl_buf)g->ctx);
    return yajl_gen_status_ok;
}

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

Generate an integer number.

Definition at line 200 of file yajl_gen.c.

{
    char i[32];
    ENSURE_VALID_STATE; ENSURE_NOT_KEY; INSERT_SEP; INSERT_WHITESPACE;
    sprintf(i, "%lld", number);
    g->print(g->ctx, i, (unsigned int)strlen(i));
    APPENDED_ATOM;
    FINAL_NEWLINE;
    return yajl_gen_status_ok;
}

YAJL_API yajl_gen_status yajl_gen_map_close

(

yajl_gen

hand

)

Finish generating a JSON map.

Definition at line 292 of file yajl_gen.c.

{
    ENSURE_VALID_STATE;
    DECREMENT_DEPTH;

    if ((g->flags & yajl_gen_beautify)) g->print(g->ctx, "\n", 1);
    APPENDED_ATOM;
    INSERT_WHITESPACE;
    g->print(g->ctx, "}", 1);
    FINAL_NEWLINE;
    return yajl_gen_status_ok;
}

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.

Definition at line 279 of file yajl_gen.c.

{
    ENSURE_VALID_STATE; ENSURE_NOT_KEY; INSERT_SEP; INSERT_WHITESPACE;
    INCREMENT_DEPTH;

    g->state[g->depth] = yajl_gen_map_start;
    g->print(g->ctx, "{", 1);
    if ((g->flags & yajl_gen_beautify)) g->print(g->ctx, "\n", 1);
    FINAL_NEWLINE;
    return yajl_gen_status_ok;
}

YAJL_API yajl_gen_status yajl_gen_null

(

yajl_gen

hand

)

Generate a null value.

Definition at line 257 of file yajl_gen.c.

{
    ENSURE_VALID_STATE; ENSURE_NOT_KEY; INSERT_SEP; INSERT_WHITESPACE;
    g->print(g->ctx, "null", strlen("null"));
    APPENDED_ATOM;
    FINAL_NEWLINE;
    return yajl_gen_status_ok;
}

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.

Definition at line 226 of file yajl_gen.c.

{
    ENSURE_VALID_STATE; ENSURE_NOT_KEY; INSERT_SEP; INSERT_WHITESPACE;
    g->print(g->ctx, s, l);
    APPENDED_ATOM;
    FINAL_NEWLINE;
    return yajl_gen_status_ok;
}

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.

Definition at line 236 of file yajl_gen.c.

{
    // if validation is enabled, check that the string is valid utf8
    // XXX: This checking could be done a little faster, in the same pass as
    // the string encoding
    if (g->flags & yajl_gen_validate_utf8) {
        if (!yajl_string_validate_utf8(str, len)) {
            return yajl_gen_invalid_string;
        }
    }
    ENSURE_VALID_STATE; INSERT_SEP; INSERT_WHITESPACE;
    g->print(g->ctx, "\"", 1);
    yajl_string_encode(g->print, g->ctx, str, len, g->flags & yajl_gen_escape_solidus);
    g->print(g->ctx, "\"", 1);
    APPENDED_ATOM;
    FINAL_NEWLINE;
    return yajl_gen_status_ok;
}