deps/libretro-common/include/formats/rjson.h

   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