2 * Copyright 2007-2009, Lloyd Hilaiel.
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are
8 * 1. Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
11 * 2. Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in
13 * the documentation and/or other materials provided with the
16 * 3. Neither the name of Lloyd Hilaiel nor the names of its
17 * contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
20 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
21 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
22 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23 * DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
24 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
25 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
28 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
29 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30 * POSSIBILITY OF SUCH DAMAGE.
35 * Interface to YAJL's JSON parsing facilities.
38 #include <yajl/yajl_common.h>
40 #ifndef __YAJL_PARSE_H__
41 #define __YAJL_PARSE_H__
46 /** error codes returned from this interface */
48 /** no error was encountered */
50 /** a client callback returned zero, stopping the parse */
51 yajl_status_client_canceled
,
52 /** The parse cannot yet complete because more json input text
53 * is required, call yajl_parse with the next buffer of input text.
54 * (pertinent only when stream parsing) */
55 yajl_status_insufficient_data
,
56 /** An error occured during the parse. Call yajl_get_error for
57 * more information about the encountered error */
61 /** attain a human readable, english, string for an error */
62 const char * YAJL_API
yajl_status_to_string(yajl_status code
);
64 /** an opaque handle to a parser */
65 typedef struct yajl_handle_t
* yajl_handle
;
67 /** yajl is an event driven parser. this means as json elements are
68 * parsed, you are called back to do something with the data. The
69 * functions in this table indicate the various events for which
70 * you will be called back. Each callback accepts a "context"
71 * pointer, this is a void * that is passed into the yajl_parse
72 * function which the client code may use to pass around context.
74 * All callbacks return an integer. If non-zero, the parse will
75 * continue. If zero, the parse will be canceled and
76 * yajl_status_client_canceled will be returned from the parse.
78 * Note about handling of numbers:
79 * yajl will only convert numbers that can be represented in a double
80 * or a long int. All other numbers will be passed to the client
81 * in string form using the yajl_number callback. Furthermore, if
82 * yajl_number is not NULL, it will always be used to return numbers,
83 * that is yajl_integer and yajl_double will be ignored. If
84 * yajl_number is NULL but one of yajl_integer or yajl_double are
85 * defined, parsing of a number larger than is representable
86 * in a double or long int will result in a parse error.
89 int (* yajl_null
)(void * ctx
);
90 int (* yajl_boolean
)(void * ctx
, int boolVal
);
91 int (* yajl_integer
)(void * ctx
, long integerVal
);
92 int (* yajl_double
)(void * ctx
, double doubleVal
);
93 /** A callback which passes the string representation of the number
94 * back to the client. Will be used for all numbers when present */
95 int (* yajl_number
)(void * ctx
, const char * numberVal
,
96 unsigned int numberLen
);
98 /** strings are returned as pointers into the JSON text when,
99 * possible, as a result, they are _not_ null padded */
100 int (* yajl_string
)(void * ctx
, const unsigned char * stringVal
,
101 unsigned int stringLen
);
103 int (* yajl_start_map
)(void * ctx
);
104 int (* yajl_map_key
)(void * ctx
, const unsigned char * key
,
105 unsigned int stringLen
);
106 int (* yajl_end_map
)(void * ctx
);
108 int (* yajl_start_array
)(void * ctx
);
109 int (* yajl_end_array
)(void * ctx
);
112 /** configuration structure for the generator */
114 /** if nonzero, javascript style comments will be allowed in
115 * the json input, both slash star and slash slash */
116 unsigned int allowComments
;
117 /** if nonzero, invalid UTF8 strings will cause a parse
119 unsigned int checkUTF8
;
120 } yajl_parser_config
;
122 /** allocate a parser handle
123 * \param callbacks a yajl callbacks structure specifying the
124 * functions to call when different JSON entities
125 * are encountered in the input text. May be NULL,
126 * which is only useful for validation.
127 * \param config configuration parameters for the parse.
128 * \param ctx a context pointer that will be passed to callbacks.
130 yajl_handle YAJL_API
yajl_alloc(const yajl_callbacks
* callbacks
,
131 const yajl_parser_config
* config
,
132 const yajl_alloc_funcs
* allocFuncs
,
135 /** free a parser handle */
136 void YAJL_API
yajl_free(yajl_handle handle
);
139 * \param hand - a handle to the json parser allocated with yajl_alloc
140 * \param jsonText - a pointer to the UTF8 json text to be parsed
141 * \param jsonTextLength - the length, in bytes, of input text
143 yajl_status YAJL_API
yajl_parse(yajl_handle hand
,
144 const unsigned char * jsonText
,
145 unsigned int jsonTextLength
);
147 /** Parse any remaining buffered json.
148 * Since yajl is a stream-based parser, without an explicit end of
149 * input, yajl sometimes can't decide if content at the end of the
150 * stream is valid or not. For example, if "1" has been fed in,
151 * yajl can't know whether another digit is next or some character
152 * that would terminate the integer token.
154 * \param hand - a handle to the json parser allocated with yajl_alloc
156 yajl_status
yajl_parse_complete(yajl_handle hand
);
158 /** get an error string describing the state of the
161 * If verbose is non-zero, the message will include the JSON
162 * text where the error occured, along with an arrow pointing to
165 * A dynamically allocated string will be returned which should
166 * be freed with yajl_free_error
168 unsigned char * YAJL_API
yajl_get_error(yajl_handle hand
, int verbose
,
169 const unsigned char * jsonText
,
170 unsigned int jsonTextLength
);
172 /** free an error returned from yajl_get_error */
173 void YAJL_API
yajl_free_error(yajl_handle hand
, unsigned char * str
);