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