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 };
  63
  64 struct json_tokener_srec
  65 {
  66   enum json_tokener_state state, saved_state;
  67   struct json_object *obj;
  68   struct json_object *current;
  69   char *obj_field_name;
  70 };
  71
  72 #define JSON_TOKENER_MAX_DEPTH 32
  73
  74 struct json_tokener
  75 {
  76   char *str;
  77   struct printbuf *pb;
  78   int depth, is_double, st_pos, char_offset;
  79   enum json_tokener_error err;
  80   unsigned int ucs_char;
  81   char quote_char;
  82   struct json_tokener_srec stack[JSON_TOKENER_MAX_DEPTH];
  83 };
  84
  85 /**
  86  * Given an error previously returned by json_tokener_get_error(),
  87  * return a human readable description of the error.
  88  *
  89  * @return a generic error message is returned if an invalid error value is provided.
  90  */
  91 const char *json_tokener_error_desc(enum json_tokener_error jerr);
  92
  93 /**
  94  * @b XXX do not use json_tokener_errors directly.
  95  * After v0.10 this will be removed.
  96  *
  97  * See json_tokener_error_desc() instead.
  98  */
  99 extern const char* json_tokener_errors[];
 100
 101 /**
 102  * Retrieve the error caused by the last call to json_tokener_parse_ex(),
 103  * or json_tokener_success if there is no error.
 104  *
 105  * When parsing a JSON string in pieces, if the tokener is in the middle
 106  * of parsing this will return json_tokener_continue.
 107  *
 108  * See also json_tokener_error_desc().
 109  */
 110 enum json_tokener_error json_tokener_get_error(struct json_tokener *tok);
 111
 112 extern struct json_tokener* json_tokener_new(void);
 113 extern void json_tokener_free(struct json_tokener *tok);
 114 extern void json_tokener_reset(struct json_tokener *tok);
 115 extern struct json_object* json_tokener_parse(const char *str);
 116 extern struct json_object* json_tokener_parse_verbose(const char *str, enum json_tokener_error *error);
 117
 118 /**
 119  * Parse a string and return a non-NULL json_object if a valid JSON value
 120  * is found.  The string does not need to be a JSON object or array;
 121  * it can also be a string, number or boolean value.
 122  *
 123  * A partial JSON string can be parsed.  If the parsing is incomplete,
 124  * NULL will be returned and json_tokener_get_error() will be return
 125  * json_tokener_continue.
 126  * json_tokener_parse_ex() can then be called with additional bytes in str
 127  * to continue the parsing.
 128  *
 129  * If json_tokener_parse_ex() returns NULL and the error anything other than
 130  * json_tokener_continue, a fatal error has occurred and parsing must be
 131  * halted.  Then tok object must not be re-used until json_tokener_reset() is
 132  * called.
 133  *
 134  * When a valid JSON value is parsed, a non-NULL json_object will be
 135  * returned.  Also, json_tokener_get_error() will return json_tokener_success.
 136  * Be sure to check the type with json_object_is_type() or
 137  * json_object_get_type() before using the object.
 138  *
 139  * @b XXX this shouldn't use internal fields:
 140  * Trailing characters after the parsed value do not automatically cause an
 141  * error.  It is up to the caller to decide whether to treat this as an
 142  * error or to handle the additional characters, perhaps by parsing another
 143  * json value starting from that point.
 144  *
 145  * Extra characters can be detected by comparing the tok->char_offset against
 146  * the length of the last len parameter passed in.
 147  *
 148  * The tokener does \b not maintain an internal buffer so the caller is
 149  * responsible for calling json_tokener_parse_ex with an appropriate str
 150  * parameter starting with the extra characters.
 151  *
 152  * Example:
 153  * @code
 154 json_object *jobj = NULL;
 155 const char *mystring = NULL;
 156 int stringlen = 0;
 157 enum json_tokener_error jerr;
 158 do {
 159         mystring = ...  // get JSON string, e.g. read from file, etc...
 160         stringlen = strlen(mystring);
 161         jobj = json_tokener_parse_ex(tok, mystring, stringlen);
 162 } while ((jerr = json_tokener_get_error(tok)) == json_tokener_continue);
 163 if (jerr != json_tokener_success)
 164 {
 165         fprintf(stderr, "Error: %s\n", json_tokener_error_desc(jerr));
 166         // Handle errors, as appropriate for your application.
 167 }
 168 if (tok->char_offset < stringlen) // XXX shouldn't access internal fields
 169 {
 170         // Handle extra characters after parsed object as desired.
 171         // e.g. issue an error, parse another object from that point, etc...
 172 }
 173 // Success, use jobj here.
 174
 175 @endcode
 176  *
 177  * @param tok a json_tokener previously allocated with json_tokener_new()
 178  * @param str an string with any valid JSON expression, or portion of.  This does not need to be null terminated.
 179  * @param len the length of str
 180  */
 181 extern struct json_object* json_tokener_parse_ex(struct json_tokener *tok,
 182                                                  const char *str, int len);
 183
 184 #ifdef __cplusplus
 185 }
 186 #endif
 187
 188 #endif