Classes | |
class | client_api |
client_api is an abstraction of the 1.0.x s11nlite interface (GAWD, NOT ANOTHER ABSTRACTION LAYER!), providing an interface which works with all compatible S11n Node types. More... | |
class | micro_api |
micro_api is of arguable utility, written just to see what happens. More... | |
struct | save_binary_f |
A binary functor to save s-nodes and Serializables using s11nlite::save(). More... | |
struct | save_string_unary_f |
A functor which forwards to s11nlite::save(node_type,string). More... | |
struct | save_stream_unary_f |
A unary functor which forwards to s11nlite::save(node_type|SerializableT,ostream). More... | |
struct | save_nullary_base_f |
An "implementation detail" nullary functor type to simplify implementations of save_xxx_nullary_f. More... | |
struct | save_node_string_nullary_f |
A nullary functor forwarding to s11nlite::save(node,string). More... | |
struct | save_node_stream_nullary_f |
A nullary functor forwarding to s11nlite::save(node,string). More... | |
struct | save_serializable_string_nullary_f |
A nullary functor forwarding to s11nlite::save(SerT,string). More... | |
struct | save_serializable_stream_nullary_f |
A nullary functor forwarding to s11nlite::save(Serializable,ostream). More... | |
struct | load_node_stream_nullary_f |
A nullary functor to call s11nlite::load_node(istream&). More... | |
struct | load_node_string_nullary_f |
A nullary functor to call s11nlite::load_node(string). More... | |
struct | load_node_unary_f |
A unary functor to call s11nlite::load_node(string|stream). More... | |
class | serializable_base |
A convenience base type for polymorphic serializable types. More... | |
struct | serializable_base_s11n |
class | simple_config |
simple_config provides very basic config file features. More... | |
Typedefs | |
typedef client_api < s11n::s11n_node > | client_interface |
client_interface defines the interface used/returned by the instance() functions. | |
typedef client_interface::node_type | node_type |
node_type is the type used to store/load a Serializable object's data. | |
typedef client_interface::node_traits | node_traits |
The s11n::node_traits type for node_type. | |
typedef client_interface::serializer_interface | serializer_interface |
This is the base-most type of the serializers used by s11nlite. | |
Functions | |
client_interface & | instance () |
Returns the client_interface object used by the s11nlite API. | |
void | instance (client_interface *newinstance) |
Sets the client_interface object used by the s11nlite API. | |
serializer_interface * | create_serializer () |
Returns a new instance of the default serializer class. | |
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 &) |
Sets the current Serializer class used by s11nlite's create_serializer(). | |
std::string | serializer_class () |
Gets the name of the current Serializer type. | |
node_type * | find_child (node_type &parent, const std::string subnodename) |
A non-const overload. | |
const node_type * | find_child (const node_type &parent, const std::string subnodename) |
Equivalent to s11n::find_child_by_name( parent, subnodename ). | |
template<typename SerializableType> | |
bool | serialize (node_type &dest, const SerializableType &src) |
See s11n::serialize(). | |
template<typename SerializableType> | |
bool | serialize_subnode (node_type &dest, const std::string &subnodename, const SerializableType &src) |
See s11n::serialize(). | |
bool | save (const node_type &src, std::ostream &dest) |
Saves the given node to the given ostream using the default serializer type. | |
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. | |
node_type * | load_node (const std::string &src) |
Tries to load a node from the given filename. | |
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) |
See s11n::deserialize(). | |
template<typename DeserializableT> | |
bool | deserialize (const node_type &src, DeserializableT &target) |
Tries to deserialize src into target. | |
template<typename DeserializableT> | |
bool | deserialize_subnode (const node_type &src, const std::string &subnodename, DeserializableT &target) |
Exactly like deserialize(), but operates on a subnode of src named subnodename. | |
template<typename DeserializableT> | |
DeserializableT * | deserialize_subnode (const node_type &src, const std::string &subnodename) |
Exactly like deserialize(), but operates on a subnode of src named subnodename. | |
template<typename SerializableType> | |
SerializableType * | load_serializable (std::istream &src) |
Tries to load an S11nNode 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 * | s11n_clone (const SerializableType &tocp) |
See s11n::s11n_clone(). | |
template<typename Type1, typename Type2> | |
bool | s11n_cast (const Type1 &t1, Type2 &t2) |
See s11n::s11n_cast(). | |
template<typename SerT> | |
save_serializable_string_nullary_f < SerT > | save_nullary_f (SerT const &src, std::string const &dest) |
Returns save_serializable_string_nullary_f<SerT>( src, dest ). | |
template<typename SerT> | |
save_serializable_stream_nullary_f < SerT > | save_nullary_f (SerT const &src, std::ostream &dest) |
Returns save_serializable_stream_nullary_f<SerT>( src, dest ). | |
save_node_string_nullary_f | save_nullary_f (node_type const &src, std::string const &dest) |
Returns save_node_string_nullary_f( src, dest ). | |
save_node_stream_nullary_f | save_nullary_f (node_type const &src, std::ostream &dest) |
Returns save_node_stream_nullary_f( src, dest ). | |
load_node_string_nullary_f | load_node_nullary_f (std::string const &s) |
Returns load_node_string_nullary_f(s). | |
load_node_stream_nullary_f | load_node_nullary_f (std::istream &s) |
Returns load_node_stream_nullary_f(s). |
It refines the s11n interface to almost-minimal, while still leaving the full power of the underlying framework at clients' disposals if they need it. It also provides a binding to the default i/o implementation (the s11n::io-related Serializers), meaning that clients don't have to deal with file formats at all, and almost never even need to deal with the Serializer interface.
It is completely compatible with the core s11n framework, but directly provides only a subset of the interface: those operations common to most client-side use-cases, and those functions where s11nlite can eliminate one of the required template parameters (s11n's conventional NodeType argument, which s11nlite hard-codes in its note_type typedef).
This implementation can easily be used as a basis for writing custom client-side, s11n-based serialization frameworks.
Suggestions for including specific features into this interface are of course welcomed.
Common conventions concerning this API:
As of version 1.1, s11nlite is primarily a wrapper around the type s11nlite::client_api<>. Many of s11nlite's functions internally use a client_api instance to do their work. This allows clients to swap out most of the s11nlite implementation with their own at runtime, while still allowing all s11nlite clients to use the same front-end API.
License: Do As You Damned Well Please
Author: stephan@s11n.net
client_interface defines the interface used/returned by the instance() functions.
By subclassing this type and reimplmenting the appropriate virtual functions, a client-supplied instance of this type can be plugged in as the primary s11nlite API handler. This allows, for example, transparently adding compression or network support to s11nlite.
Definition at line 79 of file s11nlite.hpp.
node_type is the type used to store/load a Serializable object's data.
Definition at line 85 of file s11nlite.hpp.
This is the base-most type of the serializers used by s11nlite.
Definition at line 93 of file s11nlite.hpp.
serializer_interface* s11nlite::create_serializer | ( | const std::string & | classname | ) | [inline] |
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 its class name would.
The internally-supported serializers all support 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.
Short-form names of internally-supported Serializers:
Note that the short-form name is always the same as that of the underlying Serializer class, minus the _serializer suffix. This is purely a convention, and not a rule. This command will use s11n::plugin support, if available, to dynamically load new serializers. Simply name the DLL the same as the class, without any namespace part in the filename, and your platform-specific DLL file extension (e.g. .dll, .so, or .dylib).
Returns a new instance of the given serializer class, or 0 if one could not be loaded.
e.g., register_serializer() will do the trick.
If no serializer for classname is found and classname does not contain the string "_serializer", then then (classname+"_serializer") is tried. This is intended to ease DLL lookups for the conventional abbreviations for the Serializer classes (i.e., my_serializer).
The caller owns the returned pointer, which may be 0.
Definition at line 152 of file serializers.hpp.
serializer_interface* s11nlite::create_serializer | ( | ) |
Returns a new instance of the default serializer class.
The caller owns the returned pointer.
bool s11nlite::deserialize | ( | const node_type & | src, | |
DeserializableT & | target | |||
) | [inline] |
Tries to deserialize src into target.
Returns true on success. If false is returned then target is not guaranteed to be in a useful state: this depends entirely on the object (but, it could be argued, if it was in a useful state then its deserialize operator would have returned true!).
DO NOT PASS A POINTER TYPE TO THIS FUNCTION. It will not do what you want it to, and it will likely cause a leak. If you want to directly deserialize to a pointer, use the s11n::deserialize<>() overload which takes a reference to a pointer.
Definition at line 308 of file s11nlite.hpp.
References instance().
SerializableType* s11nlite::deserialize | ( | const node_type & | src | ) | [inline] |
See s11n::deserialize().
ACHTUNG: if you are using both s11n and s11nlite namespaces this function will be ambiguous with one provided in the namespace s11n. You must then qualify it with the namespace of the one you wish to use.
Definition at line 286 of file s11nlite.hpp.
References instance().
DeserializableT* s11nlite::deserialize_subnode | ( | const node_type & | src, | |
const std::string & | subnodename | |||
) | [inline] |
Exactly like deserialize(), but operates on a subnode of src named subnodename.
Returns 0 if no such subnode is found.
Definition at line 333 of file s11nlite.hpp.
References instance().
bool s11nlite::deserialize_subnode | ( | const node_type & | src, | |
const std::string & | subnodename, | |||
DeserializableT & | target | |||
) | [inline] |
Exactly like deserialize(), but operates on a subnode of src named subnodename.
Returns false if no such file is found.
Definition at line 320 of file s11nlite.hpp.
References instance().
const node_type* s11nlite::find_child | ( | const node_type & | parent, | |
const std::string | subnodename | |||
) |
Equivalent to s11n::find_child_by_name( parent, subnodename ).
node_type* s11nlite::find_child | ( | node_type & | parent, | |
const std::string | subnodename | |||
) |
A non-const overload.
Ownership is not modified by calling this function: normally the parent node owns it.
void s11nlite::instance | ( | client_interface * | newinstance | ) |
Sets the client_interface object used by the s11nlite API.
Ownership of newinstance IS NOT transfered. Passing NULL will cause it to revert to the default instance. newinstance must live as long as any client is using s11nlite, and when newinstance is destroyed, 0 must be passed to this function to disassociate the object from the library.
Referenced by s11n::fac::factory_mgr< InterfaceT, KeyType >::aliases(), s11n::io::data_node_serializer< NodeType >::entity_translations(), s11n::fac::factory(), s11n::fac::factory_mgr< InterfaceT, KeyType >::factory_map(), s11n::fac::factory_mgr< InterfaceT, KeyType >::instance(), and s11nlite::client_api< NodeType >::provides_serializer().
client_interface& s11nlite::instance | ( | ) |
Returns the client_interface object used by the s11nlite API.
This is guaranteed to return *some* object, except possibly post-main() (where all bets are off).
See instance(client_interface*) for more details.
Referenced by deserialize(), deserialize_subnode(), load_serializable(), s11n::s11n_cast(), s11n::s11n_clone(), save(), serialize(), and serialize_subnode().
node_type* s11nlite::load_node | ( | std::istream & | is | ) | [inline] |
Tries to load a node from the given input stream.
The caller owns the returned pointer.
Only usable for loading ROOT nodes.
Tries to load a node from the given input stream.
It uses the cookie from the input stream (the first line) and uses s11n::cl::classload<SerializerBaseType>() to find a matching Serializer.
On error 0 is returned or an exception is thrown, else a new pointer, which the caller owns.
ACHTUNG: Only usable for loading ROOT nodes.
See guess_serializer( std::istream & is ) for more information, as that function is used to dispatch the stream.
Definition at line 543 of file data_node_io.hpp.
References s11n::Detail::auto_ptr< T >::get().
Referenced by s11nlite::load_node_unary_f::operator()(), s11nlite::load_node_string_nullary_f::operator()(), and s11nlite::load_node_stream_nullary_f::operator()().
node_type* s11nlite::load_node | ( | const std::string & | src | ) | [inline] |
Tries to load a node from the given filename.
The caller owns the returned pointer.
Only usable for loading ROOT nodes.
Tries to load a node from the given filename.
This is handled separately from the stream overload because some Serializers must behave differently in the face of streams. e.g., db-based Serializers typically can't deal with streams.
ACHTUNG: Only usable for loading ROOT nodes.
Added in 1.2.1.
Behaviour change in 1.3.0: The second argument to this function (bool ExternalData) was removed.
Definition at line 569 of file data_node_io.hpp.
References s11n::Detail::auto_ptr< T >::get().
load_node_stream_nullary_f s11nlite::load_node_nullary_f | ( | std::istream & | s | ) | [inline] |
load_node_string_nullary_f s11nlite::load_node_nullary_f | ( | std::string const & | s | ) | [inline] |
SerializableType* s11nlite::load_serializable | ( | const std::string & | src | ) | [inline] |
Overloaded form which takes a file name.
1.1.3: removed the never-used 2nd parameter.
Definition at line 356 of file s11nlite.hpp.
References instance().
SerializableType* s11nlite::load_serializable | ( | std::istream & | src | ) | [inline] |
Tries to load an S11nNode from src, then deserialize that to a SerializableType.
Definition at line 345 of file s11nlite.hpp.
References instance().
bool s11nlite::s11n_cast | ( | const Type1 & | t1, | |
Type2 & | t2 | |||
) | [inline] |
See s11n::s11n_cast().
"Casts" t1 to t2 using serialization.
Definition at line 376 of file s11nlite.hpp.
SerializableType* s11nlite::s11n_clone | ( | const SerializableType & | tocp | ) | [inline] |
See s11n::s11n_clone().
Clones an arbitrary SerializableType using its DataNodeType serialization implementation.
This function was renamed from clone() in version 1.1.
Definition at line 367 of file s11nlite.hpp.
bool s11nlite::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!
Definition at line 253 of file s11nlite.hpp.
References instance().
Referenced by s11nlite::save_nullary_base_f< ::client_interface::node_type, std::ostream & >::operator()(), s11nlite::save_stream_unary_f::operator()(), s11nlite::save_string_unary_f::operator()(), and s11nlite::save_binary_f::operator()().
bool s11nlite::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!
Definition at line 240 of file s11nlite.hpp.
References instance().
bool s11nlite::save | ( | const node_type & | src, | |
const std::string & | filename | |||
) |
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!
bool s11nlite::save | ( | const node_type & | src, | |
std::ostream & | dest | |||
) |
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!
Referenced by s11nlite::simple_config::~simple_config().
save_node_stream_nullary_f s11nlite::save_nullary_f | ( | node_type const & | src, | |
std::ostream & | dest | |||
) | [inline] |
save_node_string_nullary_f s11nlite::save_nullary_f | ( | node_type const & | src, | |
std::string const & | dest | |||
) | [inline] |
save_serializable_stream_nullary_f<SerT> s11nlite::save_nullary_f | ( | SerT const & | src, | |
std::ostream & | dest | |||
) | [inline] |
Returns save_serializable_stream_nullary_f<SerT>( src, dest ).
Definition at line 656 of file s11nlite.hpp.
save_serializable_string_nullary_f<SerT> s11nlite::save_nullary_f | ( | SerT const & | src, | |
std::string const & | dest | |||
) | [inline] |
Returns save_serializable_string_nullary_f<SerT>( src, dest ).
Definition at line 646 of file s11nlite.hpp.
bool s11nlite::serialize | ( | node_type & | dest, | |
const SerializableType & | src | |||
) | [inline] |
bool s11nlite::serialize_subnode | ( | node_type & | dest, | |
const std::string & | subnodename, | |||
const SerializableType & | src | |||
) | [inline] |
See s11n::serialize().
Definition at line 203 of file s11nlite.hpp.
References instance().
Referenced by s11n::subnode_serializer_f< NodeType >::operator()().
std::string s11nlite::serializer_class | ( | ) |
Gets the name of the current Serializer type.
void s11nlite::serializer_class | ( | const std::string & | ) |
Sets the current Serializer class used by s11nlite's create_serializer().
Pass it a class name, or one of the convenience names listed in create_serializer(string).