1. Add doxygen markup for documentation.
[OpenSRF.git] / include / opensrf / osrf_json.h
1 /*
2 Copyright (C) 2006  Georgia Public Library Service 
3 Bill Erickson <billserickson@gmail.com>
4
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.
9
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.
14 */
15
16 /**
17         @file osrf_json.h
18         @brief Header for parsing JSON structures and representing them in memory.
19
20         JSON is a format for representing hierarchical data structures as text.
21
22         A JSON string may be a quoted string, a numeric literal, or any of the keywords true, false
23         and null.
24
25         A JSON string may also be an array, i.e. a series of values, separated by commas and enclosed
26         in square brackets.  For example: [ "Adams", 42, null, true ]
27
28         A JSON string may also be an object, i.e. a series of name/value pairs, separated by commas
29         and enclosed by curly braces.  Each name/value pair is a quoted string, followed by a colon,
30         followed by a value.  For example: { "Author":"Adams", "answer":42, "question":null,
31         "profound": true }
32
33         The values in a JSON array or object may themselves be arrays or objects, nested to any
34         depth, in a hierarchical structure of arbitrary complexity.  For more information about
35         JSON, see http://json.org/.
36
37         Like a JSON string, a jsonObject can take several different forms.  It can hold a string, a
38         number, a boolean, or a null.  It can also hold an array, implemented internally by an
39         osrfList (see osrf_list.h).  It can also hold a series of name/value pairs, implemented
40         internally by an osrfHash (see osrf_hash.h).
41
42         A jsonObject can also tag its contents with a class name, typically referring to a
43         database table or view.  Such an object can be translated into a JSON string where the
44         class is encoded as the value of a name/value pair, with the original jsonObject encoded
45         as the value of a second name/value pair.
46 */
47
48 #ifndef JSON_H
49 #define JSON_H
50
51 #include <opensrf/utils.h>
52 #include <opensrf/osrf_list.h>
53 #include <opensrf/osrf_hash.h>
54
55 #ifdef __cplusplus
56 extern "C" {
57 #endif
58
59 /* parser states */
60 /**
61         @name Parser states
62         @brief Used internally by a JSON parser.
63
64         A jsonParserContext stores these values in order to remember where the parser is in the
65         parsing.
66 */
67 /*@{*/
68 #define JSON_STATE_IN_OBJECT    0x1
69 #define JSON_STATE_IN_ARRAY             0x2
70 #define JSON_STATE_IN_STRING    0x4
71 #define JSON_STATE_IN_UTF               0x8
72 #define JSON_STATE_IN_ESCAPE    0x10
73 #define JSON_STATE_IN_KEY               0x20
74 #define JSON_STATE_IN_NULL              0x40
75 #define JSON_STATE_IN_TRUE              0x80
76 #define JSON_STATE_IN_FALSE             0x100
77 #define JSON_STATE_IN_NUMBER    0x200
78 #define JSON_STATE_IS_INVALID   0x400
79 #define JSON_STATE_IS_DONE              0x800
80 #define JSON_STATE_START_COMMEN 0x1000
81 #define JSON_STATE_IN_COMMENT   0x2000
82 #define JSON_STATE_END_COMMENT  0x4000
83 /*@}*/
84
85 /**
86         @name Parser state operations
87         @ Macros to manipulate the parser state in a jsonParserContext.
88 */
89 /*@{*/
90 /** Set a state. */
91 #define JSON_STATE_SET(ctx,s) ctx->state |= s; 
92 /** Unset a state. */
93 #define JSON_STATE_REMOVE(ctx,s) ctx->state &= ~s;
94 /** Check if a state is set. */
95 #define JSON_STATE_CHECK(ctx,s) (ctx->state & s) ? 1 : 0
96 /** Pop a state off the stack. */
97 #define JSON_STATE_POP(ctx) osrfListPop( ctx->stateStack );
98 /** Push a state on the stack. */
99 #define JSON_STATE_PUSH(ctx, state) osrfListPush( ctx->stateStack,(void*) state );
100 /** Check which container type we're currently in. */
101 #define JSON_STATE_PEEK(ctx) osrfListGetIndex(ctx->stateStack, ctx->stateStack->size -1)
102 /** Compare stack values. */
103 #define JSON_STATE_CHECK_STACK(ctx, s) (JSON_STATE_PEEK(ctx) == (void*) s ) ? 1 : 0
104 /** Check if a parser state is set. */
105 #define JSON_PARSE_FLAG_CHECK(ctx, f) (ctx->flags & f) ? 1 : 0
106 /*@}*/
107
108 /**
109         @name JSON types
110         @brief Macros defining types of jsonObject.
111
112         A jsonObject includes a @em type member with one of these values, identifying the type of
113         jsonObject.  Client code should treat the @em type member as read-only.
114 */
115 /*@{*/
116 #define JSON_HASH       0
117 #define JSON_ARRAY      1
118 #define JSON_STRING     2
119 #define JSON_NUMBER     3
120 #define JSON_NULL       4
121 #define JSON_BOOL       5
122 /*@}*/
123
124 /**
125         This macro is used only by a JSON parser.  It probably has no business being published
126         in a header.
127 */
128 #define JSON_PARSE_LAST_CHUNK 0x1 /* this is the last part of the string we're parsing */
129
130 /**
131         @name JSON extensions
132
133         These two macros define tags used for encoding class information.  @em JSON_CLASS_KEY
134         labels a class name, and @em JSON_DATA_KEY labels an associated value.
135
136         Because each of these macros is subject to an ifndef clause, client code may override
137         the default choice of labels by defining alternatives before including this header.
138         At this writing, this potential for customization is unused.
139 */
140 /*@{*/
141 #ifndef JSON_CLASS_KEY
142 #define JSON_CLASS_KEY "__c"
143 #endif
144 #ifndef JSON_DATA_KEY
145 #define JSON_DATA_KEY "__p"
146 #endif
147 /*@}*/
148
149 /**
150         @brief Stores the current state of a JSON parser.
151
152         One form of JSON parser operates as a finite state machine.  It stores the various
153         JSON_STATE_* values in order to keep track of what it's doing.  It also maintains a
154         stack of previous states in order to keep track of nesting.
155
156         The internals of this struct are published in the header in order to provide the client
157         with a window into the operations of the parser.  By installing its own callback functions,
158         and possibly by tinkering with the insides of the jsonParserContext, the client code can
159         customize the behavior of the parser.
160
161         In practice only the default callbacks are ever installed, at this writing.  The potential
162         for customized parsing is unused.
163 */
164 struct jsonParserContextStruct {
165         int state;                  /**< What are we currently parsing. */
166         const char* chunk;          /**< The chunk we're currently parsing. */
167         int index;                  /**< Where we are in parsing the current chunk. */
168         int chunksize;              /**< Size of the current chunk. */
169         int flags;                  /**< Parser flags. */
170         osrfList* stateStack;       /**< The nest of object/array states. */
171         growing_buffer* buffer;     /**< Buffer for building strings, numbers, and keywords. */
172         growing_buffer* utfbuf;     /**< Holds the current unicode characters. */
173         void* userData;             /**< Opaque user pointer.  We ignore this. */
174         const struct jsonParserHandlerStruct* handler; /**< The event handler struct. */
175 };
176 typedef struct jsonParserContextStruct jsonParserContext;
177
178 /**
179         @brief A collection of function pointers for customizing parser behavior.
180
181         The client code can install pointers to its own functions in this struct, in order to
182         customize the behavior of the parser at various points in the parsing.
183 */
184 struct jsonParserHandlerStruct {
185         void (*handleStartObject)       (void* userData);
186         void (*handleObjectKey)         (void* userData, char* key);
187         void (*handleEndObject)         (void* userData);
188         void (*handleStartArray)        (void* userData);
189         void (*handleEndArray)          (void* userData);
190         void (*handleNull)                      (void* userData);
191         void (*handleString)            (void* userData, char* string);
192         void (*handleBool)                      (void* userData, int boolval);
193         void (*handleNumber)            (void* userData, const char* numstr);
194         void (*handleError)                     (void* userData, char* err, ...);
195 };
196 typedef struct jsonParserHandlerStruct jsonParserHandler;
197
198 /**
199         @brief Representation of a JSON string in memory
200
201         Different types of jsonObject use different members of the @em value union.
202
203         Numbers are stored as character strings, using the same buffer that we use for
204         strings.  As a result, a JSON_NUMBER can store numbers that cannot be represented
205         by native C types.
206
207         (We used to store numbers as doubles.  We still have the @em n member lying around as
208         a relic of those times, but we don't use it.  We can't get rid of it yet, either.  Long
209         story.)
210 */
211 struct _jsonObjectStruct {
212         unsigned long size;     /**< Number of sub-items. */
213         char* classname;        /**< Optional class hint (not part of the JSON spec). */
214         int type;               /**< JSON type. */
215         struct _jsonObjectStruct* parent;   /**< Whom we're attached to. */
216         /** Union used for various types of cargo. */
217         union _jsonValue {
218                 osrfHash*       h;      /**< Object container. */
219                 osrfList*       l;      /**< Array container. */
220                 char*           s;      /**< String or number. */
221                 int             b;      /**< Bool. */
222                 double  n;          /**< Number (no longer used). */
223         } value;
224 };
225 typedef struct _jsonObjectStruct jsonObject;
226
227 /**
228         @brief Iterator for traversing a jsonObject.
229
230         A jsonIterator traverses a jsonIterator only at a single level.  It does @em not descend
231         into lower levels to traverse them recursively.
232 */
233 struct _jsonIteratorStruct {
234         jsonObject* obj;           /**< The object we're traversing. */
235         osrfHashIterator* hashItr; /**< The iterator for this hash. */
236         const char* key;           /**< If this object is a hash, the current key. */
237         unsigned long index;       /**< If this object is an array, the index. */
238 };
239 typedef struct _jsonIteratorStruct jsonIterator;
240
241
242
243 /** 
244         @brief Allocate a new parser context object.
245         @param handler Pointer to a collection of function pointers for callback functions.
246         @param userData Opaque user pointer which is available to callbacks; ignored by the parser.
247         @return An allocated parser context, or NULL on error.
248 */
249 jsonParserContext* jsonNewParser( const jsonParserHandler* handler, void* userData);
250
251 /**
252         @brief Free a jsonParserContext.
253         @param ctx Pointer to the jsonParserContext to be freed.
254 */
255 void jsonParserFree( jsonParserContext* ctx );
256
257 /**
258         @brief Parse a chunk of data.
259         @param ctx Pointer to the parser context.
260         @param data Pointer the data to parse.
261         @param datalen The size of the chunk to parse.
262         @param flags Reserved.
263 */
264 int jsonParseChunk( jsonParserContext* ctx, const char* data, int datalen, int flags );
265
266 /**
267         @name Parsing functions
268         
269         There are two sets of parsing functions, which are mostly plug-compatible with each other.
270         The older series:
271
272         - jsonParseString()
273         - jsonParseStringRaw()
274         - jsonParseStringFmt()
275
276         ...and a newer series:
277
278         - jsonParseString();
279         - jsonParseStringRaw();
280         - jsonParseStringFmt();
281
282         The first series is based on a finite state machine.  Its innards are accessible, in
283         theory, through the jsonParserContext structure and through callback functions.  In
284         practice this flexibility is unused at this writing.
285
286         The second series is based on recursive descent.  It doesn't use the jsonParserContext
287         structure, nor does it accept callback functions.  However it is faster than the first
288         parser.  In addition its syntax checking is much stricter -- it catches many kinds of
289         syntax errors that slip through the first parser.
290 */
291 /*@{*/
292 /**
293         @brief Parse a JSON string;
294         @param str Pointer to the JSON string to parse.
295         @return The resulting JSON object, or NULL on error.
296 */
297 jsonObject* jsonParseString( const char* str );
298 jsonObject* jsonParseStringRaw( const char* str );
299 jsonObject* jsonParseStringFmt( const char* str, ... );
300
301 /**
302         @brief Parse a JSON string;
303         @param s Pointer to the JSON string to parse.
304         @return The resulting JSON object, or NULL on error.
305  */
306 jsonObject* jsonParse( const char* s );
307 jsonObject* jsonParseRaw( const char* s );
308 jsonObject* jsonParseFmt( const char* str, ... );
309 /*@}*/
310
311 /**
312         @brief Parses a JSON string, using a customized error handler.
313         @param errorHandler A function pointer to an error-handling function.
314         @param str The string to parse.
315         @return The resulting JSON object, or NULL on error.
316  */
317 jsonObject* jsonParseStringHandleError( void (*errorHandler) (const char*), char* str, ... );
318
319 jsonObject* jsonNewObject(const char* data);
320
321 jsonObject* jsonNewObjectFmt(const char* data, ...);
322
323 jsonObject* jsonNewObjectType(int type);
324
325 jsonObject* jsonNewNumberObject( double num );
326
327 jsonObject* jsonNewNumberStringObject( const char* numstr );
328
329 jsonObject* jsonNewBoolObject(int val);
330
331 void jsonObjectFree( jsonObject* o );
332
333 void jsonObjectFreeUnused( void );
334
335 unsigned long jsonObjectPush(jsonObject* o, jsonObject* newo);
336
337 unsigned long jsonObjectSetKey(
338                 jsonObject* o, const char* key, jsonObject* newo);
339
340 /*
341  * Turns the object into a JSON string.  The string must be freed by the caller */
342 char* jsonObjectToJSON( const jsonObject* obj );
343 char* jsonObjectToJSONRaw( const jsonObject* obj );
344
345 jsonObject* jsonObjectGetKey( jsonObject* obj, const char* key );
346
347 const jsonObject* jsonObjectGetKeyConst( const jsonObject* obj, const char* key );
348
349 jsonIterator* jsonNewIterator(const jsonObject* obj);
350
351 void jsonIteratorFree(jsonIterator* itr);
352
353 jsonObject* jsonIteratorNext(jsonIterator* iter);
354
355 int jsonIteratorHasNext(const jsonIterator* itr);
356
357 jsonObject* jsonObjectGetIndex( const jsonObject* obj, unsigned long index );
358
359 unsigned long jsonObjectSetIndex(jsonObject* dest, unsigned long index, jsonObject* newObj);
360
361 unsigned long jsonObjectRemoveIndex(jsonObject* dest, unsigned long index);
362
363 jsonObject* jsonObjectExtractIndex(jsonObject* dest, unsigned long index);
364
365 unsigned long jsonObjectRemoveKey( jsonObject* dest, const char* key);
366
367 char* jsonObjectGetString(const jsonObject*);
368
369 double jsonObjectGetNumber( const jsonObject* obj );
370
371 void jsonObjectSetString(jsonObject* dest, const char* string);
372
373 void jsonObjectSetNumber(jsonObject* dest, double num);
374
375 int jsonObjectSetNumberString(jsonObject* dest, const char* string);
376
377 void jsonObjectSetClass(jsonObject* dest, const char* classname );
378
379 const char* jsonObjectGetClass(const jsonObject* dest);
380
381 int jsonBoolIsTrue( const jsonObject* boolObj );
382
383 void jsonSetBool(jsonObject* bl, int val);
384
385 jsonObject* jsonObjectClone( const jsonObject* o );
386
387 char* jsonObjectToSimpleString( const jsonObject* o );
388
389 char* doubleToString( double num );
390
391 int jsonIsNumeric( const char* s );
392
393 char* jsonScrubNumber( const char* s );
394
395 /**
396         @brief Provide an XPATH style search interface to jsonObjects.
397         @param obj Pointer to the jsonObject to be searched.
398         @param path Pointer to a printf-style format string specifying the search path.  Subsequent
399                 parameters, if any, are formatted and inserted into the formatted string.
400         @return A copy of the object at the specified location, if it exists, or NULL if it doesn't.
401
402         Example search path: /some/node/here.
403         
404         Every element in the path must be a proper object, a JSON_HASH.
405
406         The calling code is responsible for freeing the jsonObject to which the returned pointer
407         points.
408 */
409 jsonObject* jsonObjectFindPath( const jsonObject* obj, const char* path, ... );
410
411
412 /**
413         @brief Prettify a JSON string for printing, by adding newlines and other white space.
414         @param jsonString Pointer to the original JSON string.
415         @return Pointer to a prettified JSON string.
416
417         The calling code is responsible for freeing the returned string.
418 */
419 char* jsonFormatString( const char* jsonString );
420
421 /* sets the error handler for all parsers */
422 void jsonSetGlobalErrorHandler(void (*errorHandler) (const char*));
423
424 /* ------------------------------------------------------------------------- */
425 /*
426  * The following methods provide a facility for serializing and
427  * deserializing "classed" JSON objects.  To give a JSON object a 
428  * class, simply call jsonObjectSetClass().
429  * Then, calling jsonObjectEncodeClass() will convert the JSON
430  * object (and any sub-objects) to a JSON object with class
431  * wrapper objects like so:
432  * { "__c" : "classname", "__p" : [json_thing] }
433  * In this example __c is the class key and __p is the data (object)
434  * key.  The keys are defined by the constants 
435  * JSON_CLASS_KEY and JSON_DATA_KEY
436  * To revive a serialized object, simply call
437  * jsonObjectDecodeClass()
438  */
439
440
441 /* Converts a class-wrapped object into an object with the
442  * classname set
443  * Caller must free the returned object 
444  */ 
445 jsonObject* jsonObjectDecodeClass( const jsonObject* obj );
446
447
448 /* Converts an object with a classname into a
449  * class-wrapped (serialized) object
450  * Caller must free the returned object 
451  */ 
452 jsonObject* jsonObjectEncodeClass( const jsonObject* obj );
453
454 /* ------------------------------------------------------------------------- */
455
456
457 /*
458  *      Generates an XML representation of a JSON object */
459 char* jsonObjectToXML(const jsonObject*);
460
461 /*
462  * Builds a JSON object from the provided XML 
463  */
464 jsonObject* jsonXMLToJSONObject(const char* xml);
465
466 #ifdef __cplusplus
467 }
468 #endif
469
470 #endif