GRASS GIS 8 Programmer's Manual  8.5.0dev(2024)-1d42e580e2
parson.h
Go to the documentation of this file.
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 #endif
32 #if 0
33 } /* unconfuse xcode */
34 #endif
35 
36 #define PARSON_VERSION_MAJOR 1
37 #define PARSON_VERSION_MINOR 5
38 #define PARSON_VERSION_PATCH 3
39 
40 #define PARSON_VERSION_STRING "1.5.3"
41 
42 #include <stddef.h> /* size_t */
43 
44 /* Types and enums */
45 typedef struct json_object_t JSON_Object;
46 typedef struct json_array_t JSON_Array;
47 typedef struct json_value_t JSON_Value;
48 
50  JSONError = -1,
51  JSONNull = 1,
55  JSONArray = 5,
56  JSONBoolean = 6
57 };
58 typedef int JSON_Value_Type;
59 
61 typedef int JSON_Status;
62 
63 typedef void *(*JSON_Malloc_Function)(size_t);
64 typedef void (*JSON_Free_Function)(void *);
65 
66 /* A function used for serializing numbers (see
67  json_set_number_serialization_function). If 'buf' is null then it should
68  return number of bytes that would've been written (but not more than
69  PARSON_NUM_BUF_SIZE).
70 */
71 typedef int (*JSON_Number_Serialization_Function)(double num, char *buf);
72 
73 /* Call only once, before calling any other function from parson API. If not
74  called, malloc and free from stdlib will be used for all allocations */
76  JSON_Free_Function free_fun);
77 
78 /* Sets if slashes should be escaped or not when serializing JSON. By default
79  slashes are escaped. This function sets a global setting and is not thread
80  safe. */
81 void json_set_escape_slashes(int escape_slashes);
82 
83 /* Sets float format used for serialization of numbers.
84  Make sure it can't serialize to a string longer than PARSON_NUM_BUF_SIZE.
85  If format is null then the default format is used. */
86 void json_set_float_serialization_format(const char *format);
87 
88 /* Sets a function that will be used for serialization of numbers.
89  If function is null then the default serialization function is used. */
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,
110  size_t buf_size_in_bytes);
112  const char *filename);
113 char *json_serialize_to_string(const JSON_Value *value);
114 
115 /* Pretty serialization */
116 size_t
117 json_serialization_size_pretty(const JSON_Value *value); /* returns 0 on fail */
119  size_t buf_size_in_bytes);
121  const char *filename);
122 char *json_serialize_to_string_pretty(const JSON_Value *value);
123 
125  char *string); /* frees string from json_serialize_to_string and
126  json_serialize_to_string_pretty */
127 
128 /* Comparing */
129 int json_value_equals(const JSON_Value *a, const JSON_Value *b);
130 
131 /* Validation
132  This is *NOT* JSON Schema. It validates json by checking if object have
133  identically named fields with matching types. For example schema {"name":"",
134  "age":0} will validate
135  {"name":"Joe", "age":25} and {"name":"Joe", "age":25, "gender":"m"},
136  but not {"name":"Joe"} or {"name":"Joe", "age":"Cucumber"}.
137  In case of arrays, only first value in schema is checked against all values
138  in tested array. Empty objects ({}) validate all objects, empty arrays ([])
139  validate all arrays, null validates values of every type.
140  */
141 JSON_Status json_validate(const JSON_Value *schema, const JSON_Value *value);
142 
143 /*
144  * JSON Object
145  */
146 JSON_Value *json_object_get_value(const JSON_Object *object, const char *name);
147 const char *json_object_get_string(const JSON_Object *object, const char *name);
149  const JSON_Object *object,
150  const char *name); /* doesn't account for last null character */
152  const char *name);
153 JSON_Array *json_object_get_array(const JSON_Object *object, const char *name);
154 double json_object_get_number(const JSON_Object *object,
155  const char *name); /* returns 0 on fail */
156 int json_object_get_boolean(const JSON_Object *object,
157  const char *name); /* returns -1 on fail */
158 
159 /* dotget functions enable addressing values with dot notation in nested
160  objects, just like in structs or c++/java/c# objects (e.g.
161  objectA.objectB.value). Because valid names in JSON can contain dots, some
162  values may be inaccessible this way. */
164  const char *name);
165 const char *json_object_dotget_string(const JSON_Object *object,
166  const char *name);
168  const JSON_Object *object,
169  const char *name); /* doesn't account for last null character */
171  const char *name);
173  const char *name);
174 double json_object_dotget_number(const JSON_Object *object,
175  const char *name); /* returns 0 on fail */
176 int json_object_dotget_boolean(const JSON_Object *object,
177  const char *name); /* returns -1 on fail */
178 
179 /* Functions to get available names */
180 size_t json_object_get_count(const JSON_Object *object);
181 const char *json_object_get_name(const JSON_Object *object, size_t index);
182 JSON_Value *json_object_get_value_at(const JSON_Object *object, size_t index);
184 
185 /* Functions to check if object has a value with a specific name. Returned value
186  * is 1 if object has a value and 0 if it doesn't. dothas functions behave
187  * exactly like dotget functions. */
188 int json_object_has_value(const JSON_Object *object, const char *name);
189 int json_object_has_value_of_type(const JSON_Object *object, const char *name,
190  JSON_Value_Type type);
191 
192 int json_object_dothas_value(const JSON_Object *object, const char *name);
194  const char *name, JSON_Value_Type type);
195 
196 /* Creates new name-value pair or frees and replaces old value with a new one.
197  * json_object_set_value does not copy passed value so it shouldn't be freed
198  * afterwards. */
200  JSON_Value *value);
202  const char *string);
204  JSON_Object *object, const char *name, const char *string,
205  size_t len); /* length shouldn't include last null character */
207  double number);
209  int boolean);
210 JSON_Status json_object_set_null(JSON_Object *object, const char *name);
211 
212 /* Works like dotget functions, but creates whole hierarchy if necessary.
213  * json_object_dotset_value does not copy passed value so it shouldn't be freed
214  * afterwards. */
216  JSON_Value *value);
218  const char *string);
220  JSON_Object *object, const char *name, const char *string,
221  size_t len); /* length shouldn't include last null character */
223  double number);
225  int boolean);
227 
228 /* Frees and removes name-value pair */
229 JSON_Status json_object_remove(JSON_Object *object, const char *name);
230 
231 /* Works like dotget function, but removes name-value pair only on exact match.
232  */
233 JSON_Status json_object_dotremove(JSON_Object *object, const char *key);
234 
235 /* Removes all name-value pairs in object */
237 
238 /*
239  *JSON Array
240  */
241 JSON_Value *json_array_get_value(const JSON_Array *array, size_t index);
242 const char *json_array_get_string(const JSON_Array *array, size_t index);
244  const JSON_Array *array,
245  size_t index); /* doesn't account for last null character */
246 JSON_Object *json_array_get_object(const JSON_Array *array, size_t index);
247 JSON_Array *json_array_get_array(const JSON_Array *array, size_t index);
248 double json_array_get_number(const JSON_Array *array,
249  size_t index); /* returns 0 on fail */
250 int json_array_get_boolean(const JSON_Array *array,
251  size_t index); /* returns -1 on fail */
252 size_t json_array_get_count(const JSON_Array *array);
254 
255 /* Frees and removes value at given index, does nothing and returns JSONFailure
256  * if index doesn't exist. Order of values in array may change during execution.
257  */
258 JSON_Status json_array_remove(JSON_Array *array, size_t i);
259 
260 /* Frees and removes from array value at given index and replaces it with given
261  * one. Does nothing and returns JSONFailure if index doesn't exist.
262  * json_array_replace_value does not copy passed value so it shouldn't be freed
263  * afterwards. */
265  JSON_Value *value);
267  const char *string);
269  JSON_Array *array, size_t i, const char *string,
270  size_t len); /* length shouldn't include last null character */
272  double number);
274  int boolean);
276 
277 /* Frees and removes all values from array */
279 
280 /* Appends new value at the end of array.
281  * json_array_append_value does not copy passed value so it shouldn't be freed
282  * afterwards. */
284 JSON_Status json_array_append_string(JSON_Array *array, const char *string);
286  JSON_Array *array, const char *string,
287  size_t len); /* length shouldn't include last null character */
288 JSON_Status json_array_append_number(JSON_Array *array, double number);
291 
292 /*
293  *JSON Value
294  */
297 JSON_Value *
298 json_value_init_string(const char *string); /* copies passed string */
300  const char *string,
301  size_t length); /* copies passed string, length shouldn't include last null
302  character */
303 JSON_Value *json_value_init_number(double number);
304 JSON_Value *json_value_init_boolean(int boolean);
307 void json_value_free(JSON_Value *value);
308 
312 const char *json_value_get_string(const JSON_Value *value);
314  const JSON_Value *value); /* doesn't account for last null character */
315 double json_value_get_number(const JSON_Value *value);
316 int json_value_get_boolean(const JSON_Value *value);
318 
319 /* Same as above, but shorter */
320 JSON_Value_Type json_type(const JSON_Value *value);
321 JSON_Object *json_object(const JSON_Value *value);
322 JSON_Array *json_array(const JSON_Value *value);
323 const char *json_string(const JSON_Value *value);
324 size_t json_string_len(
325  const JSON_Value *value); /* doesn't account for last null character */
326 double json_number(const JSON_Value *value);
327 int json_boolean(const JSON_Value *value);
328 
329 #ifdef __cplusplus
330 }
331 #endif
332 
333 #endif
const char * name
Definition: named_colr.c:6
JSON_Status json_object_dotset_string(JSON_Object *object, const char *name, const char *string)
Definition: parson.c:2555
size_t json_object_get_string_len(const JSON_Object *object, const char *name)
Definition: parson.c:1636
JSON_Value * json_parse_file_with_comments(const char *filename)
Definition: parson.c:1582
JSON_Status json_array_replace_null(JSON_Array *array, size_t i)
Definition: parson.c:2300
JSON_Object * json_object_dotget_object(const JSON_Object *object, const char *name)
Definition: parson.c:1690
int json_object_get_boolean(const JSON_Object *object, const char *name)
Definition: parson.c:1656
size_t json_value_get_string_len(const JSON_Value *value)
Definition: parson.c:1841
size_t json_string_len(const JSON_Value *value)
Definition: parson.c:2810
JSON_Value * json_value_init_array(void)
Definition: parson.c:1897
JSON_Value * json_array_get_value(const JSON_Array *array, size_t index)
Definition: parson.c:1761
JSON_Status json_object_dotset_boolean(JSON_Object *object, const char *name, int boolean)
Definition: parson.c:2598
JSON_Status json_array_append_null(JSON_Array *array)
Definition: parson.c:2387
JSON_Status json_array_replace_boolean(JSON_Array *array, size_t i, int boolean)
Definition: parson.c:2287
JSON_Value * json_value_deep_copy(const JSON_Value *value)
Definition: parson.c:1981
JSON_Status json_object_remove(JSON_Object *object, const char *name)
Definition: parson.c:2625
JSON_Object * json_value_get_object(const JSON_Value *value)
Definition: parson.c:1818
JSON_Status json_serialize_to_buffer_pretty(const JSON_Value *value, char *buf, size_t buf_size_in_bytes)
Definition: parson.c:2153
JSON_Object * json_array_get_object(const JSON_Array *array, size_t index)
Definition: parson.c:1784
size_t json_serialization_size_pretty(const JSON_Value *value)
Definition: parson.c:2144
json_value_type
Definition: parson.h:49
@ JSONError
Definition: parson.h:50
@ JSONObject
Definition: parson.h:54
@ JSONNull
Definition: parson.h:51
@ JSONNumber
Definition: parson.h:53
@ JSONBoolean
Definition: parson.h:56
@ JSONString
Definition: parson.h:52
@ JSONArray
Definition: parson.h:55
JSON_Value * json_value_init_string(const char *string)
Definition: parson.c:1913
JSON_Value * json_value_init_string_with_len(const char *string, size_t length)
Definition: parson.c:1921
JSON_Status json_array_append_boolean(JSON_Array *array, int boolean)
Definition: parson.c:2374
JSON_Value_Type json_type(const JSON_Value *value)
Definition: parson.c:2790
int json_object_dotget_boolean(const JSON_Object *object, const char *name)
Definition: parson.c:1702
JSON_Value * json_object_get_value(const JSON_Object *object, const char *name)
Definition: parson.c:1623
JSON_Status json_array_replace_string_with_len(JSON_Array *array, size_t i, const char *string, size_t len)
Definition: parson.c:2259
const char * json_value_get_string(const JSON_Value *value)
Definition: parson.c:1835
void *(* JSON_Malloc_Function)(size_t)
Definition: parson.h:63
JSON_Status json_object_dotset_null(JSON_Object *object, const char *name)
Definition: parson.c:2612
JSON_Status json_object_set_string_with_len(JSON_Object *object, const char *name, const char *string, size_t len)
Definition: parson.c:2457
JSON_Status json_object_set_number(JSON_Object *object, const char *name, double number)
Definition: parson.c:2469
int json_object_has_value_of_type(const JSON_Object *object, const char *name, JSON_Value_Type type)
Definition: parson.c:1741
void json_set_float_serialization_format(const char *format)
Definition: parson.c:2837
size_t json_array_get_count(const JSON_Array *array)
Definition: parson.c:1799
double json_array_get_number(const JSON_Array *array, size_t index)
Definition: parson.c:1779
json_result_t
Definition: parson.h:60
@ JSONSuccess
Definition: parson.h:60
@ JSONFailure
Definition: parson.h:60
JSON_Status json_array_replace_number(JSON_Array *array, size_t i, double number)
Definition: parson.c:2273
const char * json_array_get_string(const JSON_Array *array, size_t index)
Definition: parson.c:1769
int JSON_Value_Type
Definition: parson.h:58
JSON_Status json_array_clear(JSON_Array *array)
Definition: parson.c:2313
JSON_Array * json_value_get_array(const JSON_Value *value)
Definition: parson.c:1824
int(* JSON_Number_Serialization_Function)(double num, char *buf)
Definition: parson.h:71
JSON_Status json_object_set_string(JSON_Object *object, const char *name, const char *string)
Definition: parson.c:2446
JSON_Status json_object_set_boolean(JSON_Object *object, const char *name, int boolean)
Definition: parson.c:2480
void json_free_serialized_string(char *string)
Definition: parson.c:2213
JSON_Object * json_object_get_object(const JSON_Object *object, const char *name)
Definition: parson.c:1646
int json_value_equals(const JSON_Value *a, const JSON_Value *b)
Definition: parson.c:2723
JSON_Status json_validate(const JSON_Value *schema, const JSON_Value *value)
Definition: parson.c:2655
JSON_Status json_array_remove(JSON_Array *array, size_t i)
Definition: parson.c:2218
JSON_Value * json_object_get_wrapping_value(const JSON_Object *object)
Definition: parson.c:1728
JSON_Status json_serialize_to_file(const JSON_Value *value, const char *filename)
Definition: parson.c:2100
JSON_Status json_array_append_string_with_len(JSON_Array *array, const char *string, size_t len)
Definition: parson.c:2347
JSON_Value * json_object_dotget_value(const JSON_Object *object, const char *name)
Definition: parson.c:1661
char * json_serialize_to_string_pretty(const JSON_Value *value)
Definition: parson.c:2192
int json_object_dothas_value_of_type(const JSON_Object *object, const char *name, JSON_Value_Type type)
Definition: parson.c:1753
void json_set_escape_slashes(int escape_slashes)
Definition: parson.c:2832
JSON_Status json_object_dotset_value(JSON_Object *object, const char *name, JSON_Value *value)
Definition: parson.c:2501
struct json_array_t JSON_Array
Definition: parson.h:46
size_t json_object_get_count(const JSON_Object *object)
Definition: parson.c:1707
JSON_Value * json_parse_string(const char *string)
Definition: parson.c:1594
int json_boolean(const JSON_Value *value)
Definition: parson.c:2820
JSON_Value * json_value_get_parent(const JSON_Value *value)
Definition: parson.c:1858
double json_number(const JSON_Value *value)
Definition: parson.c:2815
JSON_Value * json_parse_string_with_comments(const char *string)
Definition: parson.c:1605
JSON_Value * json_object_get_value_at(const JSON_Object *object, size_t index)
Definition: parson.c:1720
int JSON_Status
Definition: parson.h:61
JSON_Status json_array_append_value(JSON_Array *array, JSON_Value *value)
Definition: parson.c:2326
int json_object_dothas_value(const JSON_Object *object, const char *name)
Definition: parson.c:1748
const char * json_string(const JSON_Value *value)
Definition: parson.c:2805
JSON_Object * json_object(const JSON_Value *value)
Definition: parson.c:2795
void json_set_number_serialization_function(JSON_Number_Serialization_Function fun)
Definition: parson.c:2850
int json_object_has_value(const JSON_Object *object, const char *name)
Definition: parson.c:1736
int json_value_get_boolean(const JSON_Value *value)
Definition: parson.c:1852
struct json_value_t JSON_Value
Definition: parson.h:47
JSON_Value * json_value_init_object(void)
Definition: parson.c:1881
JSON_Status json_object_clear(JSON_Object *object)
Definition: parson.c:2635
JSON_Array * json_array_get_array(const JSON_Array *array, size_t index)
Definition: parson.c:1789
JSON_Value * json_value_init_null(void)
Definition: parson.c:1970
int json_array_get_boolean(const JSON_Array *array, size_t index)
Definition: parson.c:1794
JSON_Status json_object_set_value(JSON_Object *object, const char *name, JSON_Value *value)
Definition: parson.c:2400
JSON_Status json_object_dotset_string_with_len(JSON_Object *object, const char *name, const char *string, size_t len)
Definition: parson.c:2569
void(* JSON_Free_Function)(void *)
Definition: parson.h:64
struct json_object_t JSON_Object
Definition: parson.h:45
size_t json_array_get_string_len(const JSON_Array *array, size_t index)
Definition: parson.c:1774
void json_value_free(JSON_Value *value)
Definition: parson.c:1863
JSON_Status json_object_set_null(JSON_Object *object, const char *name)
Definition: parson.c:2491
JSON_Status json_serialize_to_file_pretty(const JSON_Value *value, const char *filename)
Definition: parson.c:2168
size_t json_serialization_size(const JSON_Value *value)
Definition: parson.c:2076
JSON_Array * json_object_get_array(const JSON_Object *object, const char *name)
Definition: parson.c:1651
const char * json_object_dotget_string(const JSON_Object *object, const char *name)
Definition: parson.c:1673
JSON_Status json_array_append_string(JSON_Array *array, const char *string)
Definition: parson.c:2334
const char * json_object_get_string(const JSON_Object *object, const char *name)
Definition: parson.c:1631
size_t json_object_dotget_string_len(const JSON_Object *object, const char *name)
Definition: parson.c:1679
double json_value_get_number(const JSON_Value *value)
Definition: parson.c:1847
double json_object_get_number(const JSON_Object *object, const char *name)
Definition: parson.c:1641
double json_object_dotget_number(const JSON_Object *object, const char *name)
Definition: parson.c:1685
JSON_Value * json_parse_file(const char *filename)
Definition: parson.c:1570
JSON_Value_Type json_value_get_type(const JSON_Value *value)
Definition: parson.c:1813
JSON_Status json_array_replace_value(JSON_Array *array, size_t i, JSON_Value *value)
Definition: parson.c:2232
JSON_Array * json_array(const JSON_Value *value)
Definition: parson.c:2800
JSON_Value * json_value_init_boolean(int boolean)
Definition: parson.c:1958
char * json_serialize_to_string(const JSON_Value *value)
Definition: parson.c:2124
JSON_Status json_object_dotset_number(JSON_Object *object, const char *name, double number)
Definition: parson.c:2584
JSON_Status json_object_dotremove(JSON_Object *object, const char *key)
Definition: parson.c:2630
const char * json_object_get_name(const JSON_Object *object, size_t index)
Definition: parson.c:1712
void json_set_allocation_functions(JSON_Malloc_Function malloc_fun, JSON_Free_Function free_fun)
Definition: parson.c:2825
JSON_Array * json_object_dotget_array(const JSON_Object *object, const char *name)
Definition: parson.c:1696
JSON_Value * json_array_get_wrapping_value(const JSON_Array *array)
Definition: parson.c:1804
JSON_Value * json_value_init_number(double number)
Definition: parson.c:1942
JSON_Status json_array_append_number(JSON_Array *array, double number)
Definition: parson.c:2361
JSON_Status json_array_replace_string(JSON_Array *array, size_t i, const char *string)
Definition: parson.c:2245
JSON_Status json_serialize_to_buffer(const JSON_Value *value, char *buf, size_t buf_size_in_bytes)
Definition: parson.c:2085
double b
Definition: r_raster.c:39