Edit File: json_tokener.h
/* * $Id: json_tokener.h,v 1.10 2006/07/25 03:24:50 mclark Exp $ * * Copyright (c) 2004, 2005 Metaparadigm Pte. Ltd. * Michael Clark <michael@metaparadigm.com> * * This library is free software; you can redistribute it and/or modify * it under the terms of the MIT license. See COPYING for details. * */ /** * @file * @brief Methods to parse an input string into a tree of json_object objects. */ #ifndef _json_tokener_h_ #define _json_tokener_h_ #include <stddef.h> #include "json_object.h" #ifdef __cplusplus extern "C" { #endif enum json_tokener_error { json_tokener_success, json_tokener_continue, json_tokener_error_depth, json_tokener_error_parse_eof, json_tokener_error_parse_unexpected, json_tokener_error_parse_null, json_tokener_error_parse_boolean, json_tokener_error_parse_number, json_tokener_error_parse_array, json_tokener_error_parse_object_key_name, json_tokener_error_parse_object_key_sep, json_tokener_error_parse_object_value_sep, json_tokener_error_parse_string, json_tokener_error_parse_comment, json_tokener_error_size }; enum json_tokener_state { json_tokener_state_eatws, json_tokener_state_start, json_tokener_state_finish, json_tokener_state_null, json_tokener_state_comment_start, json_tokener_state_comment, json_tokener_state_comment_eol, json_tokener_state_comment_end, json_tokener_state_string, json_tokener_state_string_escape, json_tokener_state_escape_unicode, json_tokener_state_boolean, json_tokener_state_number, json_tokener_state_array, json_tokener_state_array_add, json_tokener_state_array_sep, json_tokener_state_object_field_start, json_tokener_state_object_field, json_tokener_state_object_field_end, json_tokener_state_object_value, json_tokener_state_object_value_add, json_tokener_state_object_sep, json_tokener_state_array_after_sep, json_tokener_state_object_field_start_after_sep, json_tokener_state_inf }; struct json_tokener_srec { enum json_tokener_state state, saved_state; struct json_object *obj; struct json_object *current; char *obj_field_name; }; #define JSON_TOKENER_DEFAULT_DEPTH 32 struct json_tokener { char *str; struct printbuf *pb; int max_depth, depth, is_double, st_pos, char_offset; enum json_tokener_error err; unsigned int ucs_char; char quote_char; struct json_tokener_srec *stack; int flags; }; /** * @deprecated Unused in json-c code */ typedef struct json_tokener json_tokener; /** * Be strict when parsing JSON input. Use caution with * this flag as what is considered valid may become more * restrictive from one release to the next, causing your * code to fail on previously working input. * * This flag is not set by default. * * @see json_tokener_set_flags() */ #define JSON_TOKENER_STRICT 0x01 /** * Given an error previously returned by json_tokener_get_error(), * return a human readable description of the error. * * @return a generic error message is returned if an invalid error value is provided. */ const char *json_tokener_error_desc(enum json_tokener_error jerr); /** * Retrieve the error caused by the last call to json_tokener_parse_ex(), * or json_tokener_success if there is no error. * * When parsing a JSON string in pieces, if the tokener is in the middle * of parsing this will return json_tokener_continue. * * See also json_tokener_error_desc(). */ JSON_EXPORT enum json_tokener_error json_tokener_get_error(struct json_tokener *tok); JSON_EXPORT struct json_tokener* json_tokener_new(void); JSON_EXPORT struct json_tokener* json_tokener_new_ex(int depth); JSON_EXPORT void json_tokener_free(struct json_tokener *tok); JSON_EXPORT void json_tokener_reset(struct json_tokener *tok); JSON_EXPORT struct json_object* json_tokener_parse(const char *str); JSON_EXPORT struct json_object* json_tokener_parse_verbose(const char *str, enum json_tokener_error *error); /** * Set flags that control how parsing will be done. */ JSON_EXPORT void json_tokener_set_flags(struct json_tokener *tok, int flags); /** * Parse a string and return a non-NULL json_object if a valid JSON value * is found. The string does not need to be a JSON object or array; * it can also be a string, number or boolean value. * * A partial JSON string can be parsed. If the parsing is incomplete, * NULL will be returned and json_tokener_get_error() will return * json_tokener_continue. * json_tokener_parse_ex() can then be called with additional bytes in str * to continue the parsing. * * If json_tokener_parse_ex() returns NULL and the error is anything other than * json_tokener_continue, a fatal error has occurred and parsing must be * halted. Then, the tok object must not be reused until json_tokener_reset() is * called. * * When a valid JSON value is parsed, a non-NULL json_object will be * returned. Also, json_tokener_get_error() will return json_tokener_success. * Be sure to check the type with json_object_is_type() or * json_object_get_type() before using the object. * * @b XXX this shouldn't use internal fields: * Trailing characters after the parsed value do not automatically cause an * error. It is up to the caller to decide whether to treat this as an * error or to handle the additional characters, perhaps by parsing another * json value starting from that point. * * Extra characters can be detected by comparing the tok->char_offset against * the length of the last len parameter passed in. * * The tokener does \b not maintain an internal buffer so the caller is * responsible for calling json_tokener_parse_ex with an appropriate str * parameter starting with the extra characters. * * This interface is presently not 64-bit clean due to the int len argument * so the function limits the maximum string size to INT32_MAX (2GB). * If the function is called with len == -1 then strlen is called to check * the string length is less than INT32_MAX (2GB) * * Example: * @code json_object *jobj = NULL; const char *mystring = NULL; int stringlen = 0; enum json_tokener_error jerr; do { mystring = ... // get JSON string, e.g. read from file, etc... stringlen = strlen(mystring); jobj = json_tokener_parse_ex(tok, mystring, stringlen); } while ((jerr = json_tokener_get_error(tok)) == json_tokener_continue); if (jerr != json_tokener_success) { fprintf(stderr, "Error: %s\n", json_tokener_error_desc(jerr)); // Handle errors, as appropriate for your application. } if (tok->char_offset < stringlen) // XXX shouldn't access internal fields { // Handle extra characters after parsed object as desired. // e.g. issue an error, parse another object from that point, etc... } // Success, use jobj here. @endcode * * @param tok a json_tokener previously allocated with json_tokener_new() * @param str an string with any valid JSON expression, or portion of. This does not need to be null terminated. * @param len the length of str */ JSON_EXPORT struct json_object* json_tokener_parse_ex(struct json_tokener *tok, const char *str, int len); #ifdef __cplusplus } #endif #endif