s11nlite Namespace Reference

s11nlite is a simplified subset of the s11n interface, combining the APIs from the core and the s11n::io namespace into a single API. More...


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...
class  simple_config
 simple_config provides very basic config file features. More...

Typedefs

typedef client_api< s11n::s11n_nodeclient_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_interfaceinstance ()
 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_interfacecreate_serializer ()
 Returns a new instance of the default serializer class.
serializer_interfacecreate_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_typefind_child (node_type &parent, const std::string subnodename)
 A non-const overload.
const node_typefind_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_typeload_node (const std::string &src)
 Tries to load a node from the given filename.
node_typeload_node (std::istream &src)
 Tries to load a node from the given input stream.


Detailed Description

s11nlite is a simplified subset of the s11n interface, combining the APIs from the core and the s11n::io namespace into a single API.

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


Typedef Documentation

typedef client_api<s11n::s11n_node> s11nlite::client_interface

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.

typedef client_interface::node_traits s11nlite::node_traits

The s11n::node_traits type for node_type.

Definition at line 96 of file s11nlite.hpp.

typedef client_interface::node_type s11nlite::node_type

node_type is the type used to store/load a Serializable object's data.

FYI: node_type might change to s11n::s11n_node in 1.1, because that implementation is a tiny bit more lightweight than s11n::data_node, and was designed specifically with node_traits in mind (data_node came much earlier than either of them). If you only use node_traits to access nodes' data then your code will be oblivious to this change (but will need a recompile).

Definition at line 93 of file s11nlite.hpp.

typedef client_interface::serializer_interface s11nlite::serializer_interface

This is the base-most type of the serializers used by s11nlite.

Definition at line 101 of file s11nlite.hpp.


Function Documentation

serializer_interface* s11nlite::create_serializer ( const std::string &  classname  ) 

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 158 of file serializers.hpp.

serializer_interface* s11nlite::create_serializer (  ) 

Returns a new instance of the default serializer class.

The caller owns the returned pointer.

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.

There is guaranteed to return *some* object, except possibly post-main() (where all bets are off).

See instance(client_interface*) for more details.

Referenced by save(), serialize(), and serialize_subnode().

node_type* s11nlite::load_node ( std::istream &  is  ) 

Tries to load a node from the given input stream.

ACHTUNG: Only usable for loading ROOT nodes.

Definition at line 605 of file data_node_io.hpp.

node_type* s11nlite::load_node ( const std::string &  src  ) 

Tries to load a node from the given filename.

The caller owns the returned pointer.

template<typename SerializableType>
bool s11nlite::save ( const SerializableType &  src,
const std::string &  dest 
)

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 261 of file s11nlite.hpp.

References instance().

template<typename SerializableType>
bool s11nlite::save ( const SerializableType &  src,
std::ostream &  dest 
)

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 248 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().

template<typename SerializableType>
bool s11nlite::serialize ( node_type &  dest,
const SerializableType &  src 
)

See s11n::serialize().

Definition at line 201 of file s11nlite.hpp.

References instance().

template<typename SerializableType>
bool s11nlite::serialize_subnode ( node_type &  dest,
const std::string &  subnodename,
const SerializableType &  src 
)

See s11n::serialize().

Definition at line 211 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).


Generated on Thu Feb 8 10:28:31 2007 for libs11n-1.2.5 by  doxygen 1.5.0