| 1 | /* Copyright (C) 2010-2020 The RetroArch team |
| 2 | * |
| 3 | * --------------------------------------------------------------------------------------- |
| 4 | * The following license statement only applies to this file (rjson.h). |
| 5 | * --------------------------------------------------------------------------------------- |
| 6 | * |
| 7 | * Permission is hereby granted, free of charge, |
| 8 | * to any person obtaining a copy of this software and associated documentation files (the "Software"), |
| 9 | * to deal in the Software without restriction, including without limitation the rights to |
| 10 | * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, |
| 11 | * and to permit persons to whom the Software is furnished to do so, subject to the following conditions: |
| 12 | * |
| 13 | * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. |
| 14 | * |
| 15 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, |
| 16 | * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 17 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. |
| 18 | * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, |
| 19 | * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
| 20 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| 21 | */ |
| 22 | |
| 23 | #ifndef __LIBRETRO_SDK_FORMAT_RJSON_H__ |
| 24 | #define __LIBRETRO_SDK_FORMAT_RJSON_H__ |
| 25 | |
| 26 | #include <retro_common_api.h> |
| 27 | #include <boolean.h> /* bool */ |
| 28 | #include <stddef.h> /* size_t */ |
| 29 | |
| 30 | RETRO_BEGIN_DECLS |
| 31 | |
| 32 | /* List of possible element types returned by rjson_next */ |
| 33 | enum rjson_type |
| 34 | { |
| 35 | RJSON_DONE, |
| 36 | RJSON_OBJECT, RJSON_ARRAY, RJSON_OBJECT_END, RJSON_ARRAY_END, |
| 37 | RJSON_STRING, RJSON_NUMBER, RJSON_TRUE, RJSON_FALSE, RJSON_NULL, |
| 38 | RJSON_ERROR |
| 39 | }; |
| 40 | |
| 41 | /* Options that can be passed to rjson_set_options */ |
| 42 | enum rjson_option |
| 43 | { |
| 44 | /* Allow UTF-8 byte order marks */ |
| 45 | RJSON_OPTION_ALLOW_UTF8BOM = (1<<0), |
| 46 | /* Allow JavaScript style comments in the stream */ |
| 47 | RJSON_OPTION_ALLOW_COMMENTS = (1<<1), |
| 48 | /* Allow unescaped control characters in strings (bytes 0x00 - 0x1F) */ |
| 49 | RJSON_OPTION_ALLOW_UNESCAPED_CONTROL_CHARACTERS = (1<<2), |
| 50 | /* Ignore invalid Unicode escapes and don't validate UTF-8 codes */ |
| 51 | RJSON_OPTION_IGNORE_INVALID_ENCODING = (1<<3), |
| 52 | /* Replace invalid Unicode escapes and UTF-8 codes with a '?' character */ |
| 53 | RJSON_OPTION_REPLACE_INVALID_ENCODING = (1<<4), |
| 54 | /* Ignore carriage return (\r escape sequence) in strings */ |
| 55 | RJSON_OPTION_IGNORE_STRING_CARRIAGE_RETURN = (1<<5), |
| 56 | /* Allow data after the end of the top JSON object/array/value */ |
| 57 | RJSON_OPTION_ALLOW_TRAILING_DATA = (1<<6) |
| 58 | }; |
| 59 | |
| 60 | /* Custom data input callback |
| 61 | * Should return > 0 and <= len on success, 0 on file end and < 0 on error. */ |
| 62 | typedef int (*rjson_io_t)(void* buf, int len, void *user_data); |
| 63 | typedef struct rjson rjson_t; |
| 64 | struct intfstream_internal; |
| 65 | struct RFILE; |
| 66 | |
| 67 | /* Create a new parser instance from various sources */ |
| 68 | rjson_t *rjson_open_stream(struct intfstream_internal *stream); |
| 69 | rjson_t *rjson_open_rfile(struct RFILE *rfile); |
| 70 | rjson_t *rjson_open_buffer(const void *buffer, size_t size); |
| 71 | rjson_t *rjson_open_string(const char *string, size_t len); |
| 72 | rjson_t *rjson_open_user(rjson_io_t io, void *user_data, int io_block_size); |
| 73 | |
| 74 | /* Free the parser instance created with rjson_open_* */ |
| 75 | void rjson_free(rjson_t *json); |
| 76 | |
| 77 | /* Set one or more enum rjson_option, will override previously set options. |
| 78 | * Use bitwise OR to concatenate multiple options. |
| 79 | * By default none of the options are set. */ |
| 80 | void rjson_set_options(rjson_t *json, char rjson_option_flags); |
| 81 | |
| 82 | /* Sets the maximum context depth, recursion inside arrays and objects. |
| 83 | * By default this is set to 50. */ |
| 84 | void rjson_set_max_depth(rjson_t *json, unsigned int max_depth); |
| 85 | |
| 86 | /* Parse to the next JSON element and return the type of it. |
| 87 | * Will return RJSON_DONE when successfully reaching the end or |
| 88 | * RJSON_ERROR when an error was encountered. */ |
| 89 | enum rjson_type rjson_next(rjson_t *json); |
| 90 | |
| 91 | /* Get the current string, null-terminated unescaped UTF-8 encoded. |
| 92 | * Can only be used when the current element is RJSON_STRING or RJSON_NUMBER. |
| 93 | * The returned pointer is only valid until the parsing continues. */ |
| 94 | const char *rjson_get_string(rjson_t *json, size_t *length); |
| 95 | |
| 96 | /* Returns the current number (or string) converted to double or int */ |
| 97 | double rjson_get_double(rjson_t *json); |
| 98 | int rjson_get_int(rjson_t *json); |
| 99 | |
| 100 | /* Returns a string describing the error once rjson_next/rjson_parse |
| 101 | * has returned an unrecoverable RJSON_ERROR (otherwise returns ""). */ |
| 102 | const char *rjson_get_error(rjson_t *json); |
| 103 | |
| 104 | /* Can be used to set a custom error description on an invalid JSON structure. |
| 105 | * Maximum length of 79 characters and once set the parsing can't continue. */ |
| 106 | void rjson_set_error(rjson_t *json, const char* error); |
| 107 | |
| 108 | /* Functions to get the current position in the source stream as well as */ |
| 109 | /* a bit of source json arround the current position for additional detail |
| 110 | * when parsing has failed with RJSON_ERROR. |
| 111 | * Intended to be used with printf style formatting like: |
| 112 | * printf("Invalid JSON at line %d, column %d - %s - Source: ...%.*s...\n", |
| 113 | * (int)rjson_get_source_line(json), (int)rjson_get_source_column(json), |
| 114 | * rjson_get_error(json), rjson_get_source_context_len(json), |
| 115 | * rjson_get_source_context_buf(json)); */ |
| 116 | size_t rjson_get_source_line(rjson_t *json); |
| 117 | size_t rjson_get_source_column(rjson_t *json); |
| 118 | int rjson_get_source_context_len(rjson_t *json); |
| 119 | const char* rjson_get_source_context_buf(rjson_t *json); |
| 120 | |
| 121 | /* Confirm the parsing context stack, for example calling |
| 122 | rjson_check_context(json, 2, RJSON_OBJECT, RJSON_ARRAY) |
| 123 | returns true when inside "{ [ ..." but not for "[ .." or "{ [ { ..." */ |
| 124 | bool rjson_check_context(rjson_t *json, unsigned int depth, ...); |
| 125 | |
| 126 | /* Returns the current level of nested objects/arrays */ |
| 127 | unsigned int rjson_get_context_depth(rjson_t *json); |
| 128 | |
| 129 | /* Return the current parsing context, that is, RJSON_OBJECT if we are inside |
| 130 | * an object, RJSON_ARRAY if we are inside an array, and RJSON_DONE or |
| 131 | * RJSON_ERROR if we are not yet/anymore in either. */ |
| 132 | enum rjson_type rjson_get_context_type(rjson_t *json); |
| 133 | |
| 134 | /* While inside an object or an array, this return the number of parsing |
| 135 | * events that have already been observed at this level with rjson_next. |
| 136 | * In particular, inside an object, an odd number would indicate that the just |
| 137 | * observed RJSON_STRING event is a member name. */ |
| 138 | size_t rjson_get_context_count(rjson_t *json); |
| 139 | |
| 140 | /* Parse an entire JSON stream with a list of element specific handlers. |
| 141 | * Each of the handlers can be passed a function or NULL to ignore it. |
| 142 | * If a handler returns false, the parsing will abort and the returned |
| 143 | * rjson_type will indicate on which element type parsing was aborted. |
| 144 | * Otherwise the return value will be RJSON_DONE or RJSON_ERROR. */ |
| 145 | enum rjson_type rjson_parse(rjson_t *json, void* context, |
| 146 | bool (*object_member_handler)(void *context, const char *str, size_t len), |
| 147 | bool (*string_handler )(void *context, const char *str, size_t len), |
| 148 | bool (*number_handler )(void *context, const char *str, size_t len), |
| 149 | bool (*start_object_handler )(void *context), |
| 150 | bool (*end_object_handler )(void *context), |
| 151 | bool (*start_array_handler )(void *context), |
| 152 | bool (*end_array_handler )(void *context), |
| 153 | bool (*boolean_handler )(void *context, bool value), |
| 154 | bool (*null_handler )(void *context)); |
| 155 | |
| 156 | /* A simpler interface to parse a JSON in memory. This will avoid any memory |
| 157 | * allocations unless the document contains strings longer than 512 characters. |
| 158 | * In the error handler, error will be "" if any of the other handlers aborted. */ |
| 159 | bool rjson_parse_quick(const char *string, size_t len, void* context, char option_flags, |
| 160 | bool (*object_member_handler)(void *context, const char *str, size_t len), |
| 161 | bool (*string_handler )(void *context, const char *str, size_t len), |
| 162 | bool (*number_handler )(void *context, const char *str, size_t len), |
| 163 | bool (*start_object_handler )(void *context), |
| 164 | bool (*end_object_handler )(void *context), |
| 165 | bool (*start_array_handler )(void *context), |
| 166 | bool (*end_array_handler )(void *context), |
| 167 | bool (*boolean_handler )(void *context, bool value), |
| 168 | bool (*null_handler )(void *context), |
| 169 | void (*error_handler )(void *context, int line, int col, const char* error)); |
| 170 | |
| 171 | /* ------------------------------------------------------------------------- */ |
| 172 | |
| 173 | /* Options that can be passed to rjsonwriter_set_options */ |
| 174 | enum rjsonwriter_option |
| 175 | { |
| 176 | /* Don't write spaces, tabs or newlines to the output (except in strings) */ |
| 177 | RJSONWRITER_OPTION_SKIP_WHITESPACE = (1<<0) |
| 178 | }; |
| 179 | |
| 180 | /* Custom data output callback |
| 181 | * Should return len on success and < len on a write error. */ |
| 182 | typedef int (*rjsonwriter_io_t)(const void* buf, int len, void *user_data); |
| 183 | typedef struct rjsonwriter rjsonwriter_t; |
| 184 | |
| 185 | /* Create a new writer instance to various targets */ |
| 186 | rjsonwriter_t *rjsonwriter_open_stream(struct intfstream_internal *stream); |
| 187 | rjsonwriter_t *rjsonwriter_open_rfile(struct RFILE *rfile); |
| 188 | rjsonwriter_t *rjsonwriter_open_memory(void); |
| 189 | rjsonwriter_t *rjsonwriter_open_user(rjsonwriter_io_t io, void *user_data); |
| 190 | |
| 191 | /* When opened with rjsonwriter_open_memory, will return the generated JSON. |
| 192 | * Result is always null-terminated. Passed len can be NULL if not needed, |
| 193 | * otherwise returned len will be string length without null-terminator. |
| 194 | * Returns NULL if writing ran out of memory or not opened from memory. |
| 195 | * Returned buffer is only valid until writer is modified or freed. */ |
| 196 | char* rjsonwriter_get_memory_buffer(rjsonwriter_t *writer, int* len); |
| 197 | |
| 198 | /* When opened with rjsonwriter_open_memory, will return current length */ |
| 199 | int rjsonwriter_count_memory_buffer(rjsonwriter_t *writer); |
| 200 | |
| 201 | /* When opened with rjsonwriter_open_memory, will clear the buffer. |
| 202 | The buffer will be partially erased if keep_len is > 0. |
| 203 | No memory is freed or re-allocated with this function. */ |
| 204 | void rjsonwriter_erase_memory_buffer(rjsonwriter_t *writer, int keep_len); |
| 205 | |
| 206 | /* Free rjsonwriter handle and return result of final rjsonwriter_flush call */ |
| 207 | bool rjsonwriter_free(rjsonwriter_t *writer); |
| 208 | |
| 209 | /* Set one or more enum rjsonwriter_option, will override previously set options. |
| 210 | * Use bitwise OR to concatenate multiple options. |
| 211 | * By default none of the options are set. */ |
| 212 | void rjsonwriter_set_options(rjsonwriter_t *writer, int rjsonwriter_option_flags); |
| 213 | |
| 214 | /* Flush any buffered output data to the output stream. |
| 215 | * Returns true if the data was successfully written. Once writing fails once, |
| 216 | * no more data will be written and flush will always returns false */ |
| 217 | bool rjsonwriter_flush(rjsonwriter_t *writer); |
| 218 | |
| 219 | /* Returns a string describing an error or "" if there was none. |
| 220 | * The only error possible is "output error" after the io function failed. |
| 221 | * If rjsonwriter_rawf were used manually, "out of memory" is also possible. */ |
| 222 | const char *rjsonwriter_get_error(rjsonwriter_t *writer); |
| 223 | |
| 224 | /* Used by the inline functions below to append raw data */ |
| 225 | void rjsonwriter_raw(rjsonwriter_t *writer, const char *buf, int len); |
| 226 | void rjsonwriter_rawf(rjsonwriter_t *writer, const char *fmt, ...); |
| 227 | |
| 228 | /* Add a UTF-8 encoded string |
| 229 | * Special and control characters are automatically escaped. |
| 230 | * If NULL is passed an empty string will be written (not JSON null). */ |
| 231 | void rjsonwriter_add_string(rjsonwriter_t *writer, const char *value); |
| 232 | void rjsonwriter_add_string_len(rjsonwriter_t *writer, const char *value, int len); |
| 233 | |
| 234 | void rjsonwriter_add_double(rjsonwriter_t *writer, double value); |
| 235 | |
| 236 | void rjsonwriter_add_spaces(rjsonwriter_t *writer, int count); |
| 237 | |
| 238 | void rjsonwriter_add_tabs(rjsonwriter_t *writer, int count); |
| 239 | |
| 240 | RETRO_END_DECLS |
| 241 | |
| 242 | #endif |