• source navigation  • diff markup  • identifier search  • freetext search  • 

Sources/json-c/json_tokener.h

  1 /*
  2  * $Id: json_tokener.h,v 1.10 2006/07/25 03:24:50 mclark Exp $
  3  *
  4  * Copyright (c) 2004, 2005 Metaparadigm Pte. Ltd.
  5  * Michael Clark <michael@metaparadigm.com>
  6  *
  7  * This library is free software; you can redistribute it and/or modify
  8  * it under the terms of the MIT license. See COPYING for details.
  9  *
 10  */
 11 
 12 #ifndef _json_tokener_h_
 13 #define _json_tokener_h_
 14 
 15 #include <stddef.h>
 16 #include "json_object.h"
 17 
 18 #ifdef __cplusplus
 19 extern "C" {
 20 #endif
 21 
 22 enum json_tokener_error {
 23   json_tokener_success,
 24   json_tokener_continue,
 25   json_tokener_error_depth,
 26   json_tokener_error_parse_eof,
 27   json_tokener_error_parse_unexpected,
 28   json_tokener_error_parse_null,
 29   json_tokener_error_parse_boolean,
 30   json_tokener_error_parse_number,
 31   json_tokener_error_parse_array,
 32   json_tokener_error_parse_object_key_name,
 33   json_tokener_error_parse_object_key_sep,
 34   json_tokener_error_parse_object_value_sep,
 35   json_tokener_error_parse_string,
 36   json_tokener_error_parse_comment
 37 };
 38 
 39 enum json_tokener_state {
 40   json_tokener_state_eatws,
 41   json_tokener_state_start,
 42   json_tokener_state_finish,
 43   json_tokener_state_null,
 44   json_tokener_state_comment_start,
 45   json_tokener_state_comment,
 46   json_tokener_state_comment_eol,
 47   json_tokener_state_comment_end,
 48   json_tokener_state_string,
 49   json_tokener_state_string_escape,
 50   json_tokener_state_escape_unicode,
 51   json_tokener_state_boolean,
 52   json_tokener_state_number,
 53   json_tokener_state_array,
 54   json_tokener_state_array_add,
 55   json_tokener_state_array_sep,
 56   json_tokener_state_object_field_start,
 57   json_tokener_state_object_field,
 58   json_tokener_state_object_field_end,
 59   json_tokener_state_object_value,
 60   json_tokener_state_object_value_add,
 61   json_tokener_state_object_sep,
 62   json_tokener_state_array_after_sep,
 63   json_tokener_state_object_field_start_after_sep
 64 };
 65 
 66 struct json_tokener_srec
 67 {
 68   enum json_tokener_state state, saved_state;
 69   struct json_object *obj;
 70   struct json_object *current;
 71   char *obj_field_name;
 72 };
 73 
 74 #define JSON_TOKENER_DEFAULT_DEPTH 32
 75 
 76 struct json_tokener
 77 {
 78   char *str;
 79   struct printbuf *pb;
 80   int max_depth, depth, is_double, st_pos, char_offset;
 81   enum json_tokener_error err;
 82   unsigned int ucs_char;
 83   char quote_char;
 84   struct json_tokener_srec *stack;
 85   int flags;
 86 };
 87 
 88 /**
 89  * Be strict when parsing JSON input.  Use caution with
 90  * this flag as what is considered valid may become more
 91  * restrictive from one release to the next, causing your
 92  * code to fail on previously working input.
 93  *
 94  * This flag is not set by default.
 95  *
 96  * @see json_tokener_set_flags()
 97  */
 98 #define JSON_TOKENER_STRICT  0x01
 99 
100 /**
101  * Given an error previously returned by json_tokener_get_error(),
102  * return a human readable description of the error.
103  *
104  * @return a generic error message is returned if an invalid error value is provided.
105  */
106 const char *json_tokener_error_desc(enum json_tokener_error jerr);
107 
108 /** 
109  * @b XXX do not use json_tokener_errors directly.  
110  * After v0.10 this will be removed.
111  *
112  * See json_tokener_error_desc() instead.
113  */
114 extern const char* json_tokener_errors[];
115 
116 /**
117  * Retrieve the error caused by the last call to json_tokener_parse_ex(),
118  * or json_tokener_success if there is no error.
119  *
120  * When parsing a JSON string in pieces, if the tokener is in the middle
121  * of parsing this will return json_tokener_continue.
122  *
123  * See also json_tokener_error_desc().
124  */
125 enum json_tokener_error json_tokener_get_error(struct json_tokener *tok);
126 
127 extern struct json_tokener* json_tokener_new(void);
128 extern struct json_tokener* json_tokener_new_ex(int depth);
129 extern void json_tokener_free(struct json_tokener *tok);
130 extern void json_tokener_reset(struct json_tokener *tok);
131 extern struct json_object* json_tokener_parse(const char *str);
132 extern struct json_object* json_tokener_parse_verbose(const char *str, enum json_tokener_error *error);
133 
134 /**
135  * Set flags that control how parsing will be done.
136  */
137 extern void json_tokener_set_flags(struct json_tokener *tok, int flags);
138 
139 /** 
140  * Parse a string and return a non-NULL json_object if a valid JSON value
141  * is found.  The string does not need to be a JSON object or array;
142  * it can also be a string, number or boolean value.
143  *
144  * A partial JSON string can be parsed.  If the parsing is incomplete,
145  * NULL will be returned and json_tokener_get_error() will be return 
146  * json_tokener_continue.
147  * json_tokener_parse_ex() can then be called with additional bytes in str
148  * to continue the parsing.  
149  *
150  * If json_tokener_parse_ex() returns NULL and the error anything other than
151  * json_tokener_continue, a fatal error has occurred and parsing must be
152  * halted.  Then tok object must not be re-used until json_tokener_reset() is
153  * called.
154  *
155  * When a valid JSON value is parsed, a non-NULL json_object will be
156  * returned.  Also, json_tokener_get_error() will return json_tokener_success.
157  * Be sure to check the type with json_object_is_type() or
158  * json_object_get_type() before using the object.
159  *
160  * @b XXX this shouldn't use internal fields:
161  * Trailing characters after the parsed value do not automatically cause an 
162  * error.  It is up to the caller to decide whether to treat this as an
163  * error or to handle the additional characters, perhaps by parsing another
164  * json value starting from that point.
165  *
166  * Extra characters can be detected by comparing the tok->char_offset against
167  * the length of the last len parameter passed in.
168  *
169  * The tokener does \b not maintain an internal buffer so the caller is
170  * responsible for calling json_tokener_parse_ex with an appropriate str
171  * parameter starting with the extra characters.
172  *
173  * Example:
174  * @code
175 json_object *jobj = NULL;
176 const char *mystring = NULL;
177 int stringlen = 0;
178 enum json_tokener_error jerr;
179 do {
180         mystring = ...  // get JSON string, e.g. read from file, etc...
181         stringlen = strlen(mystring);
182         jobj = json_tokener_parse_ex(tok, mystring, stringlen);
183 } while ((jerr = json_tokener_get_error(tok)) == json_tokener_continue);
184 if (jerr != json_tokener_success)
185 {
186         fprintf(stderr, "Error: %s\n", json_tokener_error_desc(jerr));
187         // Handle errors, as appropriate for your application.
188 }
189 if (tok->char_offset < stringlen) // XXX shouldn't access internal fields
190 {
191         // Handle extra characters after parsed object as desired.
192         // e.g. issue an error, parse another object from that point, etc...
193 }
194 // Success, use jobj here.
195 
196 @endcode
197  *
198  * @param tok a json_tokener previously allocated with json_tokener_new()
199  * @param str an string with any valid JSON expression, or portion of.  This does not need to be null terminated.
200  * @param len the length of str
201  */
202 extern struct json_object* json_tokener_parse_ex(struct json_tokener *tok,
203                                                  const char *str, int len);
204 
205 #ifdef __cplusplus
206 }
207 #endif
208 
209 #endif
210 

This page was automatically generated by LXR 0.3.1.  •  OpenWrt