UT/UT_Options.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:
 *      Edward Lam
 *      Side Effects
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 *
 * NAME:        UT_Options.h (C++, Utility Library)
 *
 * COMMENTS:    This is a smaller, faster, more type-safe version of
 *              UT_OptionFile. The reason UT_OptionFile was not simply
 *              re-implemented is that when saving and loading UT_OptionFiles,
 *              no information about the type of each option is saved. This
 *              implementation writes out the type of each data item.
 *
 */

#ifndef _UT_OPTIONS_H_
#define _UT_OPTIONS_H_

#include "UT_API.h"
#include <iostream.h>
#include "UT_SmallObject.h"
#include "UT_PtrArraySorted.h"
#include "UT_SymbolTable.h"
#include "UT_DeepString.h"
#include <string>

class UT_WorkBuffer;
class UT_String;

#include "UT_VectorTypes.h"

class UT_OptionEntry;
class UT_JSONParser;
class UT_JSONWriter;
class UT_JSONIStream;

// NOTE: The values of UT_OptionType are saved to disk, thus we should NOT 
//       reorder these options if we want to maintain compatibility with older
//       saved options.
typedef enum {
    UT_OPTION_INVALID = -1,
    UT_OPTION_INT = 0,
    UT_OPTION_BOOL = 1,
    UT_OPTION_FPREAL = 2,
    UT_OPTION_STRING = 3,
    UT_OPTION_VECTOR2 = 4,
    UT_OPTION_VECTOR3 = 5,
    UT_OPTION_VECTOR4 = 6,
    UT_OPTION_QUATERNION = 7,
    UT_OPTION_MATRIX3 = 8,
    UT_OPTION_MATRIX4 = 9,
    UT_OPTION_UV = 10,
    UT_OPTION_UVW = 11,
    UT_OPTION_STRINGRAW = 12,   // used by getPyOptionString
    UT_OPTION_NUM_TYPES = 13
} UT_OptionType;

class UT_API UT_Options
{
public:
    UT_Options();
    UT_Options(const UT_Options &src);
    virtual ~UT_Options();

    // This function does not call optionChanged.
    void clear();

    // only returns false if the file encounters an error. true is returned on
    // success or if the file didn't exist.
    // The load methods can handle files saved either with this save
    // or with saveAsJSON.  saveAsJSON is preferable as it handles 64bit
    // floats and ints, but can't be read before H10.5
    bool load(const char *filename);
    bool save(const char *filename) const;
    bool load(const char *filename, UT_IStream &is);
    bool save(const char *filename, ostream &os) const;
    bool saveAsJSON(const char *filename) const;
    bool saveAsJSON(const char *filename, ostream &os) const;

    // Remove an option.
    void                 removeOption(const char *name);
    // Get the string representation of any of our options.  Note that, if
    // the value contains binary data with null characters, you can't determine
    // the length of the data with UT_String version of these methods.
    void                 getOptionString(const char *name,
                                         UT_WorkBuffer &result) const;
    void                 getOptionString(const char *name,
                                         UT_String &result) const;
    static void          getOptionString(const UT_OptionEntry *option,
                                         UT_WorkBuffer &result);
    static void          getOptionString(const UT_OptionEntry *option,
                                         UT_String &result);

    // Append the python dictionary representation of ALL our options to the
    // buffer
    bool                 appendPyDictionary(UT_WorkBuffer &result) const;
    // Get the python representation of any of our options.  Note that the
    // UT_WorkBuffer versions can contain arbitrary binary data, but the
    // UT_String versions cannot (since they cannot contain null characters).
    bool                 getPyOptionString(const char *name,
                                        UT_WorkBuffer &result) const;
    bool                 getPyOptionString(const char *name,
                                        UT_String &result) const;
    // Get the python string represention of any option.
    static bool          getPyOptionString(const UT_OptionEntry *option,
                                        UT_WorkBuffer &result);
    static bool          getPyOptionString(const UT_OptionEntry *option,
                                        UT_String &result);

    /// Save a UT_Options to JSON format using UT_JSONWriter
    bool                 save(UT_JSONWriter &w) const;

    /// Load a UT_Options from a JSON parser.
    /// \param parser           Parser
    /// \param clear_self       Clear existing map before loading
    ///   If true and the first object in the JSON stream is not a map object,
    ///   then the parser will fail (with an error).  Otherwise a warning will
    ///   be added and the object will be skipped.
    /// \param is   If this is specified, then data will be read from that
    ///   stream rather than the stream associated with the parser.
    bool                 load(UT_JSONParser &parser,
                                bool clear_self,
                                UT_JSONIStream *is = 0);
    /// Convenience method to parse with a UT_IStream
    bool                 load(UT_JSONParser &parser,
                                bool clear_self,
                                UT_IStream *is);

    // Functions for accessing the options by name.
    bool                 hasOption(const char *name) const;
    UT_OptionType        getOptionType(const char *name) const;
    const UT_OptionEntry*getOptionEntry(const char *name) const;

    // Functions for accessing all options sequentially.
    int                  getNumOptions() const;
    const char          *getOptionName(int optionnum) const;
    UT_OptionType        getOptionType(int optionnum) const;
    const UT_OptionEntry*getOptionEntry(int optionnum) const;

    // Functions for accessing specific option values.
    int64                getOptionI(const char *name) const;
    bool                 getOptionB(const char *name) const;
    fpreal64             getOptionF(const char *name) const;
    const UT_Vector2D    getOptionV2(const char *name) const;
    const UT_Vector3D    getOptionV3(const char *name) const;
    const UT_Vector4D    getOptionV4(const char *name) const;
    const UT_QuaternionD getOptionQ(const char *name) const;
    const UT_Matrix3D    getOptionM3(const char *name) const;
    const UT_Matrix4D    getOptionM4(const char *name) const;
    const UT_Vector2D    getOptionUV(const char *name) const;
    const UT_Vector3D    getOptionUVW(const char *name) const;
    // Note that, if the string value contains binary data with null
    // characters, the UT_String version of getOptionS will not be able to
    // tell you the length of the data, since UT_String doesn't store the
    // length.
    std::string          getOptionS(const char *name) const;
    void                 getOptionS(const char *name, std::string &value) const;
    void                 getOptionS(const char *name, UT_String &value) const;
    void                 getOptionS(
                            const char *name, UT_WorkBuffer &value) const;

    // Returns a valid number if this option is a float or an int.
    // In the case of an int, it is converted to a float.
    fpreal64             getOptionNum(const char *name) const;

    // Functions for accessing option values.  These methods will perform some
    // minimal "casting".
    //  importOption(... bool &value)   - Tests integers and string options
    //  importOption(... fpreal &value) - Evaluates integer/bool options
    //  importOption(... UT_Vector2 &)  - Evaluates Vector2 or UV
    //  importOption(... UT_Vector3 &)  - Evaluates Vector3 or UVW
    //  
    bool         importOption(const char *name, int &value) const;
    bool         importOption(const char *name, int64 &value) const;
    bool         importOption(const char *name, bool &value) const;
    bool         importOption(const char *name, fpreal32 &value) const;
    bool         importOption(const char *name, fpreal64 &value) const;
    bool         importOption(const char *name, std::string &value) const;
    bool         importOption(const char *name, UT_String &value) const;
    bool         importOption(const char *name, UT_Vector2F &value) const;
    bool         importOption(const char *name, UT_Vector3F &value) const;
    bool         importOption(const char *name, UT_Vector4F &value) const;
    bool         importOption(const char *name, UT_QuaternionF &value) const;
    bool         importOption(const char *name, UT_Matrix3F &value) const;
    bool         importOption(const char *name, UT_Matrix4F &value) const;
    bool         importOption(const char *name, UT_Vector2D &value) const;
    bool         importOption(const char *name, UT_Vector3D &value) const;
    bool         importOption(const char *name, UT_Vector4D &value) const;
    bool         importOption(const char *name, UT_QuaternionD &value) const;
    bool         importOption(const char *name, UT_Matrix3D &value) const;
    bool         importOption(const char *name, UT_Matrix4D &value) const;

    // Generic import which handles arbitrary length int/float data
    bool         importOption(const char *name, UT_IntArray &value) const;
    bool         importOption(const char *name, UT_FloatArray &value) const;

    // All these functions cause optionChanged to be called.
    void                 setOptionI(const char *name, int64 value);
    void                 setOptionB(const char *name, bool value);
    void                 setOptionF(const char *name, fpreal64 value);
    // Note that you can store binary data (that can contain null characters
    // or that isn't null-terminated) in a string option by passing in a
    // std::string or a size.
    void                 setOptionS(
                            const char *name, const char *value, int64 size=-1);
    void                 setOptionS(const char *name, const std::string &value);
    // setOptionSRaw() is the same as setOptionS() instead of it being
    // additionally tagged as a "raw" string so that getPyOptionString() and
    // appendPyDictionary() won't add quotes around the value. To retrieve its
    // value, use getOptionS().
    void                 setOptionSRaw(
                            const char *name, const char *value, int64 size=-1);
    void                 setOptionSRaw(
                            const char *name, const std::string &value);
    void                 setOptionV2(const char *name,
                                     const UT_Vector2F &value);
    void                 setOptionV2(const char *name,
                                     const UT_Vector2D &value);
    void                 setOptionV2(const char *name,
                                        fpreal64 x, fpreal64 y);
    void                 setOptionV3(const char *name,
                                     const UT_Vector3F &value);
    void                 setOptionV3(const char *name,
                                     const UT_Vector3D &value);
    void                 setOptionV3(const char *name,
                                        fpreal64 x, fpreal64 y, fpreal64 z);
    void                 setOptionV4(const char *name,
                                     const UT_Vector4F &value);
    void                 setOptionV4(const char *name,
                                     const UT_Vector4D &value);
    void                 setOptionV4(const char *name,
                                        fpreal64 x, fpreal64 y, fpreal64 z, fpreal64 w);
    void                 setOptionQ(const char *name,
                                    const UT_QuaternionF &value);
    void                 setOptionQ(const char *name,
                                    const UT_QuaternionD &value);
    void                 setOptionM3(const char *name,
                                     const UT_Matrix3F &value);
    void                 setOptionM3(const char *name,
                                     const UT_Matrix3D &value);
    void                 setOptionM4(const char *name,
                                     const UT_Matrix4F &value);
    void                 setOptionM4(const char *name,
                                     const UT_Matrix4D &value);
    void                 setOptionUV(const char *name,
                                     const UT_Vector2F &value);
    void                 setOptionUV(const char *name,
                                     const UT_Vector2D &value);
    void                 setOptionUVW(const char *name,
                                      const UT_Vector3F &value);
    void                 setOptionUVW(const char *name,
                                      const UT_Vector3D &value);

    /// Get a hash code for the options
    unsigned             hash() const;

    /// Comparison operator
    bool                 operator==(const UT_Options &src) const;
    bool                 operator!=(const UT_Options &src) const
                            { return !(*this == src); }

    /// Assignment operator
    const UT_Options    &operator=(const UT_Options &src);
    void                 merge(const UT_Options &src);
    int64                getMemoryUsage() const;

    static UT_OptionType getOptionTypeFromString(const char *optiontypestr);
    static const char   *getStringFromOptionType(UT_OptionType optiontype);

protected:
    const std::string   *findOptionS(const char *name) const;
    void                 addError(const char *filename, int linecount,
                                  const char *error_str) const;
    void                 setOption(const char *name, UT_OptionEntry *value);
    virtual void         optionChanged(const char *name);

    static int           compareStrings(const char * const *str1,
                                        const char * const *str2);
    static const char   *getStringReference(const char *symbol);
    /// Save a single option to a JSON stream.  This is saved with the schema
    /// \code
    /// {
    ///     "name":"UT_OptionEntry",
    ///     "type":"object",
    ///     "properties": {
    ///        "type":{
    ///           "type":"string",
    ///           "enum":{ UT_Options::getStringFromOptionType() },
    ///        },
    ///        "value":{
    ///            "type":["bool", "integer", "float", "string", "array"],
    ///            "items":{"type":"float"},
    ///            "description":"Basic type or an array.
    ///                           Arrays must be 2,3,4,9 or 16 floats.
    ///                           Data should match given type",
    ///        },
    ///     },
    /// }
    /// \endcode
    static bool          saveJSON(UT_JSONWriter &w, const UT_OptionEntry *opt);

    /// Compute hash/equivalence for a given option entry
    static unsigned      hash(const UT_OptionEntry *option);
    static unsigned      isEqual(const UT_OptionEntry *o1,
                                 const UT_OptionEntry *o2,
                                 fpreal64 tolerance=0);


    UT_PtrArraySorted<const char *>      myOptionNames;
    UT_PtrArray<UT_OptionEntry *>        myOptionValues;
    bool                                 mySendOptionChanges;
};

// The base class for data held by the UT_Options.
class UT_API UT_OptionEntry : public UT_SmallObject<UT_OptionEntry,
                                        UT_SMALLOBJECT_CLEANPAGES_DEFAULT,
                                        UT_SMALLOBJECT_PAGESIZE_DEFAULT,
                                        UT_SMALLOBJECT_THREADSAFE_ON>
{
public:
                                 UT_OptionEntry()
                                 { }
    virtual                     ~UT_OptionEntry()
                                 { }

    virtual UT_OptionType        getType() const = 0;
    virtual UT_OptionEntry      *clone() const = 0;
};

// A templatized version of the class above for holding specific data types.
template<class T, UT_OptionType ID>
class UT_OptionEntryImpl : public UT_OptionEntry
{
public:
                                 UT_OptionEntryImpl(const T &value)
                                     : myValue(value)
                                 { }
    virtual                     ~UT_OptionEntryImpl()
                                 { }

    const T                     &getValue() const
                                 { return myValue; }
    virtual UT_OptionType        getType() const
                                 { return ID; }
    virtual UT_OptionEntry      *clone() const
                                 { return new UT_OptionEntryImpl(myValue); }

private:
    T                            myValue;
};

typedef UT_OptionEntryImpl<int64, UT_OPTION_INT> UT_OptionInt;
typedef UT_OptionEntryImpl<bool, UT_OPTION_BOOL> UT_OptionBool;
typedef UT_OptionEntryImpl<fpreal64, UT_OPTION_FPREAL> UT_OptionFpreal;
typedef UT_OptionEntryImpl<std::string, UT_OPTION_STRING> UT_OptionString;
typedef UT_OptionEntryImpl<UT_Vector2D, UT_OPTION_VECTOR2> UT_OptionVector2;
typedef UT_OptionEntryImpl<UT_Vector3D, UT_OPTION_VECTOR3> UT_OptionVector3;
typedef UT_OptionEntryImpl<UT_Vector4D, UT_OPTION_VECTOR4> UT_OptionVector4;
typedef UT_OptionEntryImpl<UT_QuaternionD, UT_OPTION_QUATERNION> UT_OptionQuaternion;
typedef UT_OptionEntryImpl<UT_Matrix3D, UT_OPTION_MATRIX3> UT_OptionMatrix3;
typedef UT_OptionEntryImpl<UT_Matrix4D, UT_OPTION_MATRIX4> UT_OptionMatrix4;
typedef UT_OptionEntryImpl<UT_Vector2D, UT_OPTION_UV> UT_OptionUV;
typedef UT_OptionEntryImpl<UT_Vector3D, UT_OPTION_UVW> UT_OptionUVW;

#endif

---