UT/UT_JSONValue.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * Produced by:
 *      Side Effects Software Inc
 *      123 Front Street West, Suite 1401
 *      Toronto, Ontario
 *      Canada   M5J 2M2
 *      416-504-9876
 *
 * NAME:        UT_JSONValue.h ( UT Library, C++)
 *
 * COMMENTS:    This class represents a JSON object.
 */

#ifndef __UT_JSONValue__
#define __UT_JSONValue__

#include "UT_API.h"
#include "UT_PtrArray.h"
#include "UT_SymbolTable.h"

class UT_JSONValueArray;
class UT_JSONValueMap;
class UT_JSONParser;
class UT_JSONWriter;
class UT_JSONIStream;
class UT_IStream;
class UT_WorkBuffer;

/// @brief Class to store JSON objects as C++ objects
///
/// This class is able to represent a JSON object in its entirety.  Arrays and
/// Maps store arrays and maps of JSON values.
///
/// There are methods to load a JSONValue from a UT_JSONParser and to save to a
/// UT_JSONWriter object.
///
/// To load an entire JSON file into memory, you can do something like
/// @code
///     UT_JSONIStream  *is = UT_JSONIStream::create(args);
///     UT_JSONParser   parser();
///     UT_JSONValue    value;
///     if (!value.load(parser, *is))
///             reportFailure(parser.getErrors());
/// @endcode
///
/// To save a value:
/// @code
///     UT_JSONWriterSubclass    &os;
///     value.save(os);
/// @endcode
///
/// Alternatively, it's possible to use the UT_JSONValue class from within
/// other UT_JSONHandle classes.  For example, when loading key/value pairs for
/// an arbitrary map:
/// @code
///     bool
///     my_handle::jsonKey(UT_JSONParser &parser, const char *token, int64)
///     {
///          UT_String          keyword;
///          UT_JSONValue       value;
///          keyword.harden(token);
///          if (!value.load(parser))
///             return false;
///          process(keyword, value);
///          return true;
///     }
/// @endcode
/// @see UT_JSONParser, UT_JSONWriter, UT_JSONHandle, UT_JSONValueArray,
/// UT_JSONValueMap

class UT_API UT_JSONValue {
public:
    /// Types held in the UT_JSONValue.  The number type has been broken out
    /// into an integer and a real.
    enum Type {
        JSON_NULL,      // Null
        JSON_BOOL,      // Bool
        JSON_INT,       // Integer
        JSON_REAL,      // Real
        JSON_STRING,    // String value
        JSON_KEY,       // Key value
        JSON_ARRAY,     // An array of UT_JSON_VALUE
        JSON_MAP,       // A map of keyword, UT_JSONValue object
    };

     UT_JSONValue();
     UT_JSONValue(const UT_JSONValue &v);
    ~UT_JSONValue();

    UT_JSONValue        &operator=(const UT_JSONValue &v)
                         {
                             copyFrom(v);
                             return *this;
                         }

    /// Read the next value from the parser and store it in this object
    /// @param parser   The parser
    /// @param is       If specified, data will be read from this stream.
    /// Otherwise, the stream associated with the parser will be used.
    bool         parseValue(UT_JSONParser &parser, UT_JSONIStream *is=0);

    /// Convenience method to parse using a UT_IStream.
    /// @see UT_JSONIStream.
    bool         parseValue(UT_JSONParser &parser, UT_IStream *is);


    /// Save the object the output stream
    bool                 save(UT_JSONWriter &os) const;

    /// Get the type of data stored in the object
    Type                 getType() const        { return myType; }

    /// Get the bool value.  Interprets integer/float as bool
    bool                 getB() const;
    /// Get the integer value.  Intereprets bool/real as integer
    /// @note Real values are cast to integer.
    int64                getI() const;
    /// Get the real value.  Interprets bool/int as reals.
    fpreal64             getF() const;
    /// Get the string value (may return a NULL pointer)
    const char          *getS() const;
    /// Return the string length (returns -1 if not a string)
    int64                getSLength() const;
    /// Get a key value
    const char          *getKey() const;
    /// Get the length of the key
    int64                getKeyLength() const;
    /// Get the array value (may return a NULL pointer)
    UT_JSONValueArray   *getArray() const;
    /// Get the map value (may return a NULL pointer)
    UT_JSONValueMap     *getMap() const;

    /// Extract a bool (returns false if type is invalid)
    bool                 import(bool &result) const;
    /// Extract an integer (returns false if type is invalid)
    bool                 import(int64 &result) const;
    /// Extract an float (returns false if type is invalid)
    bool                 import(fpreal64 &result) const;
    /// Extract a string @b or key (returns false if type is invalid)
    bool                 import(UT_WorkBuffer &result) const;
    /// Extract a tuple of integers from an JSON_Array.  If there aren't enough
    /// elements in the array, this method fails
    bool                 import(int64 *result, int size) const;
    /// Extract a tuple of floats from an JSON_Array.  If there aren't enough
    /// elements in the array, this method fails
    bool                 import(fpreal64 *result, int size) const;

    /// Returns whether the value can be interpreted as a number
    bool         isNumber() const
                 {
                    return  myType == JSON_REAL || myType == JSON_INT ||
                            myType == JSON_BOOL;
                 }

    /// Set value to a null
    void         setNull()      { clearValue(); }
    /// Set value to an bool
    void         setBool(bool v);
    /// Set value to an int
    void         setInt(int64 v);
    /// Set value to an int
    void         setReal(fpreal64 v);
    /// Set string.  If the length is not specified, the length of the string
    /// will be used.
    void         setString(const char *s, int64 length=-1)
                    { setStringType(s, length, JSON_STRING); }
    /// Set string.  If the length is not specified, the length of the string
    /// will be used.
    void         setKey(const char *s, int64 length=-1)
                    { setStringType(s, length, JSON_KEY); }
    /// Set value to the array
    void         setArray(UT_JSONValueArray *array);
    /// Set value to the map
    void         setMap(UT_JSONValueMap *map);

    /// Start building an array from scratch. @see appendArray
    void         startArray();
    /// Add an element to an array (returns false if operation fails)
    bool         appendArray(const UT_JSONValue &v);

    /// Start building a map from scratch . @see appendMap
    void         startMap();
    /// Add an element to a map (returns false if operation fails)
    bool         appendMap(const char *key, const UT_JSONValue &v);

    /// @{
    /// Build a uniform array of values
    bool         setUniformArray(int len, const int32 *data);
    bool         setUniformArray(int len, const int64 *data);
    bool         setUniformArray(int len, const fpreal32 *data);
    bool         setUniformArray(int len, const fpreal64 *data);
    /// @}

    /// Used internally by UT_JSONValueMap
    int                  getMapIndex() const    { return myMapIndex; }
    /// Used internally bu UT_JSONValueMap
    void                 setMapIndex(int i)     { myMapIndex = i; }

private:
    void                 clearValue();
    void                 copyFrom(const UT_JSONValue &s);
    void                 setStringType(const char *s, int64 l, Type t);
    union {
        bool             myBool;
        int64            myInt;
        fpreal64         myReal;
    } myData;
    union {
        // NOTE:  Keep the pointers and scalars separate.  The string is stored
        // as a pointer and a length so that null characters may be contained.
        char                    *myString;
        UT_JSONValueArray       *myArray;
        UT_JSONValueMap         *myMap;
    } myPointers;
    int                  myMapIndex;    // Location in a map
    Type                 myType;
};

#endif

---