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 /**
  60         @name JSON types
  61         @brief Macros defining types of jsonObject.
  62
  63         A jsonObject includes a @em type member with one of these values, identifying the type of
  64         jsonObject.  Client code should treat the @em type member as read-only.
  65 */
  66 /*@{*/
  67 #define JSON_HASH       0
  68 #define JSON_ARRAY      1
  69 #define JSON_STRING     2
  70 #define JSON_NUMBER     3
  71 #define JSON_NULL       4
  72 #define JSON_BOOL       5
  73 /*@}*/
  74
  75 /**
  76         @name JSON extensions
  77
  78         These two macros define tags used for encoding class information.  @em JSON_CLASS_KEY
  79         labels a class name, and @em JSON_DATA_KEY labels an associated value.
  80
  81         Because each of these macros is subject to an ifndef clause, client code may override
  82         the default choice of labels by defining alternatives before including this header.
  83         At this writing, this potential for customization is unused.
  84 */
  85 /*@{*/
  86 #ifndef JSON_CLASS_KEY
  87 #define JSON_CLASS_KEY "__c"
  88 #endif
  89 #ifndef JSON_DATA_KEY
  90 #define JSON_DATA_KEY "__p"
  91 #endif
  92 /*@}*/
  93
  94 /**
  95         @brief Representation of a JSON string in memory
  96
  97         Different types of jsonObject use different members of the @em value union.
  98
  99         Numbers are stored as character strings, using the same buffer that we use for
 100         strings.  As a result, a JSON_NUMBER can store numbers that cannot be represented
 101         by native C types.
 102
 103         (We used to store numbers as doubles.  We still have the @em n member lying around as
 104         a relic of those times, but we don't use it.  We can't get rid of it yet, either.  Long
 105         story.)
 106 */
 107 struct _jsonObjectStruct {
 108         unsigned long size;     /**< Number of sub-items. */
 109         char* classname;        /**< Optional class hint (not part of the JSON spec). */
 110         int type;               /**< JSON type. */
 111         struct _jsonObjectStruct* parent;   /**< Whom we're attached to. */
 112         /** Union used for various types of cargo. */
 113         union _jsonValue {
 114                 osrfHash*       h;      /**< Object container. */
 115                 osrfList*       l;      /**< Array container. */
 116                 char*           s;      /**< String or number. */
 117                 int             b;      /**< Bool. */
 118                 double  n;          /**< Number (no longer used). */
 119         } value;
 120 };
 121 typedef struct _jsonObjectStruct jsonObject;
 122
 123 /**
 124         @brief Iterator for traversing a jsonObject.
 125
 126         A jsonIterator traverses a jsonIterator only at a single level.  It does @em not descend
 127         into lower levels to traverse them recursively.
 128 */
 129 struct _jsonIteratorStruct {
 130         jsonObject* obj;           /**< The object we're traversing. */
 131         osrfHashIterator* hashItr; /**< The iterator for this hash. */
 132         const char* key;           /**< If this object is a hash, the current key. */
 133         unsigned long index;       /**< If this object is an array, the index. */
 134 };
 135 typedef struct _jsonIteratorStruct jsonIterator;
 136
 137 /**
 138         @brief Macros for upward compatibility with an old, defunct version
 139     of the JSON parser.
 140 */
 141 /*@{*/
 142 #define jsonParseString                jsonParse
 143 #define jsonParseStringRaw             jsonParseRaw
 144 #define jsonParseStringFmt             jsonParseFmt
 145 /*@}*/
 146
 147 jsonObject* jsonParse( const char* str );
 148
 149 jsonObject* jsonParseRaw( const char* str );
 150
 151 jsonObject* jsonParseFmt( const char* str, ... );
 152
 153 jsonObject* jsonNewObject(const char* data);
 154
 155 jsonObject* jsonNewObjectFmt(const char* data, ...);
 156
 157 jsonObject* jsonNewObjectType(int type);
 158
 159 jsonObject* jsonNewNumberObject( double num );
 160
 161 jsonObject* jsonNewNumberStringObject( const char* numstr );
 162
 163 jsonObject* jsonNewBoolObject(int val);
 164
 165 void jsonObjectFree( jsonObject* o );
 166
 167 void jsonObjectFreeUnused( void );
 168
 169 unsigned long jsonObjectPush(jsonObject* o, jsonObject* newo);
 170
 171 unsigned long jsonObjectSetKey(
 172                 jsonObject* o, const char* key, jsonObject* newo);
 173
 174 /*
 175  * Turns the object into a JSON string.  The string must be freed by the caller */
 176 char* jsonObjectToJSON( const jsonObject* obj );
 177 char* jsonObjectToJSONRaw( const jsonObject* obj );
 178
 179 jsonObject* jsonObjectGetKey( jsonObject* obj, const char* key );
 180
 181 const jsonObject* jsonObjectGetKeyConst( const jsonObject* obj, const char* key );
 182
 183 jsonIterator* jsonNewIterator(const jsonObject* obj);
 184
 185 void jsonIteratorFree(jsonIterator* itr);
 186
 187 jsonObject* jsonIteratorNext(jsonIterator* iter);
 188
 189 int jsonIteratorHasNext(const jsonIterator* itr);
 190
 191 jsonObject* jsonObjectGetIndex( const jsonObject* obj, unsigned long index );
 192
 193 unsigned long jsonObjectSetIndex(jsonObject* dest, unsigned long index, jsonObject* newObj);
 194
 195 unsigned long jsonObjectRemoveIndex(jsonObject* dest, unsigned long index);
 196
 197 jsonObject* jsonObjectExtractIndex(jsonObject* dest, unsigned long index);
 198
 199 unsigned long jsonObjectRemoveKey( jsonObject* dest, const char* key);
 200
 201 const char* jsonObjectGetString(const jsonObject*);
 202
 203 double jsonObjectGetNumber( const jsonObject* obj );
 204
 205 void jsonObjectSetString(jsonObject* dest, const char* string);
 206
 207 void jsonObjectSetNumber(jsonObject* dest, double num);
 208
 209 int jsonObjectSetNumberString(jsonObject* dest, const char* string);
 210
 211 void jsonObjectSetClass(jsonObject* dest, const char* classname );
 212
 213 const char* jsonObjectGetClass(const jsonObject* dest);
 214
 215 int jsonBoolIsTrue( const jsonObject* boolObj );
 216
 217 void jsonSetBool(jsonObject* bl, int val);
 218
 219 jsonObject* jsonObjectClone( const jsonObject* o );
 220
 221 char* jsonObjectToSimpleString( const jsonObject* o );
 222
 223 char* doubleToString( double num );
 224
 225 int jsonIsNumeric( const char* s );
 226
 227 char* jsonScrubNumber( const char* s );
 228
 229 /**
 230         @brief Provide an XPATH style search interface to jsonObjects.
 231         @param obj Pointer to the jsonObject to be searched.
 232         @param path Pointer to a printf-style format string specifying the search path.  Subsequent
 233                 parameters, if any, are formatted and inserted into the formatted string.
 234         @return A copy of the object at the specified location, if it exists, or NULL if it doesn't.
 235
 236         Example search path: /some/node/here.
 237
 238         Every element in the path must be a proper object, a JSON_HASH.
 239
 240         The calling code is responsible for freeing the jsonObject to which the returned pointer
 241         points.
 242 */
 243 jsonObject* jsonObjectFindPath( const jsonObject* obj, const char* path, ... );
 244
 245
 246 /**
 247         @brief Prettify a JSON string for printing, by adding newlines and other white space.
 248         @param jsonString Pointer to the original JSON string.
 249         @return Pointer to a prettified JSON string.
 250
 251         The calling code is responsible for freeing the returned string.
 252 */
 253 char* jsonFormatString( const char* jsonString );
 254
 255 /* ------------------------------------------------------------------------- */
 256 /*
 257  * The following methods provide a facility for serializing and
 258  * deserializing "classed" JSON objects.  To give a JSON object a
 259  * class, simply call jsonObjectSetClass().
 260  * Then, calling jsonObjectEncodeClass() will convert the JSON
 261  * object (and any sub-objects) to a JSON object with class
 262  * wrapper objects like so:
 263  * { "__c" : "classname", "__p" : [json_thing] }
 264  * In this example __c is the class key and __p is the data (object)
 265  * key.  The keys are defined by the constants
 266  * JSON_CLASS_KEY and JSON_DATA_KEY
 267  * To revive a serialized object, simply call
 268  * jsonObjectDecodeClass()
 269  */
 270
 271
 272 /* Converts a class-wrapped object into an object with the
 273  * classname set
 274  * Caller must free the returned object
 275  */
 276 jsonObject* jsonObjectDecodeClass( const jsonObject* obj );
 277
 278
 279 /* Converts an object with a classname into a
 280  * class-wrapped (serialized) object
 281  * Caller must free the returned object
 282  */
 283 jsonObject* jsonObjectEncodeClass( const jsonObject* obj );
 284
 285 /* ------------------------------------------------------------------------- */
 286
 287
 288 /*
 289  *      Generates an XML representation of a JSON object */
 290 char* jsonObjectToXML(const jsonObject*);
 291
 292 /*
 293  * Builds a JSON object from the provided XML
 294  */
 295 jsonObject* jsonXMLToJSONObject(const char* xml);
 296
 297 #ifdef __cplusplus
 298 }
 299 #endif
 300
 301 #endif