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
29 //#include "opensrf/utils.h"
32 /* json object types */
41 /* top level generic object structure */
42 struct _jsonObjectStruct {
44 /* how many sub-objects do we contain if we're an array or an object.
45 Note that this includes null array elements in sparse arrays */
48 /* optional class hint */
51 /* see JSON types above */
56 union _jsonObjectValue {
57 struct _jsonObjectNodeStruct* c; /* our list of sub-objects if we're an array or a hash */
60 double n; /* number */
64 /* client may provide a comment string which will be
65 * added to the object when stringified */
69 typedef struct _jsonObjectStruct jsonObject;
73 String parsing function. This is assigned by the json_parser code.
74 to avoid circular dependency, declare the parse function here,
75 and have the json parse code set the variable to a real function
77 //jsonObject* (*jsonParseString) (char* str);
80 /* this contains a single element of the object along with the elements
81 * index (if this object is an array) and key (if this object is a hash)
83 struct _jsonObjectNodeStruct {
85 unsigned long index; /* our array position */
86 char* key; /* our hash key */
88 jsonObject* item; /* our object */
89 struct _jsonObjectNodeStruct* next; /* pointer to the next object node */
91 typedef struct _jsonObjectNodeStruct jsonObjectNode;
95 /* utility object for iterating over hash objects */
96 struct _jsonObjectIteratorStruct {
97 const jsonObject* obj; /* the topic object */
98 jsonObjectNode* current; /* the current node within the object */
100 typedef struct _jsonObjectIteratorStruct jsonObjectIterator;
103 /** Allocates a new iterator
104 @param obj The object over which to iterate.
106 jsonObjectIterator* jsonNewObjectIterator(const jsonObject* obj);
109 De-allocates an iterator
110 @param iter The iterator object to free
112 void jsonObjectIteratorFree(jsonObjectIterator* iter);
115 Returns the object_node currently pointed to by the iterator
116 and increments the pointer to the next node
117 @param iter The iterator in question.
119 jsonObjectNode* jsonObjectIteratorNext(jsonObjectIterator* iter);
122 @param iter The iterator.
123 @return True if there is another node after the current node.
125 int jsonObjectIteratorHasNext(const jsonObjectIterator* iter);
129 Allocates a new object.
130 @param string The string data if this object is to be a string.
131 if not, string should be NULL
132 @return The newly allocated object or NULL on memory error.
134 jsonObject* jsonNewObjectFmt(const char* string, ...);
135 jsonObject* jsonNewObject(const char* string);
138 Allocates a new JSON number object.
139 @param num The number this object is to hold
140 @return The newly allocated object.
142 jsonObject* jsonNewNumberObject( double num );
146 Returns a pointer to the object at the given index. This call is
147 only valid if the object has a type of JSON_ARRAY.
148 @param obj The object
149 @param index The position within the object
150 @return The object at the given index.
152 jsonObject* jsonObjectGetIndex( const jsonObject* obj, unsigned long index );
156 Returns a pointer to the object with the given key
157 @param obj The object
159 @return The object with the given key.
161 jsonObject* jsonObjectGetKey( const jsonObject* obj, const char* key );
164 De-allocates an object. Note that this function should only be called
165 on objects that are _not_ children of other objects or there will be
167 @param obj The object to free.
169 void jsonObjectFree(jsonObject* obj);
173 Allocates a new object node.
174 @param obj The object to which the node will be appended.
175 @return The new object node.
177 jsonObjectNode* jsonNewObjectNode(jsonObject* obj);
180 De-allocates an object node
181 @param obj The object node to de-allocate.
183 void jsonObjectNodeFree(jsonObjectNode* obj);
187 Pushes the given object onto the end of the list. This coerces an object
188 into becoming an array. _Only_ use this function on objects that you
189 want to become an array.
190 If obj is NULL, inserts a new NULL object into the list.
191 @return array size on success, -1 on error
193 unsigned long jsonObjectPush(jsonObject* dest, jsonObject* newObj);
195 /* removes (and deallocates) the object at the given index (if one exists) and inserts
196 * the new one. returns the size on success, -1 on error
197 * If obj is NULL, inserts a new object into the list with is_null set to true
199 unsigned long jsonObjectSetIndex(jsonObject* dest, unsigned long index, jsonObject* newObj);
201 /* inserts the new object, overwriting (removing, deallocating) any
202 * previous object with the given key.
203 * returns the size on success, -1 on error
204 * if 'obj' is NULL, a new object is inserted at key 'key' with 'is_null'
207 unsigned long jsonObjectSetKey(jsonObject* dest, const char* key, jsonObject* newObj);
209 /* removes the object at the given index and, if more items exist,
210 * re-indexes (shifts down by 1) the rest of the objects in the array
212 unsigned long jsonObjectRemoveIndex(jsonObject* dest, unsigned long index);
214 /* removes (and deallocates) the object with key 'key' if it exists */
215 unsigned long jsonObjectRemoveKey( jsonObject* dest, const char* key);
217 /* returns a pointer to the string data held by this object if this object
218 is a string. Otherwise returns NULL*/
219 char* jsonObjectGetString(const jsonObject*);
221 double jsonObjectGetNumber( const jsonObject* obj );
223 /* sets the string data */
224 void jsonObjectSetString(jsonObject* dest, const char* string);
226 /* sets the number value for the object */
227 void jsonObjectSetNumber(jsonObject* dest, double num);
229 /* sets the class hint for this object */
230 void jsonObjectSetClass(jsonObject* dest, const char* classname );
232 /* converts an object to a json string. client is responsible for freeing the return string */
233 char* jsonObjectToJSON( const jsonObject* obj );
235 /* set this object's comment string */
236 void jsonObjectSetComment(jsonObject* dest, const char* classname);
238 /* utility method. starting at index 'index', shifts all indices down by one and
239 * decrements the objects size by 1
241 void _jsonObjectShiftIndex(jsonObject* dest, unsigned long index);
243 /* formats a JSON string from printing. User must free returned string */
244 char* jsonFormatString( const char* jsonString );
246 jsonObject* jsonObjectClone( const jsonObject* o );
248 /* tries to extract the string data from an object.
249 if object -> NULL (the C NULL)
250 if array -> NULL (the C NULL)
251 if null -> NULL (the C NULL)
252 if true/false -> true/false
253 if string/number/double the string version of either of those
254 The caller is responsible for freeing the returned string
256 char* jsonObjectToSimpleString( const jsonObject* o );
258 int jsonBoolIsTrue( const jsonObject* o );
261 /* ------------------------------------------------------------------------ */
264 /* provides an XPATH style search interface (e.g. /some/node/here) and
265 return the object at that location if one exists. Naturally,
266 every element in the path must be a proper object ("hash" / {}).
267 Returns NULL if the specified node is not found
268 Note also that the object returned is a clone and
269 must be freed by the caller
271 jsonObject* jsonObjectFindPath( const jsonObject* obj, char* path, ... );
274 /* Utility method. finds any object in the tree that matches the path.
275 Use this for finding paths that start with '//' */
276 jsonObject* _jsonObjectFindPathRecurse( const jsonObject* o, char* root, char* path );
278 /* returns a list of object whose key is 'root'. These are used as
279 potential objects when doing a // search */
280 jsonObject* __jsonObjectFindPathRecurse( const jsonObject* o, char* root );
282 /* ------------------------------------------------------------------------ */