API: Definitions, Sources and Factories

#Overview Scriptable objects only exist at runtime. They are not C++ data types and may not be directly declared and initialized in your client code. Instead we create an object source and pass that to the object factory which returns us the object.

All object sources are derived from ScriptObjectDefinition and ScriptObjectSource, these two base classes allow the object factory to query the number of fields, their names and types and ultimately create the new object.

##Object Definitions ScriptObjectDefinition exposes the fundamental methods to determine the number of fields, their names and their types in the source object. The class does not expose object instance values, it is used solely to infer the object signature based on its name and type components.

In addition the class can calculate a hash based on the field names and types which can be used by libscriptobject to look up metadata associated with the object (e.g. common keys).

The class is defined as follows:

class ScriptObjectDefinition {
public:
    virtual unsigned count() const = 0;
    virtual ScriptObjectType type(int index) const = 0;
    virtual const char* name(int index) const = 0;    
    virtual unsigned length(int index) const = 0;
    
    void CalculateHash(ScriptObjectHash digest) const;
};

count returns the number of fields in the object.
type returns the type of the field at the supplied index.
name returns the null terminated name of the field and length the number of characters occupied by the name.

##Object Sources ScriptObjectSource, derived from ScriptObjectDefinition, provides methods to query the source field values which will ultimately be assigned to the new object in the factory.

The class is defined as follows:

class ScriptObjectSource : public ScriptObjectDefinition {
public:
    virtual bool getBoolean(int index) const = 0;
    virtual std::int32_t getInt32(int index) const = 0;
    virtual std::uint32_t getUInt32(int index) const = 0;
    virtual std::int64_t getInt64(int index) const = 0;
    virtual std::uint64_t getUInt64(int index) const = 0;
    virtual double getDouble(int index) const = 0;
    virtual const char* getString(int index) const = 0;
    virtual int getStringLength(int index) const = 0;
    virtual const ScriptObjectPtr getObject(int index) const = 0;
    virtual const ScriptArrayPtr getArray(int index) const = 0;
};

The methods in this class exclusively return values associated with fields in the source object. When an object derived from ScriptObjectSource is passed to the object factory the new object is created as follows:

the factory asks for the number of fields in the source object
the factory enumerates each field, asking for its type, name and value
the factory adds the field to the new script object
when all fields have been added the factory returns the new object to the caller

When child objects are encountered in the object definition they are recursively passed to the factory which assigns the new child object instance on return. The same mechanism is used for arrays.

##Object Factories The only mechanism offered by libscriptobject to create scriptable objects is the object factory. It is defined as follows:

class ScriptObjectFactory final {
public:
    static ScriptObjectPtr CreateObject(const ScriptObjectSource& source, bool useKeyCache = true);
    static unsigned getCount();    
    static unsigned long getTotalBytesAllocated();
};