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_DEFAULT_DEPTH 32
  73
  74 struct json_tokener
  75 {
  76   char *str;
  77   struct printbuf *pb;
  78   int max_depth, 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;
  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 struct json_tokener* json_tokener_new_ex(int depth);
 114 extern void json_tokener_free(struct json_tokener *tok);
 115 extern void json_tokener_reset(struct json_tokener *tok);
 116 extern struct json_object* json_tokener_parse(const char *str);
 117 extern struct json_object* json_tokener_parse_verbose(const char *str, enum json_tokener_error *error);
 118
 119 /**
 120  * Parse a string and return a non-NULL json_object if a valid JSON value
 121  * is found.  The string does not need to be a JSON object or array;
 122  * it can also be a string, number or boolean value.
 123  *
 124  * A partial JSON string can be parsed.  If the parsing is incomplete,
 125  * NULL will be returned and json_tokener_get_error() will be return
 126  * json_tokener_continue.
 127  * json_tokener_parse_ex() can then be called with additional bytes in str
 128  * to continue the parsing.
 129  *
 130  * If json_tokener_parse_ex() returns NULL and the error anything other than
 131  * json_tokener_continue, a fatal error has occurred and parsing must be
 132  * halted.  Then tok object must not be re-used until json_tokener_reset() is
 133  * called.
 134  *
 135  * When a valid JSON value is parsed, a non-NULL json_object will be
 136  * returned.  Also, json_tokener_get_error() will return json_tokener_success.
 137  * Be sure to check the type with json_object_is_type() or
 138  * json_object_get_type() before using the object.
 139  *
 140  * @b XXX this shouldn't use internal fields:
 141  * Trailing characters after the parsed value do not automatically cause an
 142  * error.  It is up to the caller to decide whether to treat this as an
 143  * error or to handle the additional characters, perhaps by parsing another
 144  * json value starting from that point.
 145  *
 146  * Extra characters can be detected by comparing the tok->char_offset against
 147  * the length of the last len parameter passed in.
 148  *
 149  * The tokener does \b not maintain an internal buffer so the caller is
 150  * responsible for calling json_tokener_parse_ex with an appropriate str
 151  * parameter starting with the extra characters.
 152  *
 153  * Example:
 154  * @code
 155 json_object *jobj = NULL;
 156 const char *mystring = NULL;
 157 int stringlen = 0;
 158 enum json_tokener_error jerr;
 159 do {
 160         mystring = ...  // get JSON string, e.g. read from file, etc...
 161         stringlen = strlen(mystring);
 162         jobj = json_tokener_parse_ex(tok, mystring, stringlen);
 163 } while ((jerr = json_tokener_get_error(tok)) == json_tokener_continue);
 164 if (jerr != json_tokener_success)
 165 {
 166         fprintf(stderr, "Error: %s\n", json_tokener_error_desc(jerr));
 167         // Handle errors, as appropriate for your application.
 168 }
 169 if (tok->char_offset < stringlen) // XXX shouldn't access internal fields
 170 {
 171         // Handle extra characters after parsed object as desired.
 172         // e.g. issue an error, parse another object from that point, etc...
 173 }
 174 // Success, use jobj here.
 175
 176 @endcode
 177  *
 178  * @param tok a json_tokener previously allocated with json_tokener_new()
 179  * @param str an string with any valid JSON expression, or portion of.  This does not need to be null terminated.
 180  * @param len the length of str
 181  */
 182 extern struct json_object* json_tokener_parse_ex(struct json_tokener *tok,
 183                                                  const char *str, int len);
 184
 185 #ifdef __cplusplus
 186 }
 187 #endif
 188
 189 #endif