#include <client_api.hpp>
Public Types | |
typedef NodeType | node_type |
node_type is the type used to store/load a Serializable object's data. | |
typedef s11n::node_traits < node_type > | node_traits |
The s11n::node_traits type for node_type. | |
typedef s11n::io::data_node_serializer < node_type > | serializer_interface |
This is the base-most type of the serializers used by s11nlite clients. | |
Public Member Functions | |
client_api () | |
client_api (const std::string &default_serializer_class) | |
virtual | ~client_api () |
serializer_interface * | create_serializer () |
Returns create_serialize( serializer_class() ). | |
virtual serializer_interface * | create_serializer (const std::string &classname) |
Returns a new instance of the given serializer class, or 0 if one could not be loaded. | |
void | serializer_class (const std::string &classname) |
Sets the current Serializer class used by s11nlite's create_serializer(). | |
std::string | serializer_class () const |
Gets the name of the current Serializer type. | |
virtual bool | provides_serializer (const std::string &key) |
Returns true if key can be used to create a Serializer object via a call to serializer_class(). | |
template<typename SerializableType> | |
bool | serialize (node_type &dest, const SerializableType &src) const |
See s11n::serialize(). | |
template<typename SerializableType> | |
bool | serialize_subnode (node_type &dest, const std::string &subnodename, const SerializableType &src) const |
See s11n::serialize_subnode(). | |
virtual bool | save (const node_type &src, std::ostream &dest) |
Saves the given node to the given ostream using the default serializer type. | |
virtual bool | save (const node_type &src, const std::string &filename) |
Saves the given node to the given filename using the default serializer type. | |
template<typename SerializableType> | |
bool | save (const SerializableType &src, std::ostream &dest) |
Saves the given Serializable to the given ostream using the default serializer type. | |
template<typename SerializableType> | |
bool | save (const SerializableType &src, const std::string &dest) |
Saves the given Serializable to the given filename using the default serializer type. | |
virtual node_type * | load_node (const std::string &src) |
Tries to load a node from the given filename. | |
virtual node_type * | load_node (std::istream &src) |
Tries to load a node from the given input stream. | |
template<typename SerializableType> | |
SerializableType * | deserialize (const node_type &src) const |
Returns s11n::deserialize<node_type,SerializableType>(src). | |
template<typename DeserializableT> | |
bool | deserialize (const node_type &src, DeserializableT &target) const |
See s11n::deserialize(). | |
template<typename DeserializableT> | |
bool | deserialize_subnode (const node_type &src, const std::string &subnodename, DeserializableT &target) const |
See s11n::deserialize_subnode(). | |
template<typename DeserializableT> | |
DeserializableT * | deserialize_subnode (const node_type &src, const std::string &subnodename) const |
See s11n::deserialize_subnode(). | |
template<typename SerializableType> | |
SerializableType * | load_serializable (std::istream &src) |
Tries to load a data_node from src, then deserialize that to a SerializableType. | |
template<typename SerializableType> | |
SerializableType * | load_serializable (const std::string &src) |
Overloaded form which takes a file name. | |
template<typename SerializableType> | |
SerializableType * | clone (const SerializableType &tocp) const |
See s11n::s11n_clone(). | |
template<typename Type1, typename Type2> | |
bool | cast (const Type1 &t1, Type2 &t2) const |
See s11n::s11n_cast(). | |
Static Public Member Functions | |
static client_api < node_type > & | instance () |
Returns a shared instance of this class. |
The intention of this class is for projects to have easy access to an s11nlite-like interface for their own node types. s11nlite, as of s11n 1.2, will be based off of this type.
Another use of this class is in conjunction with s11n::fac::instance_hook: clients may specialize that type to make this type's instance() function return a custom client_api object. The intention of this feature is to allow clients to extend the s11nlite interface "from inside" while allowing client code to keep using the s11nlite interface. This allows, amongst other things, extending s11nlite to support special i/o channels (as provided, e.g., by pclasses.com's libraries) without actually touching s11nlite. See http://s11n.net/ps11n/ for where this is headed...
Particularly observant users might notice that many of this type's functions which "probably should be" const are not const. This is because subclasses are encouraged to add features behind the basic API, and many would not be practical without a non-const object. As an example, a subclass might want to do DLL lookups and may need to modify internal tables when it does so. Template functions which can be made const are const. This would appear to be inconsistent, but it is in fact me trying to make up for more of the API not being const.
The NodeType parameterized type must be compatible with the s11n's "Data Node" type conventions (e.g., s11n::s11n_node).
Clients may notice that not much of this API is virtual. That's not because i'm anal, but because most of the API is template functions, and those can't be virual. There is a theoretical solution, for those wanting more control: subclass this type with another template type: serializable_api<SerializableType>. Then you can add virtual functions which take the place of the templated members. Not sure if overloading rules will let you get away with it, but it sounds halfway reasonable.
TODOs:
Definition at line 74 of file client_api.hpp.
typedef NodeType s11nlite::client_api< NodeType >::node_type |
node_type is the type used to store/load a Serializable object's data.
Definition at line 97 of file client_api.hpp.
typedef s11n::node_traits<node_type> s11nlite::client_api< NodeType >::node_traits |
typedef s11n::io::data_node_serializer<node_type> s11nlite::client_api< NodeType >::serializer_interface |
This is the base-most type of the serializers used by s11nlite clients.
Definition at line 106 of file client_api.hpp.
s11nlite::client_api< NodeType >::client_api | ( | ) | [inline] |
Definition at line 81 of file client_api.hpp.
s11nlite::client_api< NodeType >::client_api | ( | const std::string & | default_serializer_class | ) | [inline, explicit] |
Definition at line 85 of file client_api.hpp.
virtual s11nlite::client_api< NodeType >::~client_api | ( | ) | [inline, virtual] |
Definition at line 89 of file client_api.hpp.
serializer_interface* s11nlite::client_api< NodeType >::create_serializer | ( | ) | [inline] |
Returns create_serialize( serializer_class() ).
The caller owns the returned pointer.
Definition at line 113 of file client_api.hpp.
virtual serializer_interface* s11nlite::client_api< NodeType >::create_serializer | ( | const std::string & | classname | ) | [inline, virtual] |
Returns a new instance of the given serializer class, or 0 if one could not be loaded.
classname must represent a subtype of serializer_interface.
The caller owns the returned pointer.
You can also pass a serializer's cookie here, and that should return the same thing as it's class name would.
The internally-supported serializers all register a "friendly form" of the name, an alias registered with their classloader. Passing either this name or the cookie of the Serializer should return the same thing as the classname itself would.
Subclasses may do, e.g., lookups for externally-linked serializers.
Definition at line 138 of file client_api.hpp.
void s11nlite::client_api< NodeType >::serializer_class | ( | const std::string & | classname | ) | [inline] |
Sets the current Serializer class used by s11nlite's create_serializer().
Pass it a class name, or one of the convenience names, e.g.:
compact, funtxt, funxml, simplexml, parens, wesnoth, and expat (if your s11n was built with it).
You may use provides_serializer() to check for the existence of a class. This function does no validation of classname: this is delayed until save/load-time, to allow for DLL lookups during the normal classloading process (as opposed to duplicating that check here).
Definition at line 159 of file client_api.hpp.
std::string s11nlite::client_api< NodeType >::serializer_class | ( | ) | const [inline] |
virtual bool s11nlite::client_api< NodeType >::provides_serializer | ( | const std::string & | key | ) | [inline, virtual] |
Returns true if key can be used to create a Serializer object via a call to serializer_class().
Subclasses may do additional work here, like look up DLLs, which is why the function is not const.
Definition at line 179 of file client_api.hpp.
References s11nlite::instance().
bool s11nlite::client_api< NodeType >::serialize | ( | node_type & | dest, | |
const SerializableType & | src | |||
) | const [inline] |
See s11n::serialize().
Definition at line 190 of file client_api.hpp.
Referenced by s11nlite::client_api< NodeType >::save().
bool s11nlite::client_api< NodeType >::serialize_subnode | ( | node_type & | dest, | |
const std::string & | subnodename, | |||
const SerializableType & | src | |||
) | const [inline] |
See s11n::serialize_subnode().
Definition at line 199 of file client_api.hpp.
References s11n::node_traits< NodeT >::children(), and s11n::node_traits< NodeT >::create().
virtual bool s11nlite::client_api< NodeType >::save | ( | const node_type & | src, | |
std::ostream & | dest | |||
) | [inline, virtual] |
Saves the given node to the given ostream using the default serializer type.
Returns true on success, false on error.
ONLY use this for saving root nodes!
Definition at line 226 of file client_api.hpp.
Referenced by s11nlite::client_api< NodeType >::save().
virtual bool s11nlite::client_api< NodeType >::save | ( | const node_type & | src, | |
const std::string & | filename | |||
) | [inline, virtual] |
Saves the given node to the given filename using the default serializer type.
Returns true on success, false on error.
ONLY use this for saving root nodes!
Subclasses are free to interpret the filename however they like, e.g., as a URL or database record name.
Definition at line 246 of file client_api.hpp.
bool s11nlite::client_api< NodeType >::save | ( | const SerializableType & | src, | |
std::ostream & | dest | |||
) | [inline] |
Saves the given Serializable to the given ostream using the default serializer type.
Returns true on success, false on error.
ONLY use this for saving root nodes!
Subclassers: this function serializes src to a node and then calls save(node,dest).
Definition at line 277 of file client_api.hpp.
References s11nlite::client_api< NodeType >::save(), and s11nlite::client_api< NodeType >::serialize().
bool s11nlite::client_api< NodeType >::save | ( | const SerializableType & | src, | |
const std::string & | dest | |||
) | [inline] |
Saves the given Serializable to the given filename using the default serializer type.
Returns true on success, false on error.
ONLY use this for saving root nodes!
Subclassers: this function serializes src to a node and then calls save(node,dest).
Definition at line 297 of file client_api.hpp.
References s11nlite::client_api< NodeType >::save(), and s11nlite::client_api< NodeType >::serialize().
virtual node_type* s11nlite::client_api< NodeType >::load_node | ( | const std::string & | src | ) | [inline, virtual] |
Tries to load a node from the given filename.
The caller owns the returned pointer.
Subclasses are free to interpret the filename however they like, e.g., as a URL or database record name.
Definition at line 319 of file client_api.hpp.
virtual node_type* s11nlite::client_api< NodeType >::load_node | ( | std::istream & | src | ) | [inline, virtual] |
Tries to load a node from the given input stream.
The caller owns the returned pointer, which may be 0.
Only usable for loading ROOT nodes.
Definition at line 333 of file client_api.hpp.
SerializableType* s11nlite::client_api< NodeType >::deserialize | ( | const node_type & | src | ) | const [inline] |
Returns s11n::deserialize<node_type,SerializableType>(src).
Caller owns the returned pointer, which may be 0.
Note that this function is non-const because deserialization may indirectly classload other types or affect this object.
See the one-argument variant of s11n::deserialize() for IMPORTANT error-handling considerations for this function.
Definition at line 352 of file client_api.hpp.
bool s11nlite::client_api< NodeType >::deserialize | ( | const node_type & | src, | |
DeserializableT & | target | |||
) | const [inline] |
bool s11nlite::client_api< NodeType >::deserialize_subnode | ( | const node_type & | src, | |
const std::string & | subnodename, | |||
DeserializableT & | target | |||
) | const [inline] |
DeserializableT* s11nlite::client_api< NodeType >::deserialize_subnode | ( | const node_type & | src, | |
const std::string & | subnodename | |||
) | const [inline] |
SerializableType* s11nlite::client_api< NodeType >::load_serializable | ( | std::istream & | src | ) | [inline] |
Tries to load a data_node from src, then deserialize that to a SerializableType.
Definition at line 393 of file client_api.hpp.
SerializableType* s11nlite::client_api< NodeType >::load_serializable | ( | const std::string & | src | ) | [inline] |
Overloaded form which takes a file name.
1.1.3: removed the never-used 2nd parameter.
Subclassers: the loading is done via load_node(), so you can intercept the src string there.
Definition at line 410 of file client_api.hpp.
SerializableType* s11nlite::client_api< NodeType >::clone | ( | const SerializableType & | tocp | ) | const [inline] |
bool s11nlite::client_api< NodeType >::cast | ( | const Type1 & | t1, | |
Type2 & | t2 | |||
) | const [inline] |
static client_api<node_type>& s11nlite::client_api< NodeType >::instance | ( | ) | [inline, static] |
Returns a shared instance of this class.
The object itself is post-main() safe (on most systems), meaning if this function is called after the shared object is destroy (after main() exits), it "should" actually behave properly be re-instantiating the object in-place. See s11n/phoenix.hpp for details and caveats. In the worst case, it's no less safe than any other post-main() object.
Definition at line 454 of file client_api.hpp.