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 /**
  13  * @file
  14  * @brief Methods to parse an input string into a tree of json_object objects.
  15  */
  16 #ifndef _json_tokener_h_
  17 #define _json_tokener_h_
  18
  19 #include "json_object.h"
  20 #include <stddef.h>
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 enum json_tokener_error
  27 {
  28         json_tokener_success,
  29         json_tokener_continue,
  30         json_tokener_error_depth,
  31         json_tokener_error_parse_eof,
  32         json_tokener_error_parse_unexpected,
  33         json_tokener_error_parse_null,
  34         json_tokener_error_parse_boolean,
  35         json_tokener_error_parse_number,
  36         json_tokener_error_parse_array,
  37         json_tokener_error_parse_object_key_name,
  38         json_tokener_error_parse_object_key_sep,
  39         json_tokener_error_parse_object_value_sep,
  40         json_tokener_error_parse_string,
  41         json_tokener_error_parse_comment,
  42         json_tokener_error_parse_utf8_string,
  43         json_tokener_error_memory,
  44         json_tokener_error_size
  45 };
  46
  47 /**
  48  * @deprecated Don't use this outside of json_tokener.c, it will be made private in a future release.
  49  */
  50 enum json_tokener_state
  51 {
  52         json_tokener_state_eatws,
  53         json_tokener_state_start,
  54         json_tokener_state_finish,
  55         json_tokener_state_null,
  56         json_tokener_state_comment_start,
  57         json_tokener_state_comment,
  58         json_tokener_state_comment_eol,
  59         json_tokener_state_comment_end,
  60         json_tokener_state_string,
  61         json_tokener_state_string_escape,
  62         json_tokener_state_escape_unicode,
  63         json_tokener_state_escape_unicode_need_escape,
  64         json_tokener_state_escape_unicode_need_u,
  65         json_tokener_state_boolean,
  66         json_tokener_state_number,
  67         json_tokener_state_array,
  68         json_tokener_state_array_add,
  69         json_tokener_state_array_sep,
  70         json_tokener_state_object_field_start,
  71         json_tokener_state_object_field,
  72         json_tokener_state_object_field_end,
  73         json_tokener_state_object_value,
  74         json_tokener_state_object_value_add,
  75         json_tokener_state_object_sep,
  76         json_tokener_state_array_after_sep,
  77         json_tokener_state_object_field_start_after_sep,
  78         json_tokener_state_inf
  79 };
  80
  81 /**
  82  * @deprecated Don't use this outside of json_tokener.c, it will be made private in a future release.
  83  */
  84 struct json_tokener_srec
  85 {
  86         enum json_tokener_state state, saved_state;
  87         struct json_object *obj;
  88         struct json_object *current;
  89         char *obj_field_name;
  90 };
  91
  92 #define JSON_TOKENER_DEFAULT_DEPTH 32
  93
  94 /**
  95  * Internal state of the json parser.
  96  * Do not access any fields of this structure directly.
  97  * Its definition is published due to historical limitations
  98  * in the json tokener API, and will be changed to be an opaque
  99  * type in the future.
 100  */
 101 struct json_tokener
 102 {
 103         /**
 104          * @deprecated Do not access any of these fields outside of json_tokener.c
 105          */
 106         char *str;
 107         struct printbuf *pb;
 108         int max_depth, depth, is_double, st_pos;
 109         /**
 110          * @deprecated See json_tokener_get_parse_end() instead.
 111          */
 112         int char_offset;
 113         /**
 114          * @deprecated See json_tokener_get_error() instead.
 115          */
 116         enum json_tokener_error err;
 117         unsigned int ucs_char, high_surrogate;
 118         char quote_char;
 119         struct json_tokener_srec *stack;
 120         int flags;
 121 };
 122
 123 /**
 124  * Return the offset of the byte after the last byte parsed
 125  * relative to the start of the most recent string passed in
 126  * to json_tokener_parse_ex().  i.e. this is where parsing
 127  * would start again if the input contains another JSON object
 128  * after the currently parsed one.
 129  *
 130  * Note that when multiple parse calls are issued, this is *not* the
 131  * total number of characters parsed.
 132  *
 133  * In the past this would have been accessed as tok->char_offset.
 134  *
 135  * See json_tokener_parse_ex() for an example of how to use this.
 136  */
 137 JSON_EXPORT size_t json_tokener_get_parse_end(struct json_tokener *tok);
 138
 139 /**
 140  * @deprecated Unused in json-c code
 141  */
 142 typedef struct json_tokener json_tokener;
 143
 144 /**
 145  * Be strict when parsing JSON input.  Use caution with
 146  * this flag as what is considered valid may become more
 147  * restrictive from one release to the next, causing your
 148  * code to fail on previously working input.
 149  *
 150  * Note that setting this will also effectively disable parsing
 151  * of multiple json objects in a single character stream
 152  * (e.g. {"foo":123}{"bar":234}); if you want to allow that
 153  * also set JSON_TOKENER_ALLOW_TRAILING_CHARS
 154  *
 155  * This flag is not set by default.
 156  *
 157  * @see json_tokener_set_flags()
 158  */
 159 #define JSON_TOKENER_STRICT 0x01
 160
 161 /**
 162  * Use with JSON_TOKENER_STRICT to allow trailing characters after the
 163  * first parsed object.
 164  *
 165  * @see json_tokener_set_flags()
 166  */
 167 #define JSON_TOKENER_ALLOW_TRAILING_CHARS 0x02
 168
 169 /**
 170  * Cause json_tokener_parse_ex() to validate that input is UTF8.
 171  * If this flag is specified and validation fails, then
 172  * json_tokener_get_error(tok) will return
 173  * json_tokener_error_parse_utf8_string
 174  *
 175  * This flag is not set by default.
 176  *
 177  * @see json_tokener_set_flags()
 178  */
 179 #define JSON_TOKENER_VALIDATE_UTF8 0x10
 180
 181 /**
 182  * Given an error previously returned by json_tokener_get_error(),
 183  * return a human readable description of the error.
 184  *
 185  * @return a generic error message is returned if an invalid error value is provided.
 186  */
 187 JSON_EXPORT const char *json_tokener_error_desc(enum json_tokener_error jerr);
 188
 189 /**
 190  * Retrieve the error caused by the last call to json_tokener_parse_ex(),
 191  * or json_tokener_success if there is no error.
 192  *
 193  * When parsing a JSON string in pieces, if the tokener is in the middle
 194  * of parsing this will return json_tokener_continue.
 195  *
 196  * @see json_tokener_error_desc().
 197  */
 198 JSON_EXPORT enum json_tokener_error json_tokener_get_error(struct json_tokener *tok);
 199
 200 /**
 201  * Allocate a new json_tokener.
 202  * When done using that to parse objects, free it with json_tokener_free().
 203  * See json_tokener_parse_ex() for usage details.
 204  */
 205 JSON_EXPORT struct json_tokener *json_tokener_new(void);
 206
 207 /**
 208  * Allocate a new json_tokener with a custom max nesting depth.
 209  * @see JSON_TOKENER_DEFAULT_DEPTH
 210  */
 211 JSON_EXPORT struct json_tokener *json_tokener_new_ex(int depth);
 212
 213 /**
 214  * Free a json_tokener previously allocated with json_tokener_new().
 215  */
 216 JSON_EXPORT void json_tokener_free(struct json_tokener *tok);
 217
 218 /**
 219  * Reset the state of a json_tokener, to prepare to parse a
 220  * brand new JSON object.
 221  */
 222 JSON_EXPORT void json_tokener_reset(struct json_tokener *tok);
 223
 224 /**
 225  * Parse a json_object out of the string `str`.
 226  *
 227  * If you need more control over how the parsing occurs,
 228  * see json_tokener_parse_ex().
 229  */
 230 JSON_EXPORT struct json_object *json_tokener_parse(const char *str);
 231
 232 /**
 233  * Parser a json_object out of the string `str`, but if it fails
 234  * return the error in `*error`.
 235  * @see json_tokener_parse()
 236  * @see json_tokener_parse_ex()
 237  */
 238 JSON_EXPORT struct json_object *json_tokener_parse_verbose(const char *str,
 239                                                            enum json_tokener_error *error);
 240
 241 /**
 242  * Set flags that control how parsing will be done.
 243  */
 244 JSON_EXPORT void json_tokener_set_flags(struct json_tokener *tok, int flags);
 245
 246 /**
 247  * Parse a string and return a non-NULL json_object if a valid JSON value
 248  * is found.  The string does not need to be a JSON object or array;
 249  * it can also be a string, number or boolean value.
 250  *
 251  * A partial JSON string can be parsed.  If the parsing is incomplete,
 252  * NULL will be returned and json_tokener_get_error() will return
 253  * json_tokener_continue.
 254  * json_tokener_parse_ex() can then be called with additional bytes in str
 255  * to continue the parsing.
 256  *
 257  * If json_tokener_parse_ex() returns NULL and the error is anything other than
 258  * json_tokener_continue, a fatal error has occurred and parsing must be
 259  * halted.  Then, the tok object must not be reused until json_tokener_reset()
 260  * is called.
 261  *
 262  * When a valid JSON value is parsed, a non-NULL json_object will be
 263  * returned, with a reference count of one which belongs to the caller.  Also,
 264  * json_tokener_get_error() will return json_tokener_success. Be sure to check
 265  * the type with json_object_is_type() or json_object_get_type() before using
 266  * the object.
 267  *
 268  * Trailing characters after the parsed value do not automatically cause an
 269  * error.  It is up to the caller to decide whether to treat this as an
 270  * error or to handle the additional characters, perhaps by parsing another
 271  * json value starting from that point.
 272  *
 273  * If the caller knows that they are at the end of their input, the length
 274  * passed MUST include the final '\0' character, so values with no inherent
 275  * end (i.e. numbers) can be properly parsed, rather than just returning
 276  * json_tokener_continue.
 277  *
 278  * Extra characters can be detected by comparing the value returned by
 279  * json_tokener_get_parse_end() against
 280  * the length of the last len parameter passed in.
 281  *
 282  * The tokener does \b not maintain an internal buffer so the caller is
 283  * responsible for a subsequent call to json_tokener_parse_ex with an
 284  * appropriate str parameter starting with the extra characters.
 285  *
 286  * This interface is presently not 64-bit clean due to the int len argument
 287  * so the function limits the maximum string size to INT32_MAX (2GB).
 288  * If the function is called with len == -1 then strlen is called to check
 289  * the string length is less than INT32_MAX (2GB)
 290  *
 291  * Example:
 292  * @code
 293 json_object *jobj = NULL;
 294 const char *mystring = NULL;
 295 int stringlen = 0;
 296 enum json_tokener_error jerr;
 297 do {
 298         mystring = ...  // get JSON string, e.g. read from file, etc...
 299         stringlen = strlen(mystring);
 300         if (end_of_input)
 301                 stringlen++;  // Include the '\0' if we know we're at the end of input
 302         jobj = json_tokener_parse_ex(tok, mystring, stringlen);
 303 } while ((jerr = json_tokener_get_error(tok)) == json_tokener_continue);
 304 if (jerr != json_tokener_success)
 305 {
 306         fprintf(stderr, "Error: %s\n", json_tokener_error_desc(jerr));
 307         // Handle errors, as appropriate for your application.
 308 }
 309 if (json_tokener_get_parse_end(tok) < stringlen)
 310 {
 311         // Handle extra characters after parsed object as desired.
 312         // e.g. issue an error, parse another object from that point, etc...
 313 }
 314 // Success, use jobj here.
 315
 316 @endcode
 317  *
 318  * @param tok a json_tokener previously allocated with json_tokener_new()
 319  * @param str an string with any valid JSON expression, or portion of.  This does not need to be null terminated.
 320  * @param len the length of str
 321  */
 322 JSON_EXPORT struct json_object *json_tokener_parse_ex(struct json_tokener *tok, const char *str,
 323                                                       int len);
 324
 325 #ifdef __cplusplus
 326 }
 327 #endif
 328
 329 #endif