diff options
Diffstat (limited to 'comm/third_party/json-c/json_tokener.h')
| -rw-r--r-- | comm/third_party/json-c/json_tokener.h | 328 |
1 files changed, 328 insertions, 0 deletions
diff --git a/comm/third_party/json-c/json_tokener.h b/comm/third_party/json-c/json_tokener.h new file mode 100644 index 0000000000..a07e12ce7e --- /dev/null +++ b/comm/third_party/json-c/json_tokener.h @@ -0,0 +1,328 @@ +/* + * $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 "json_object.h" +#include <stddef.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_parse_utf8_string, + json_tokener_error_size +}; + +/** + * @deprecated Don't use this outside of json_tokener.c, it will be made private in a future release. + */ +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_escape_unicode_need_escape, + json_tokener_state_escape_unicode_need_u, + 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 +}; + +/** + * @deprecated Don't use this outside of json_tokener.c, it will be made private in a future release. + */ +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 + +/** + * Internal state of the json parser. + * Do not access any fields of this structure directly. + * Its definition is published due to historical limitations + * in the json tokener API, and will be changed to be an opaque + * type in the future. + */ +struct json_tokener +{ + /** + * @deprecated Do not access any of these fields outside of json_tokener.c + */ + char *str; + struct printbuf *pb; + int max_depth, depth, is_double, st_pos; + /** + * @deprecated See json_tokener_get_parse_end() instead. + */ + int char_offset; + /** + * @deprecated See json_tokener_get_error() instead. + */ + enum json_tokener_error err; + unsigned int ucs_char, high_surrogate; + char quote_char; + struct json_tokener_srec *stack; + int flags; +}; + +/** + * Return the offset of the byte after the last byte parsed + * relative to the start of the most recent string passed in + * to json_tokener_parse_ex(). i.e. this is where parsing + * would start again if the input contains another JSON object + * after the currently parsed one. + * + * Note that when multiple parse calls are issued, this is *not* the + * total number of characters parsed. + * + * In the past this would have been accessed as tok->char_offset. + * + * See json_tokener_parse_ex() for an example of how to use this. + */ +JSON_EXPORT size_t json_tokener_get_parse_end(struct json_tokener *tok); + +/** + * @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. + * + * Note that setting this will also effectively disable parsing + * of multiple json objects in a single character stream + * (e.g. {"foo":123}{"bar":234}); if you want to allow that + * also set JSON_TOKENER_ALLOW_TRAILING_CHARS + * + * This flag is not set by default. + * + * @see json_tokener_set_flags() + */ +#define JSON_TOKENER_STRICT 0x01 + +/** + * Use with JSON_TOKENER_STRICT to allow trailing characters after the + * first parsed object. + * + * @see json_tokener_set_flags() + */ +#define JSON_TOKENER_ALLOW_TRAILING_CHARS 0x02 + +/** + * Cause json_tokener_parse_ex() to validate that input is UTF8. + * If this flag is specified and validation fails, then + * json_tokener_get_error(tok) will return + * json_tokener_error_parse_utf8_string + * + * This flag is not set by default. + * + * @see json_tokener_set_flags() + */ +#define JSON_TOKENER_VALIDATE_UTF8 0x10 + +/** + * 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. + */ +JSON_EXPORT 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 json_tokener_error_desc(). + */ +JSON_EXPORT enum json_tokener_error json_tokener_get_error(struct json_tokener *tok); + +/** + * Allocate a new json_tokener. + * When done using that to parse objects, free it with json_tokener_free(). + * See json_tokener_parse_ex() for usage details. + */ +JSON_EXPORT struct json_tokener *json_tokener_new(void); + +/** + * Allocate a new json_tokener with a custom max nesting depth. + * @see JSON_TOKENER_DEFAULT_DEPTH + */ +JSON_EXPORT struct json_tokener *json_tokener_new_ex(int depth); + +/** + * Free a json_tokener previously allocated with json_tokener_new(). + */ +JSON_EXPORT void json_tokener_free(struct json_tokener *tok); + +/** + * Reset the state of a json_tokener, to prepare to parse a + * brand new JSON object. + */ +JSON_EXPORT void json_tokener_reset(struct json_tokener *tok); + +/** + * Parse a json_object out of the string `str`. + * + * If you need more control over how the parsing occurs, + * see json_tokener_parse_ex(). + */ +JSON_EXPORT struct json_object *json_tokener_parse(const char *str); + +/** + * Parser a json_object out of the string `str`, but if it fails + * return the error in `*error`. + * @see json_tokener_parse() + * @see json_tokener_parse_ex() + */ +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, with a reference count of one which belongs to the caller. 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. + * + * 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. + * + * If the caller knows that they are at the end of their input, the length + * passed MUST include the final '\0' character, so values with no inherent + * end (i.e. numbers) can be properly parsed, rather than just returning + * json_tokener_continue. + * + * Extra characters can be detected by comparing the value returned by + * json_tokener_get_parse_end() 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 a subsequent call to 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); + if (end_of_input) + stringlen++; // Include the '\0' if we know we're at the end of input + 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 (json_tokener_get_parse_end(tok) < stringlen) +{ + // 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 |