1 /* 2 SPDX-License-Identifier: MIT 3 4 Parson 1.5.3 (https://github.com/kgabis/parson) 5 Copyright (c) 2012 - 2023 Krzysztof Gabis 6 7 Permission is hereby granted, free of charge, to any person obtaining a copy 8 of this software and associated documentation files (the "Software"), to deal 9 in the Software without restriction, including without limitation the rights 10 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 11 copies of the Software, and to permit persons to whom the Software is 12 furnished to do so, subject to the following conditions: 13 14 The above copyright notice and this permission notice shall be included in 15 all copies or substantial portions of the Software. 16 17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 20 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 23 THE SOFTWARE. 24 */ 25 26 #ifndef parson_parson_h 27 #define parson_parson_h 28 29 #ifdef __cplusplus 30 extern "C" 31 { 32 #endif 33 #if 0 34 } /* unconfuse xcode */ 35 #endif 36 37 #define PARSON_VERSION_MAJOR 1 38 #define PARSON_VERSION_MINOR 5 39 #define PARSON_VERSION_PATCH 3 40 41 #define PARSON_VERSION_STRING "1.5.3" 42 43 #include <stddef.h> /* size_t */ 44 45 /* Types and enums */ 46 typedef struct json_object_t JSON_Object; 47 typedef struct json_array_t JSON_Array; 48 typedef struct json_value_t JSON_Value; 49 50 enum json_value_type { 51 JSONError = -1, 52 JSONNull = 1, 53 JSONString = 2, 54 JSONNumber = 3, 55 JSONObject = 4, 56 JSONArray = 5, 57 JSONBoolean = 6 58 }; 59 typedef int JSON_Value_Type; 60 61 enum json_result_t { 62 JSONSuccess = 0, 63 JSONFailure = -1 64 }; 65 typedef int JSON_Status; 66 67 typedef void * (*JSON_Malloc_Function)(size_t); 68 typedef void (*JSON_Free_Function)(void *); 69 70 /* A function used for serializing numbers (see json_set_number_serialization_function). 71 If 'buf' is null then it should return number of bytes that would've been written 72 (but not more than PARSON_NUM_BUF_SIZE). 73 */ 74 typedef int (*JSON_Number_Serialization_Function)(double num, char *buf); 75 76 /* Call only once, before calling any other function from parson API. If not called, malloc and free 77 from stdlib will be used for all allocations */ 78 void json_set_allocation_functions(JSON_Malloc_Function malloc_fun, JSON_Free_Function free_fun); 79 80 /* Sets if slashes should be escaped or not when serializing JSON. By default slashes are escaped. 81 This function sets a global setting and is not thread safe. */ 82 void json_set_escape_slashes(int escape_slashes); 83 84 /* Sets float format used for serialization of numbers. 85 Make sure it can't serialize to a string longer than PARSON_NUM_BUF_SIZE. 86 If format is null then the default format is used. */ 87 void json_set_float_serialization_format(const char *format); 88 89 /* Sets a function that will be used for serialization of numbers. 90 If function is null then the default serialization function is used. */ 91 void json_set_number_serialization_function(JSON_Number_Serialization_Function fun); 92 93 /* Parses first JSON value in a file, returns NULL in case of error */ 94 JSON_Value * json_parse_file(const char *filename); 95 96 /* Parses first JSON value in a file and ignores comments (/ * * / and //), 97 returns NULL in case of error */ 98 JSON_Value * json_parse_file_with_comments(const char *filename); 99 100 /* Parses first JSON value in a string, returns NULL in case of error */ 101 JSON_Value * json_parse_string(const char *string); 102 103 /* Parses first JSON value in a string and ignores comments (/ * * / and //), 104 returns NULL in case of error */ 105 JSON_Value * json_parse_string_with_comments(const char *string); 106 107 /* Serialization */ 108 size_t json_serialization_size(const JSON_Value *value); /* returns 0 on fail */ 109 JSON_Status json_serialize_to_buffer(const JSON_Value *value, char *buf, size_t buf_size_in_bytes); 110 JSON_Status json_serialize_to_file(const JSON_Value *value, const char *filename); 111 char * json_serialize_to_string(const JSON_Value *value); 112 113 /* Pretty serialization */ 114 size_t json_serialization_size_pretty(const JSON_Value *value); /* returns 0 on fail */ 115 JSON_Status json_serialize_to_buffer_pretty(const JSON_Value *value, char *buf, size_t buf_size_in_bytes); 116 JSON_Status json_serialize_to_file_pretty(const JSON_Value *value, const char *filename); 117 char * json_serialize_to_string_pretty(const JSON_Value *value); 118 119 void json_free_serialized_string(char *string); /* frees string from json_serialize_to_string and json_serialize_to_string_pretty */ 120 121 /* Comparing */ 122 int json_value_equals(const JSON_Value *a, const JSON_Value *b); 123 124 /* Validation 125 This is *NOT* JSON Schema. It validates json by checking if object have identically 126 named fields with matching types. 127 For example schema {"name":"", "age":0} will validate 128 {"name":"Joe", "age":25} and {"name":"Joe", "age":25, "gender":"m"}, 129 but not {"name":"Joe"} or {"name":"Joe", "age":"Cucumber"}. 130 In case of arrays, only first value in schema is checked against all values in tested array. 131 Empty objects ({}) validate all objects, empty arrays ([]) validate all arrays, 132 null validates values of every type. 133 */ 134 JSON_Status json_validate(const JSON_Value *schema, const JSON_Value *value); 135 136 /* 137 * JSON Object 138 */ 139 JSON_Value * json_object_get_value (const JSON_Object *object, const char *name); 140 const char * json_object_get_string (const JSON_Object *object, const char *name); 141 size_t json_object_get_string_len(const JSON_Object *object, const char *name); /* doesn't account for last null character */ 142 JSON_Object * json_object_get_object (const JSON_Object *object, const char *name); 143 JSON_Array * json_object_get_array (const JSON_Object *object, const char *name); 144 double json_object_get_number (const JSON_Object *object, const char *name); /* returns 0 on fail */ 145 int json_object_get_boolean(const JSON_Object *object, const char *name); /* returns -1 on fail */ 146 147 /* dotget functions enable addressing values with dot notation in nested objects, 148 just like in structs or c++/java/c# objects (e.g. objectA.objectB.value). 149 Because valid names in JSON can contain dots, some values may be inaccessible 150 this way. */ 151 JSON_Value * json_object_dotget_value (const JSON_Object *object, const char *name); 152 const char * json_object_dotget_string (const JSON_Object *object, const char *name); 153 size_t json_object_dotget_string_len(const JSON_Object *object, const char *name); /* doesn't account for last null character */ 154 JSON_Object * json_object_dotget_object (const JSON_Object *object, const char *name); 155 JSON_Array * json_object_dotget_array (const JSON_Object *object, const char *name); 156 double json_object_dotget_number (const JSON_Object *object, const char *name); /* returns 0 on fail */ 157 int json_object_dotget_boolean(const JSON_Object *object, const char *name); /* returns -1 on fail */ 158 159 /* Functions to get available names */ 160 size_t json_object_get_count (const JSON_Object *object); 161 const char * json_object_get_name (const JSON_Object *object, size_t index); 162 JSON_Value * json_object_get_value_at(const JSON_Object *object, size_t index); 163 JSON_Value * json_object_get_wrapping_value(const JSON_Object *object); 164 165 /* Functions to check if object has a value with a specific name. Returned value is 1 if object has 166 * a value and 0 if it doesn't. dothas functions behave exactly like dotget functions. */ 167 int json_object_has_value (const JSON_Object *object, const char *name); 168 int json_object_has_value_of_type(const JSON_Object *object, const char *name, JSON_Value_Type type); 169 170 int json_object_dothas_value (const JSON_Object *object, const char *name); 171 int json_object_dothas_value_of_type(const JSON_Object *object, const char *name, JSON_Value_Type type); 172 173 /* Creates new name-value pair or frees and replaces old value with a new one. 174 * json_object_set_value does not copy passed value so it shouldn't be freed afterwards. */ 175 JSON_Status json_object_set_value(JSON_Object *object, const char *name, JSON_Value *value); 176 JSON_Status json_object_set_string(JSON_Object *object, const char *name, const char *string); 177 JSON_Status json_object_set_string_with_len(JSON_Object *object, const char *name, const char *string, size_t len); /* length shouldn't include last null character */ 178 JSON_Status json_object_set_number(JSON_Object *object, const char *name, double number); 179 JSON_Status json_object_set_boolean(JSON_Object *object, const char *name, int boolean); 180 JSON_Status json_object_set_null(JSON_Object *object, const char *name); 181 182 /* Works like dotget functions, but creates whole hierarchy if necessary. 183 * json_object_dotset_value does not copy passed value so it shouldn't be freed afterwards. */ 184 JSON_Status json_object_dotset_value(JSON_Object *object, const char *name, JSON_Value *value); 185 JSON_Status json_object_dotset_string(JSON_Object *object, const char *name, const char *string); 186 JSON_Status json_object_dotset_string_with_len(JSON_Object *object, const char *name, const char *string, size_t len); /* length shouldn't include last null character */ 187 JSON_Status json_object_dotset_number(JSON_Object *object, const char *name, double number); 188 JSON_Status json_object_dotset_boolean(JSON_Object *object, const char *name, int boolean); 189 JSON_Status json_object_dotset_null(JSON_Object *object, const char *name); 190 191 /* Frees and removes name-value pair */ 192 JSON_Status json_object_remove(JSON_Object *object, const char *name); 193 194 /* Works like dotget function, but removes name-value pair only on exact match. */ 195 JSON_Status json_object_dotremove(JSON_Object *object, const char *key); 196 197 /* Removes all name-value pairs in object */ 198 JSON_Status json_object_clear(JSON_Object *object); 199 200 /* 201 *JSON Array 202 */ 203 JSON_Value * json_array_get_value (const JSON_Array *array, size_t index); 204 const char * json_array_get_string (const JSON_Array *array, size_t index); 205 size_t json_array_get_string_len(const JSON_Array *array, size_t index); /* doesn't account for last null character */ 206 JSON_Object * json_array_get_object (const JSON_Array *array, size_t index); 207 JSON_Array * json_array_get_array (const JSON_Array *array, size_t index); 208 double json_array_get_number (const JSON_Array *array, size_t index); /* returns 0 on fail */ 209 int json_array_get_boolean(const JSON_Array *array, size_t index); /* returns -1 on fail */ 210 size_t json_array_get_count (const JSON_Array *array); 211 JSON_Value * json_array_get_wrapping_value(const JSON_Array *array); 212 213 /* Frees and removes value at given index, does nothing and returns JSONFailure if index doesn't exist. 214 * Order of values in array may change during execution. */ 215 JSON_Status json_array_remove(JSON_Array *array, size_t i); 216 217 /* Frees and removes from array value at given index and replaces it with given one. 218 * Does nothing and returns JSONFailure if index doesn't exist. 219 * json_array_replace_value does not copy passed value so it shouldn't be freed afterwards. */ 220 JSON_Status json_array_replace_value(JSON_Array *array, size_t i, JSON_Value *value); 221 JSON_Status json_array_replace_string(JSON_Array *array, size_t i, const char* string); 222 JSON_Status json_array_replace_string_with_len(JSON_Array *array, size_t i, const char *string, size_t len); /* length shouldn't include last null character */ 223 JSON_Status json_array_replace_number(JSON_Array *array, size_t i, double number); 224 JSON_Status json_array_replace_boolean(JSON_Array *array, size_t i, int boolean); 225 JSON_Status json_array_replace_null(JSON_Array *array, size_t i); 226 227 /* Frees and removes all values from array */ 228 JSON_Status json_array_clear(JSON_Array *array); 229 230 /* Appends new value at the end of array. 231 * json_array_append_value does not copy passed value so it shouldn't be freed afterwards. */ 232 JSON_Status json_array_append_value(JSON_Array *array, JSON_Value *value); 233 JSON_Status json_array_append_string(JSON_Array *array, const char *string); 234 JSON_Status json_array_append_string_with_len(JSON_Array *array, const char *string, size_t len); /* length shouldn't include last null character */ 235 JSON_Status json_array_append_number(JSON_Array *array, double number); 236 JSON_Status json_array_append_boolean(JSON_Array *array, int boolean); 237 JSON_Status json_array_append_null(JSON_Array *array); 238 239 /* 240 *JSON Value 241 */ 242 JSON_Value * json_value_init_object (void); 243 JSON_Value * json_value_init_array (void); 244 JSON_Value * json_value_init_string (const char *string); /* copies passed string */ 245 JSON_Value * json_value_init_string_with_len(const char *string, size_t length); /* copies passed string, length shouldn't include last null character */ 246 JSON_Value * json_value_init_number (double number); 247 JSON_Value * json_value_init_boolean(int boolean); 248 JSON_Value * json_value_init_null (void); 249 JSON_Value * json_value_deep_copy (const JSON_Value *value); 250 void json_value_free (JSON_Value *value); 251 252 JSON_Value_Type json_value_get_type (const JSON_Value *value); 253 JSON_Object * json_value_get_object (const JSON_Value *value); 254 JSON_Array * json_value_get_array (const JSON_Value *value); 255 const char * json_value_get_string (const JSON_Value *value); 256 size_t json_value_get_string_len(const JSON_Value *value); /* doesn't account for last null character */ 257 double json_value_get_number (const JSON_Value *value); 258 int json_value_get_boolean(const JSON_Value *value); 259 JSON_Value * json_value_get_parent (const JSON_Value *value); 260 261 /* Same as above, but shorter */ 262 JSON_Value_Type json_type (const JSON_Value *value); 263 JSON_Object * json_object (const JSON_Value *value); 264 JSON_Array * json_array (const JSON_Value *value); 265 const char * json_string (const JSON_Value *value); 266 size_t json_string_len(const JSON_Value *value); /* doesn't account for last null character */ 267 double json_number (const JSON_Value *value); 268 int json_boolean(const JSON_Value *value); 269 270 #ifdef __cplusplus 271 } 272 #endif 273 274 #endif 275