199 lines
9.5 KiB
C++
199 lines
9.5 KiB
C++
// -*- C++ -*-
|
|
|
|
|
|
namespace Hurricane {
|
|
|
|
//! \addtogroup JsonSupport
|
|
//! \{
|
|
|
|
|
|
/*! \class JsonObject
|
|
* \brief Support for JSON export.
|
|
*
|
|
*/
|
|
|
|
//! \function JsonObject::JsonObject ( unsigned long flags );
|
|
//! \param flags Flags sets by derived classes.
|
|
//!
|
|
//! Base object to be used by all JSON parsers. Provides
|
|
//! helpers functions. Store three separated lists of
|
|
//! requirements/attributes needes to build the object.
|
|
//! - \c stackeds : thoses are \b not attributes of the
|
|
//! current object, but other objects that are expected
|
|
//! to be already in the stack. They are needed to build the
|
|
//! current object. Their key must start with a \c '.'
|
|
//! character.
|
|
//! - \c attributes : the simple attributes of the object.
|
|
//! Their key must start with a \c '_'.
|
|
//! - \c collections : any container, collection or whatever
|
|
//! set of other objects part of the current object.
|
|
//! Their key must start with a \c '+' character.
|
|
//!
|
|
//! For adding a requirement/attribute, see JsonObject::add().
|
|
|
|
//! \function string JsonObject::getTypeName () const;
|
|
//! \Return The typename of the concrete object, that is, the value
|
|
//! of the \c @typename key of the JSON object.
|
|
|
|
//! \function string JsonObject::getStackName () const;
|
|
//! \Return The key with which the DataBase object will be pushed on
|
|
//! the parser stack.
|
|
//!
|
|
//! If the current object is associated to an attribute (that
|
|
//! is, a key in JSON), then the \c name attribute of the JsonObject
|
|
//! should have been set, and it will be returned here.
|
|
//!
|
|
//! If the \c name attribute has not been set (for example,
|
|
//! because we are in an array). Then the typename (JsonObject::getTypeName()),
|
|
//! prefixed by a \c '.' character will be returned.
|
|
//!
|
|
//! If the JsonObject is, for instance, a JsonBox (typename: \c "Box") :
|
|
//! - If \c name is set to \c "_abutmentBox", the box will be stacked
|
|
//! with that key.
|
|
//! - If \c name is \b not set, then the key will be \c ".Box".
|
|
|
|
//! \function JsonObject* JsonObject::setFlags ( unsigned long mask );
|
|
//! \param mask Flag(s) to be raised.
|
|
//! \return The current object.
|
|
|
|
//! \function JsonObject* JsonObject::resetFlags ( unsigned long mask );
|
|
//! \param mask Flag(s) to be lowered.
|
|
//! \return The current object.
|
|
|
|
//! \function bool JsonObject::issetFlags ( unsigned long mask ) const;
|
|
//! \param mask The combination of flags to be checked.
|
|
//! \return \true if \b all the flags given in \c mask are sets.
|
|
|
|
//! \function bool JsonObject::check ( JsonStack& stack, string fname ) const;
|
|
//! \param stack Where the objects already parsed are stored.
|
|
//! \param fname The function name on behalf of which the check is
|
|
//! performed.
|
|
//! \return \true if the check is successful.
|
|
//!
|
|
//! Check that the \c stack actually contains all the objects (i.e. attributes)
|
|
//! needed to build the current object. The list of \e attributes is built
|
|
//! using the JsonObject::add() function. If an attribute is missing, a warning
|
|
//! is issued, but the parser will try to continue.
|
|
|
|
//! \function bool JsonObject::has ( const string& key ) const;
|
|
//! \param key The key name to search for.
|
|
//! \return \true if the object possess such a key.
|
|
|
|
//! \function void JsonObject::add ( const string& key, type_index tid );
|
|
//! \param key The requirement/attribute to add.
|
|
//! \param tid The type index of the attribute.
|
|
//!
|
|
//! Adds a new requirement or attribute to the object. The first character
|
|
//! of the key tells which kind it is:
|
|
//! - \c '.' : a requirement (not part of the object) that must be present
|
|
//! in the stack.
|
|
//! - \c '_' : a simple attribute of the object.
|
|
//! - \c '+' : belongs to a collection or container.
|
|
//!
|
|
//! A more detailed description could be found in JsonObject::JsonObject().
|
|
|
|
//! \function void JsonObject::remove ( const string& key );
|
|
//! \param key The key of the requirement/attribute to remove.
|
|
//!
|
|
//! Removes an attribute from the current object.
|
|
|
|
//! \function T JsonObject::get ( JsonStack& stack, const string& key ) const;
|
|
//! \param stack The object stack of the parser.
|
|
//! \param key The key of the requested object.
|
|
//! \return The first object associated with \c key, starting <em>from the top</em>
|
|
//! of the stack.
|
|
//!
|
|
//! Retrieve requirements or attributes from the parser stack.
|
|
//! - If no element with a corresponding key is found, an empty element
|
|
//! of type \c T is returned (by calling the default \c T constructor).
|
|
//! - If an element matching the key is found, \b but it's type do not
|
|
//! match \c T, an exception from \c any_cast<> will be thrown.
|
|
|
|
//! \function void JsonObject::copyAttrs ( const JsonObject* other, bool reset=false );
|
|
//! \param other The object from which to copy attributes.
|
|
//! \param reset Whether to keep or erase the original attributes of the object.
|
|
//!
|
|
//! Copy the attributes from \c other into the current object. \b Only the
|
|
//! \b attributes are copied. Neither the requirements, nor the collections.
|
|
//! By default, the attributes are added to the existing one of the object,
|
|
//! but if \c reset is \true, the original ones will be suppresseds.
|
|
|
|
//! \function void JsonObject::clear ();
|
|
//! Removes all requirements/attributes/collections of the object.
|
|
//! Also unbind it from any generated DataBase object.
|
|
|
|
//! \function string JsonObject::getName () const;
|
|
//! \Return The name of the whole object as attribute.
|
|
//!
|
|
//! During the parsing of the JSON structure, excepted when in an array,
|
|
//! an object is associated with a key. This is the string returned by
|
|
//! this function. It is called \c getName() instead of \c getKey() to
|
|
//! avoid confusing with the attributes keys.
|
|
|
|
//! \function void JsonObject::setName ( const string& name );
|
|
//! \param name Set the key associated to this object.
|
|
//!
|
|
//! See JsonObject::getName() for the meaning of the name (key).
|
|
|
|
//! \function T& JsonObject::getObject () const;
|
|
//! \Return The associated DataBase object.
|
|
//!
|
|
//! Once all the attributes have been gathered, the creation of the
|
|
//! DataBase object is triggered by calling JsonObject::toData().
|
|
//! We keep track of that DataBase object by storing it (or a pointer
|
|
//! to it) in an \c boost::any field of the JsonObject.
|
|
|
|
//! \function void JsonObject::setObject ( T );
|
|
//! \param T The DataBase object.
|
|
//!
|
|
//! Associate the constructed DataBase object \c T to the JSON
|
|
//! object (for later access).
|
|
|
|
//! \function bool JsonObject::isBound () const;
|
|
//! \Return \true if a DataBase object is associated to the JSON object
|
|
//! (see JsonObject::setObject()).
|
|
|
|
//! \function JsonObject* JsonObject::clone ( unsigned long flags ) const;
|
|
//! \Return a new \b empty object <em>of the same dynamic type</em>
|
|
//! as the source one.
|
|
//!
|
|
//! This is not a true clone operation in the sense that the datas
|
|
//! of the original object are not copied. The cloning is about the
|
|
//! type, and is the result of a call to the \c new operator.
|
|
//!
|
|
//! \Important This method must be overloaded in each concrete derived class.
|
|
|
|
//! \function void JsonObject::toData ( JsonStack& stack );
|
|
//! \param The parser object stack.
|
|
//!
|
|
//! \Important This method must be overloaded in each concrete derived class.
|
|
//!
|
|
//! Creates the DataBase object. The requirements and attributes
|
|
//! must be on top of the stack, they are popped, the DataBase object
|
|
//! is created from them and the result is then pushed back.
|
|
|
|
//! \function unsigned int JsonObject::presetId ( JsonStack& stack );
|
|
//! \param The parser object stack.
|
|
//! \Return the <em>next id</em> that has been set.
|
|
//!
|
|
//! \Remark This is a helper for JsonStack::toData().
|
|
//!
|
|
//! In blob mode, the DataBase must be restored <em>as is</em>,
|
|
//! including the \c ids of all the Entities (see Entity).
|
|
//! This function read from the stack the \c _id attribute
|
|
//! and sets it so that the next Entity created will use it.
|
|
|
|
//! \function void JsonObject::update ( JsonStack& stack, T hobject );
|
|
//! \param The parser object stack.
|
|
//! \param hobject the newly created DataBase object.
|
|
//!
|
|
//! \Remark This is a helper for JsonStack::toData().
|
|
//!
|
|
//! Pop the attributes from the stack. Push the newly created
|
|
//! object and bind it to the JsonObject.
|
|
|
|
|
|
//! \}
|
|
|
|
}
|