source/include/exparson.h

0001 /*
0002  Exparson
0003  based on parson ( http://kgabis.github.com/parson/ )
0004  Copyright (c) 2012 - 2017 Krzysztof Gabis
0005
0006  Permission is hereby granted, free of charge, to any person obtaining a copy
0007  of this software and associated documentation files (the "Software"), to deal
0008  in the Software without restriction, including without limitation the rights
0009  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
0010  copies of the Software, and to permit persons to whom the Software is
0011  furnished to do so, subject to the following conditions:
0012
0013  The above copyright notice and this permission notice shall be included in
0014  all copies or substantial portions of the Software.
0015
0016  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
0017  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
0018  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
0019  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
0020  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
0021  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
0022  THE SOFTWARE.
0023 */
0024
0025 #ifndef exparson_exparson_h
0026 #define exparson_exparson_h
0027
0028 #ifdef __cplusplus
0029 extern "C"
0030 {
0031 #endif
0032
0033 #include <stddef.h>   /* size_t */
0034
0035 /* Types and enums */
0036 typedef struct exjson_object_t EXJSON_Object;
0037 typedef struct exjson_array_t  EXJSON_Array;
0038 typedef struct exjson_value_t  EXJSON_Value;
0039
0040 enum exjson_value_type {
0041     EXJSONError   = -1,
0042     EXJSONNull    = 1,
0043     EXJSONString  = 2,
0044     EXJSONNumber  = 3,
0045     EXJSONObject  = 4,
0046     EXJSONArray   = 5,
0047     EXJSONBoolean = 6,
0048     EXJSONIntnumber = 7
0049 };
0050 typedef int EXJSON_Value_Type;
0051
0052 enum exjson_result_t {
0053     EXJSONSuccess = 0,
0054     EXJSONFailure = -1
0055 };
0056 typedef int EXJSON_Status;
0057
0058 typedef void * (*EXJSON_Malloc_Function)(size_t);
0059 typedef void   (*EXJSON_Free_Function)(void *);
0060
0061 /* Call only once, before calling any other function from exparson API. If not called, malloc and free
0062    from stdlib will be used for all allocations */
0063 void exjson_set_allocation_functions(EXJSON_Malloc_Function malloc_fun, EXJSON_Free_Function free_fun);
0064
0065 /* Parses first EXJSON value in a file, returns NULL in case of error */
0066 EXJSON_Value * exjson_parse_file(const char *filename);
0067
0068 /* Parses first EXJSON value in a file and ignores comments (/ * * / and //),
0069    returns NULL in case of error */
0070 EXJSON_Value * exjson_parse_file_with_comments(const char *filename);
0071
0072 /*  Parses first EXJSON value in a string, returns NULL in case of error */
0073 EXJSON_Value * exjson_parse_string(const char *string);
0074
0075 /*  Parses first EXJSON value in a string and ignores comments (/ * * / and //),
0076     returns NULL in case of error */
0077 EXJSON_Value * exjson_parse_string_with_comments(const char *string);
0078
0079 /* Serialization */
0080 size_t      exjson_serialization_size(const EXJSON_Value *value); /* returns 0 on fail */
0081 EXJSON_Status exjson_serialize_to_buffer(const EXJSON_Value *value, char *buf, size_t buf_size_in_bytes);
0082 EXJSON_Status exjson_serialize_to_file(const EXJSON_Value *value, const char *filename);
0083 char *      exjson_serialize_to_string(const EXJSON_Value *value);
0084
0085 /* Pretty serialization */
0086 size_t      exjson_serialization_size_pretty(const EXJSON_Value *value); /* returns 0 on fail */
0087 EXJSON_Status exjson_serialize_to_buffer_pretty(const EXJSON_Value *value, char *buf, size_t buf_size_in_bytes);
0088 EXJSON_Status exjson_serialize_to_file_pretty(const EXJSON_Value *value, const char *filename);
0089 char *      exjson_serialize_to_string_pretty(const EXJSON_Value *value);
0090
0091 void        exjson_free_serialized_string(char *string); /* frees string from exjson_serialize_to_string and exjson_serialize_to_string_pretty */
0092
0093 /* Comparing */
0094 int  exjson_value_equals(const EXJSON_Value *a, const EXJSON_Value *b);
0095
0096 /* Validation
0097    This is *NOT* EXJSON Schema. It validates exjson by checking if object have identically
0098    named fields with matching types.
0099    For example schema {"name":"", "age":0} will validate
0100    {"name":"Joe", "age":25} and {"name":"Joe", "age":25, "gender":"m"},
0101    but not {"name":"Joe"} or {"name":"Joe", "age":"Cucumber"}.
0102    In case of arrays, only first value in schema is checked against all values in tested array.
0103    Empty objects ({}) validate all objects, empty arrays ([]) validate all arrays,
0104    null validates values of every type.
0105  */
0106 EXJSON_Status exjson_validate(const EXJSON_Value *schema, const EXJSON_Value *value);
0107
0108 /*
0109  * EXJSON Object
0110  */
0111 EXJSON_Value  * exjson_object_get_value  (const EXJSON_Object *object, const char *name);
0112 const char  * exjson_object_get_string (const EXJSON_Object *object, const char *name);
0113 EXJSON_Object * exjson_object_get_object (const EXJSON_Object *object, const char *name);
0114 EXJSON_Array  * exjson_object_get_array  (const EXJSON_Object *object, const char *name);
0115 double        exjson_object_get_number (const EXJSON_Object *object, const char *name); /* returns 0 on fail */
0116 long        exjson_object_get_intnumber (const EXJSON_Object *object, const char *name); /* returns 0 on fail */
0117 int           exjson_object_get_boolean(const EXJSON_Object *object, const char *name); /* returns -1 on fail */
0118
0119 /* dotget functions enable addressing values with dot notation in nested objects,
0120  just like in structs or c++/java/c# objects (e.g. objectA.objectB.value).
0121  Because valid names in EXJSON can contain dots, some values may be inaccessible
0122  this way. */
0123 EXJSON_Value  * exjson_object_dotget_value  (const EXJSON_Object *object, const char *name);
0124 const char  * exjson_object_dotget_string (const EXJSON_Object *object, const char *name);
0125 EXJSON_Object * exjson_object_dotget_object (const EXJSON_Object *object, const char *name);
0126 EXJSON_Array  * exjson_object_dotget_array  (const EXJSON_Object *object, const char *name);
0127 double        exjson_object_dotget_number (const EXJSON_Object *object, const char *name); /* returns 0 on fail */
0128 long        exjson_object_dotget_intnumber (const EXJSON_Object *object, const char *name); /* returns 0 on fail */
0129 int           exjson_object_dotget_boolean(const EXJSON_Object *object, const char *name); /* returns -1 on fail */
0130
0131 /* Functions to get available names */
0132 size_t        exjson_object_get_count   (const EXJSON_Object *object);
0133 const char  * exjson_object_get_name    (const EXJSON_Object *object, size_t index);
0134 EXJSON_Value  * exjson_object_get_value_at(const EXJSON_Object *object, size_t index);
0135 EXJSON_Value  * exjson_object_get_wrapping_value(const EXJSON_Object *object);
0136
0137 /* Functions to check if object has a value with a specific name. Returned value is 1 if object has
0138  * a value and 0 if it doesn't. dothas functions behave exactly like dotget functions. */
0139 int exjson_object_has_value        (const EXJSON_Object *object, const char *name);
0140 int exjson_object_has_value_of_type(const EXJSON_Object *object, const char *name, EXJSON_Value_Type type);
0141
0142 int exjson_object_dothas_value        (const EXJSON_Object *object, const char *name);
0143 int exjson_object_dothas_value_of_type(const EXJSON_Object *object, const char *name, EXJSON_Value_Type type);
0144
0145 /* Creates new name-value pair or frees and replaces old value with a new one.
0146  * exjson_object_set_value does not copy passed value so it shouldn't be freed afterwards. */
0147 EXJSON_Status exjson_object_set_value(EXJSON_Object *object, const char *name, EXJSON_Value *value);
0148 EXJSON_Status exjson_object_set_string(EXJSON_Object *object, const char *name, const char *string);
0149 EXJSON_Status exjson_object_set_number(EXJSON_Object *object, const char *name, double number);
0150 EXJSON_Status exjson_object_set_intnumber(EXJSON_Object *object, const char *name, long number);
0151 EXJSON_Status exjson_object_set_boolean(EXJSON_Object *object, const char *name, int boolean);
0152 EXJSON_Status exjson_object_set_null(EXJSON_Object *object, const char *name);
0153
0154 /* Works like dotget functions, but creates whole hierarchy if necessary.
0155  * exjson_object_dotset_value does not copy passed value so it shouldn't be freed afterwards. */
0156 EXJSON_Status exjson_object_dotset_value(EXJSON_Object *object, const char *name, EXJSON_Value *value);
0157 EXJSON_Status exjson_object_dotset_string(EXJSON_Object *object, const char *name, const char *string);
0158 EXJSON_Status exjson_object_dotset_number(EXJSON_Object *object, const char *name, double number);
0159 EXJSON_Status exjson_object_dotset_intnumber(EXJSON_Object *object, const char *name, long number);
0160 EXJSON_Status exjson_object_dotset_boolean(EXJSON_Object *object, const char *name, int boolean);
0161 EXJSON_Status exjson_object_dotset_null(EXJSON_Object *object, const char *name);
0162
0163 /* Frees and removes name-value pair */
0164 EXJSON_Status exjson_object_remove(EXJSON_Object *object, const char *name);
0165
0166 /* Works like dotget function, but removes name-value pair only on exact match. */
0167 EXJSON_Status exjson_object_dotremove(EXJSON_Object *object, const char *key);
0168
0169 /* Removes all name-value pairs in object */
0170 EXJSON_Status exjson_object_clear(EXJSON_Object *object);
0171
0172 /*
0173  *EXJSON Array
0174  */
0175 EXJSON_Value  * exjson_array_get_value  (const EXJSON_Array *array, size_t index);
0176 const char  * exjson_array_get_string (const EXJSON_Array *array, size_t index);
0177 EXJSON_Object * exjson_array_get_object (const EXJSON_Array *array, size_t index);
0178 EXJSON_Array  * exjson_array_get_array  (const EXJSON_Array *array, size_t index);
0179 double        exjson_array_get_number (const EXJSON_Array *array, size_t index); /* returns 0 on fail */
0180
0181 long        exjson_array_get_intnumber (const EXJSON_Array *array, size_t index); /* returns 0 on fail */
0182
0183 int           exjson_array_get_boolean(const EXJSON_Array *array, size_t index); /* returns -1 on fail */
0184 size_t        exjson_array_get_count  (const EXJSON_Array *array);
0185 EXJSON_Value  * exjson_array_get_wrapping_value(const EXJSON_Array *array);
0186
0187 /* Frees and removes value at given index, does nothing and returns EXJSONFailure if index doesn't exist.
0188  * Order of values in array may change during execution.  */
0189 EXJSON_Status exjson_array_remove(EXJSON_Array *array, size_t i);
0190
0191 /* Frees and removes from array value at given index and replaces it with given one.
0192  * Does nothing and returns EXJSONFailure if index doesn't exist.
0193  * exjson_array_replace_value does not copy passed value so it shouldn't be freed afterwards. */
0194 EXJSON_Status exjson_array_replace_value(EXJSON_Array *array, size_t i, EXJSON_Value *value);
0195 EXJSON_Status exjson_array_replace_string(EXJSON_Array *array, size_t i, const char* string);
0196 EXJSON_Status exjson_array_replace_number(EXJSON_Array *array, size_t i, double number);
0197 EXJSON_Status exjson_array_replace_intnumber(EXJSON_Array *array, size_t i, long number);
0198 EXJSON_Status exjson_array_replace_boolean(EXJSON_Array *array, size_t i, int boolean);
0199 EXJSON_Status exjson_array_replace_null(EXJSON_Array *array, size_t i);
0200
0201 /* Frees and removes all values from array */
0202 EXJSON_Status exjson_array_clear(EXJSON_Array *array);
0203
0204 /* Appends new value at the end of array.
0205  * exjson_array_append_value does not copy passed value so it shouldn't be freed afterwards. */
0206 EXJSON_Status exjson_array_append_value(EXJSON_Array *array, EXJSON_Value *value);
0207 EXJSON_Status exjson_array_append_string(EXJSON_Array *array, const char *string);
0208 EXJSON_Status exjson_array_append_number(EXJSON_Array *array, double number);
0209 EXJSON_Status exjson_array_append_intnumber(EXJSON_Array *array, long number);
0210 EXJSON_Status exjson_array_append_boolean(EXJSON_Array *array, int boolean);
0211 EXJSON_Status exjson_array_append_null(EXJSON_Array *array);
0212
0213 /*
0214  *EXJSON Value
0215  */
0216 EXJSON_Value * exjson_value_init_object (void);
0217 EXJSON_Value * exjson_value_init_array  (void);
0218 EXJSON_Value * exjson_value_init_string (const char *string); /* copies passed string */
0219 EXJSON_Value * exjson_value_init_number (double number);
0220 EXJSON_Value * exjson_value_init_intnumber (long number);
0221 EXJSON_Value * exjson_value_init_boolean(int boolean);
0222 EXJSON_Value * exjson_value_init_null   (void);
0223 EXJSON_Value * exjson_value_deep_copy   (const EXJSON_Value *value);
0224 void         exjson_value_free        (EXJSON_Value *value);
0225
0226 EXJSON_Value_Type exjson_value_get_type   (const EXJSON_Value *value);
0227 EXJSON_Object *   exjson_value_get_object (const EXJSON_Value *value);
0228 EXJSON_Array  *   exjson_value_get_array  (const EXJSON_Value *value);
0229 const char  *   exjson_value_get_string (const EXJSON_Value *value);
0230 double          exjson_value_get_number (const EXJSON_Value *value);
0231 long          exjson_value_get_intnumber (const EXJSON_Value *value);
0232 int             exjson_value_get_boolean(const EXJSON_Value *value);
0233 EXJSON_Value  *   exjson_value_get_parent (const EXJSON_Value *value);
0234
0235 /* Same as above, but shorter */
0236 EXJSON_Value_Type exjson_type   (const EXJSON_Value *value);
0237 EXJSON_Object *   exjson_object (const EXJSON_Value *value);
0238 EXJSON_Array  *   exjson_array  (const EXJSON_Value *value);
0239 const char  *   exjson_string (const EXJSON_Value *value);
0240 double          exjson_number (const EXJSON_Value *value);
0241 long          exjson_intnumber (const EXJSON_Value *value);
0242 int             exjson_boolean(const EXJSON_Value *value);
0243
0244 #ifdef __cplusplus
0245 }
0246 #endif
0247
0248 #endif