2 Copyright (C) 2005 Georgia Public Library Service
3 Bill Erickson <highfalutin@gmail.com>
5 This program is free software; you can redistribute it and/or
6 modify it under the terms of the GNU General Public License
7 as published by the Free Software Foundation; either version 2
8 of the License, or (at your option) any later version.
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
17 /* ---------------------------------------------------------------------------------------
19 * --------------------------------------------------------------------------------------- */
21 #ifndef _JSON_OBJECT_H
22 #define _JSON_OBJECT_H
31 /* json object types */
40 /* top level generic object structure */
41 struct _jsonObjectStruct {
43 /* how many sub-objects do we contain if we're an array or an object.
44 Note that this includes null array elements in sparse arrays */
47 /* optional class hint */
50 /* see JSON types above */
55 union _jsonObjectValue {
56 struct _jsonObjectNodeStruct* c; /* our list of sub-objects if we're an array or a hash */
59 double n; /* number */
63 /* client may provide a comment string which will be
64 * added to the object when stringified */
68 typedef struct _jsonObjectStruct jsonObject;
72 String parsing function. This is assigned by the json_parser code.
73 to avoid circular dependency, declare the parse function here,
74 and have the json parse code set the variable to a real function
76 //jsonObject* (*jsonParseString) (char* str);
79 /* this contains a single element of the object along with the elements
80 * index (if this object is an array) and key (if this object is a hash)
82 struct _jsonObjectNodeStruct {
84 unsigned long index; /* our array position */
85 char* key; /* our hash key */
87 jsonObject* item; /* our object */
88 struct _jsonObjectNodeStruct* next; /* pointer to the next object node */
90 typedef struct _jsonObjectNodeStruct jsonObjectNode;
94 /* utility object for iterating over hash objects */
95 struct _jsonObjectIteratorStruct {
96 const jsonObject* obj; /* the topic object */
97 jsonObjectNode* current; /* the current node within the object */
99 typedef struct _jsonObjectIteratorStruct jsonObjectIterator;
102 /** Allocates a new iterator
103 @param obj The object over which to iterate.
105 jsonObjectIterator* jsonNewObjectIterator(const jsonObject* obj);
108 De-allocates an iterator
109 @param iter The iterator object to free
111 void jsonObjectIteratorFree(jsonObjectIterator* iter);
114 Returns the object_node currently pointed to by the iterator
115 and increments the pointer to the next node
116 @param iter The iterator in question.
118 jsonObjectNode* jsonObjectIteratorNext(jsonObjectIterator* iter);
121 @param iter The iterator.
122 @return True if there is another node after the current node.
124 int jsonObjectIteratorHasNext(const jsonObjectIterator* iter);
128 Allocates a new object.
129 @param string The string data if this object is to be a string.
130 if not, string should be NULL
131 @return The newly allocated object or NULL on memory error.
133 jsonObject* jsonNewObject(const char* string, ...);
136 Allocates a new JSON number object.
137 @param num The number this object is to hold
138 @return The newly allocated object.
140 jsonObject* jsonNewNumberObject( double num );
144 Returns a pointer to the object at the given index. This call is
145 only valid if the object has a type of JSON_ARRAY.
146 @param obj The object
147 @param index The position within the object
148 @return The object at the given index.
150 jsonObject* jsonObjectGetIndex( const jsonObject* obj, unsigned long index );
154 Returns a pointer to the object with the given key
155 @param obj The object
157 @return The object with the given key.
159 jsonObject* jsonObjectGetKey( const jsonObject* obj, const char* key );
162 De-allocates an object. Note that this function should only be called
163 on objects that are _not_ children of other objects or there will be
165 @param obj The object to free.
167 void jsonObjectFree(jsonObject* obj);
171 Allocates a new object node.
172 @param obj The object to which the node will be appended.
173 @return The new object node.
175 jsonObjectNode* jsonNewObjectNode(jsonObject* obj);
178 De-allocates an object node
179 @param obj The object node to de-allocate.
181 void jsonObjectNodeFree(jsonObjectNode* obj);
185 Pushes the given object onto the end of the list. This coerces an object
186 into becoming an array. _Only_ use this function on objects that you
187 want to become an array.
188 If obj is NULL, inserts a new NULL object into the list.
189 @return array size on success, -1 on error
191 unsigned long jsonObjectPush(jsonObject* dest, jsonObject* newObj);
193 /* removes (and deallocates) the object at the given index (if one exists) and inserts
194 * the new one. returns the size on success, -1 on error
195 * If obj is NULL, inserts a new object into the list with is_null set to true
197 unsigned long jsonObjectSetIndex(jsonObject* dest, unsigned long index, jsonObject* newObj);
199 /* inserts the new object, overwriting (removing, deallocating) any
200 * previous object with the given key.
201 * returns the size on success, -1 on error
202 * if 'obj' is NULL, a new object is inserted at key 'key' with 'is_null'
205 unsigned long jsonObjectSetKey(jsonObject* dest, const char* key, jsonObject* newObj);
207 /* removes the object at the given index and, if more items exist,
208 * re-indexes (shifts down by 1) the rest of the objects in the array
210 unsigned long jsonObjectRemoveIndex(jsonObject* dest, unsigned long index);
212 /* removes (and deallocates) the object with key 'key' if it exists */
213 unsigned long jsonObjectRemoveKey( jsonObject* dest, const char* key);
215 /* returns a pointer to the string data held by this object if this object
216 is a string. Otherwise returns NULL*/
217 char* jsonObjectGetString(const jsonObject*);
219 double jsonObjectGetNumber( const jsonObject* obj );
221 /* sets the string data */
222 void jsonObjectSetString(jsonObject* dest, const char* string);
224 /* sets the number value for the object */
225 void jsonObjectSetNumber(jsonObject* dest, double num);
227 /* sets the class hint for this object */
228 void jsonObjectSetClass(jsonObject* dest, const char* classname );
230 /* converts an object to a json string. client is responsible for freeing the return string */
231 char* jsonObjectToJSON( const jsonObject* obj );
233 /* set this object's comment string */
234 void jsonObjectSetComment(jsonObject* dest, const char* classname);
236 /* utility method. starting at index 'index', shifts all indices down by one and
237 * decrements the objects size by 1
239 void _jsonObjectShiftIndex(jsonObject* dest, unsigned long index);
241 /* formats a JSON string from printing. User must free returned string */
242 char* jsonFormatString( const char* jsonString );
244 jsonObject* jsonObjectClone( const jsonObject* o );
246 /* tries to extract the string data from an object.
247 if object -> NULL (the C NULL)
248 if array -> NULL (the C NULL)
249 if null -> NULL (the C NULL)
250 if true/false -> true/false
251 if string/number/double the string version of either of those
252 The caller is responsible for freeing the returned string
254 char* jsonObjectToSimpleString( const jsonObject* o );
257 /* ------------------------------------------------------------------------ */
260 /* provides an XPATH style search interface (e.g. /some/node/here) and
261 return the object at that location if one exists. Naturally,
262 every element in the path must be a proper object ("hash" / {}).
263 Returns NULL if the specified node is not found
264 Note also that the object returned is a clone and
265 must be freed by the caller
267 jsonObject* jsonObjectFindPath( const jsonObject* obj, char* path, ... );
270 /* Utility method. finds any object in the tree that matches the path.
271 Use this for finding paths that start with '//' */
272 jsonObject* _jsonObjectFindPathRecurse( const jsonObject* o, char* root, char* path );
274 /* returns a list of object whose key is 'root'. These are used as
275 potential objects when doing a // search */
276 jsonObject* __jsonObjectFindPathRecurse( const jsonObject* o, char* root );
278 /* ------------------------------------------------------------------------ */