s11n::io Namespace Reference

The s11n::io namespace defines some i/o-related types which conform to the conventions expected by the s11n::de/serialize() core functions. More...


Classes

class  compact_serializer
 De/serializes objects from/to a compact binary-like grammar. More...
class  tree_builder
 tree_builder exists mainly so some lex-based code can get access to a non-templated type (so we don't have to hard-code the parsers to a node_type). More...
class  tree_builder_context
 tree_builder_context is a helper for accessing some template-dependent code from non-template-aware lexer code. More...
class  data_node_tree_builder
 data_node_tree_builder is a helper class for building trees from deserialized data, designed particularly for use with lex/callback-based tree builders. More...
class  tree_builder_lexer
 tree_builder_lexer is a type intended to ease the implementation of lex-based node tree parsers. More...
class  key_value_serializer
 A helper for serializing properties to a stream. More...
struct  node_child_simple_formatter
 A helper functor to loop over serializable children of a node from within a Serializer implementation. More...
class  data_node_serializer
 data_node_serializer provides an interface for saving/loading a given abstract data node type to/from streams. More...
class  expat_serializer
 expat_serializer is an XML-based Serializer, using libexpat to read it's data. More...
class  funtxt_serializer
 De/serializes objects from/to this class' config-file-like grammar. More...
class  funxml_serializer
 De/serializes objects from/to a simple XML grammar, with all properties and children stored as subnodes. More...
class  js_serializer
 js_serializer writes objects to a Javascript dialect. More...
class  parens_serializer
 De/serializes objects from/to a lisp-like grammar. More...
class  simplexml_serializer
 De/serializes objects from/to a simple XML grammar, with properties stored as XML attibutes and children stored as subnodes. More...
class  url_parser
 url_parser is a basic implementation for parsing a URL string into its atomic components. More...
class  url_stream_factory
 A factory type intended to be subclassed to provide protocol-specific i/o streams. More...
class  file_stream_factory
 This factory creates streams for URLs in the following format:. More...
class  wesnoth_serializer
 De/serializes objects from/to this class' config-file-like grammar. More...

Namespaces

namespace  Private
namespace  sharing
namespace  strtool
 The strtool namespace encapsulates a set of utility functions for working with string objects.

Typedefs

typedef std::map
< std::string,
std::string > 
entity_translation_map
 A typedef representing a map of tokens used for "entity translations" by s11n parsers/serializers.
typedef std::map
< std::string,
std::string > 
entity_translation_map
 convenience typedef
typedef std::map
< std::string,
std::string > 
entity_translation_map
 convenience typedef
typedef std::map
< std::string,
std::string > 
entity_translation_map
typedef std::map
< std::string,
std::string > 
entity_translation_map
 convenience typedef

Functions

template<typename NodeType, typename BuilderContext>
NodeType * deserialize_lex_forwarder (const std::string &lexerClassName, std::istream &src)
 This function exists for a really long, strange reason involving accessing templatized types from template-free code (FlexLexers).
std::ostream * get_ostream (const std::string name)
 Returns an output stream for the given file name.
std::istream * get_istream (const std::string name)
 Returns an input stream for the given file name.
std::string get_magic_cookie (const std::string &src)
 Convenience function for grabbing the first line of a file.
std::string get_magic_cookie (std::istream &is)
 Convenience function for grabbing the first line of a stream.
template<typename NodeType>
data_node_serializer
< NodeType > * 
guess_serializer (std::istream &is)
 Tries to guess which Serializer can be used to read is.
template<typename NodeType>
data_node_serializer
< NodeType > * 
guess_serializer (std::string const &infile)
 An overload which assumes infile is a local file.
template<typename NodeType>
NodeType * load_node (std::istream &is)
 Tries to load a NodeType object from the given node.
template<typename NodeType>
NodeType * load_node (const std::string &src)
 Similar to load_node( istream ), overloaded to take a filename.
template<typename NodeT, typename SerializableT>
SerializableT * load_serializable (std::istream &src)
 Tries to load a SerializableT from the given stream.
template<typename NodeT, typename SerializableT>
SerializableT * load_serializable (const std::string &src)
 An overloaded form which takes an input string.
entity_translation_mapexpat_serializer_translations ()
 The entity translations map used by expat_serializer.
entity_translation_mapfuntxt_serializer_translations ()
 The entity translations map used by funtxt_serializer.
entity_translation_mapfunxml_serializer_translations ()
 The entity translations map used by funxml_serializer.
std::string quote_js_string (std::string const &s)
 An attempt to quote s as a JS string:.
entity_translation_mapparens_serializer_translations ()
 The entity translations map used by parens_serializer.
template<typename NodeT, typename ListT>
void serializer_list (ListT &target, bool onlyShortNames=true)
 Intended mainly as a convenience for client applications, serializer_list() populates the target list with the names of registered Serializers.
template<typename SerializerT>
void register_serializer (const std::string &classname, const std::string &alias)
 Registers a Serializer type with the s11n::io layer.
template<typename NodeT>
s11n::io::data_node_serializer
< NodeT > * 
create_serializer (const std::string &classname)
 Returns a Serializer object, which must have been registered with the s11n::cl/s11nfac classloading API, using an interface type of s11n::io::data_node_serializer<NodeT>.
entity_translation_mapsimplexml_serializer_translations ()
 The entity translations map used by simplexml_serializer.
std::istream * get_url_istream (std::string const &url)
 Convenience overload.
std::istream * get_url_istream (url_parser const &url)
 Classloads an instance of an istream, using a url_stream_factory to create the stream.
std::ostream * get_url_ostream (std::string const &url)
 Convenience overload.
std::ostream * get_url_ostream (url_parser const &url)
 See get_url_istream().
entity_translation_mapwesnoth_serializer_translations ()
 The entity translations map used by wesnoth_serializer.


Detailed Description

The s11n::io namespace defines some i/o-related types which conform to the conventions expected by the s11n::de/serialize() core functions.

This namespace deals with the de/serialization of Data Nodes at the stream/file level, leaving the s11n core to only deal with de/serialization of containers.

Clients can swap out these types and still use the core s11n interface. The core has no dependencies on this namespace. s11nlite combines the s11n core and i/o interfaces into a single, easy-to-use API, and users who don't need to directly act with the Serializers are strongly encouraged to stick to using s11nlite for their save/load needs.

s11n's default Serializer implementations all live in the s11n::io namespace, and are derived from serializer<NodeT>. Clients who subclass this type and follow the conventions laid out by the reference implementations can plug their own Serializers into the framework with very little effort. For an example of a plug-in Serializer see the mysql_serializer.


Typedef Documentation

typedef std::map<std::string,std::string> s11n::io::entity_translation_map

convenience typedef

Definition at line 26 of file wesnoth_serializer.hpp.

typedef std::map<std::string,std::string> s11n::io::entity_translation_map

Definition at line 33 of file simplexml_serializer.hpp.

typedef std::map<std::string,std::string> s11n::io::entity_translation_map

convenience typedef

Definition at line 31 of file funxml_serializer.hpp.

typedef std::map<std::string,std::string> s11n::io::entity_translation_map

convenience typedef

Definition at line 34 of file expat_serializer.hpp.

typedef std::map<std::string,std::string> s11n::io::entity_translation_map

A typedef representing a map of tokens used for "entity translations" by s11n parsers/serializers.

Definition at line 56 of file data_node_format.hpp.


Function Documentation

template<typename NodeT>
s11n::io::data_node_serializer<NodeT>* s11n::io::create_serializer ( const std::string &  classname  )  [inline]

Returns a Serializer object, which must have been registered with the s11n::cl/s11nfac classloading API, using an interface type of s11n::io::data_node_serializer<NodeT>.

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.

template<typename NodeType, typename BuilderContext>
NodeType* s11n::io::deserialize_lex_forwarder ( const std::string &  lexerClassName,
std::istream &  src 
) [inline]

This function exists for a really long, strange reason involving accessing templatized types from template-free code (FlexLexers).

The caller owns the returned poiner, which may be 0.

As of s11n version 1.1.3, this function may throw on error, and is guaranteed to propagate any exceptions it catches (after cleaning up). Except when passing on a (...) exception, all thrown exceptions are guaranteed to be std::exception types.

Definition at line 593 of file data_node_format.hpp.

References s11n::io::Private::lex_api_hider_yylex().

Referenced by s11n::io::tree_builder_lexer< NodeType, s11n::io::sharing::funxml_sharing_context >::deserialize().

entity_translation_map& s11n::io::expat_serializer_translations (  ) 

The entity translations map used by expat_serializer.

entity_translation_map& s11n::io::funtxt_serializer_translations (  ) 

The entity translations map used by funtxt_serializer.

Referenced by s11n::io::funtxt_serializer< NodeType >::entity_translations().

entity_translation_map& s11n::io::funxml_serializer_translations (  ) 

The entity translations map used by funxml_serializer.

Referenced by s11n::io::funxml_serializer< NodeType >::entity_translations().

std::istream* s11n::io::get_istream ( const std::string  name  ) 

Returns an input stream for the given file name.

Caller owns the returned pointer, which may be 0.

As of version 1.3.0, this function supports URLs. URLs will be dispatched to get_url_ostream().

When passed a non-URL filename the returned stream supports libzl and libbz2 if your libs11n is built with libs11n_zfstream support. That means that if zfstream::compression_policy() is set, then the returned string might be a compressing stream.

In version 1.3.0 the 2nd parameter (ExternalData) was removed because it is never used.

Referenced by s11n::io::data_node_serializer< NodeType >::deserialize(), and guess_serializer().

std::string s11n::io::get_magic_cookie ( std::istream &  is  ) 

Convenience function for grabbing the first line of a stream.

Returns the first line of the given stream, or an empty string on error.

As of version 1.2.1, this function behaves slightly differently than prior versions: the returned string will be the first consecutive non-control characters in the line. This allows us to properly read some binary formats which use a string identifier as a magic cookie (e.g. sqlite databases). In this context "control characters" are anything outside the range of ASCII values [32..126]. This change "shouldn't" affect any pre-1.2.1 behaviours, which were never tested/used with binary file formats.

std::string s11n::io::get_magic_cookie ( const std::string &  src  ) 

Convenience function for grabbing the first line of a file.

See get_magic_cookie( istream & ) for notes on a minor functional change introduced in version 1.2.1.

Changed in 1.3.0: second parameter to this function (bool ExternalData) was removed.

Referenced by guess_serializer().

std::ostream* s11n::io::get_ostream ( const std::string  name  ) 

Returns an output stream for the given file name.

Caller owns the returned pointer, which may be 0.

As of version 1.3.0, this function supports URLs. URLs will be dispatched to get_url_ostream().

When passed a non-URL filename, the returned stream supports libzl and libbz2 if your libs11n is built with libs11n_zfstream support, meaning it can read files compressed with zlib/gzip or bz2lib.

Referenced by s11n::io::data_node_serializer< NodeType >::serialize().

std::istream* s11n::io::get_url_istream ( url_parser const &  url  ) 

Classloads an instance of an istream, using a url_stream_factory to create the stream.

Caller owns the returned pointer, which may be 0. Failure indicates one of:

std::istream* s11n::io::get_url_istream ( std::string const &  url  ) 

Convenience overload.

std::ostream* s11n::io::get_url_ostream ( url_parser const &  url  ) 

See get_url_istream().

std::ostream* s11n::io::get_url_ostream ( std::string const &  url  ) 

Convenience overload.

template<typename NodeType>
data_node_serializer<NodeType>* s11n::io::guess_serializer ( std::string const &  infile  )  [inline]

An overload which assumes infile is a local file.

Added in 1.2.1.

Definition at line 516 of file data_node_io.hpp.

References get_istream().

template<typename NodeType>
data_node_serializer<NodeType>* s11n::io::guess_serializer ( std::istream &  is  )  [inline]

Tries to guess which Serializer can be used to read is.

Returns an instance of that type on success or 0 on error. The caller owns the returned object. It may propagate exceptions.

Achtung: the first line of input from the input stream is consumed by this function (to find the cookie), which means that if this stream is handed off to the object which this function returns, it won't get its own cookie. The only reliable way around this [that i know of] is to buffer the whole input as a string, and i don't wanna do that (it's really bad for massive data files).

Special feature:

If the first line of the stream is "#s11n::io::serializer CLASSNAME" or "#!/s11n/io/serialize CLASSNAME" then the CLASSNAME token is expected to be a Serializer class name. This function will try to classload that object. If successful it will use that type to deserialize the input stream. If that fails, it will return 0. The intention of this feature is to simplify creation of non-C++ tools which generate s11n data (e.g., perl scripts), so that they don't need to know the exact cookies.

Added in 1.2.1.

Definition at line 481 of file data_node_io.hpp.

References get_magic_cookie().

template<typename NodeType>
NodeType* s11n::io::load_node ( const std::string &  src  )  [inline]

Similar to load_node( istream ), overloaded to take a filename.

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.

template<typename NodeType>
NodeType* s11n::io::load_node ( std::istream &  is  )  [inline]

Tries to load a NodeType object from the given node.

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.

template<typename NodeT, typename SerializableT>
SerializableT* s11n::io::load_serializable ( const std::string &  src  )  [inline]

An overloaded form which takes an input string.

If ExternalData is true the string is treated as a file name, otherwise it is processed as an input stream.

ACHTUNG: Only usable for loading ROOT nodes.

Changed in 1.3.0: the second parameter to this function (bool ExternalData) was removed.

Definition at line 610 of file data_node_io.hpp.

template<typename NodeT, typename SerializableT>
SerializableT* s11n::io::load_serializable ( std::istream &  src  )  [inline]

Tries to load a SerializableT from the given stream.

On success returns a new object, else 0.

The caller owns the returned pointer.

ACHTUNG: Only usable for loading ROOT nodes.

Definition at line 587 of file data_node_io.hpp.

References CERR.

entity_translation_map& s11n::io::parens_serializer_translations (  ) 

The entity translations map used by parens_serializer.

Referenced by s11n::io::parens_serializer< NodeType >::entity_translations().

std::string s11n::io::quote_js_string ( std::string const &  s  ) 

An attempt to quote s as a JS string:.

If s contains no apostrophes, it is returned as 's', with apostrophes as quotes. Else, if it contains no double-quotes, "s" is returned. Else we backslash-escape the apostrophes and return 's'.

template<typename SerializerT>
void s11n::io::register_serializer ( const std::string &  classname,
const std::string &  alias 
) [inline]

Registers a Serializer type with the s11n::io layer.

It must:

i.e., the conventions of all of the Serializers included with libs11n.

Registering makes the type available to the data_node_serializer classloader.

Arguments:

SerializeT's magic_cookie() function is called to alias the cookie as an alias for classname. Thus, a SerializerT object is (briefly) instantiated.

Node that this function essentially performs the same operations as the reg_serializer.hpp supermacro, and the two should be equivalent (though this seems easier to use).

Definition at line 122 of file serializers.hpp.

template<typename NodeT, typename ListT>
void s11n::io::serializer_list ( ListT &  target,
bool  onlyShortNames = true 
) [inline]

Intended mainly as a convenience for client applications, serializer_list() populates the target list with the names of registered Serializers.

ListT must support push_back(std::string).

If onlyShortNames is true (the default) then only "simple" names (only alphanumeric or underscore characters) are put into target, not the "full" names of the classes. This is to make the data more useful in the context of client applications as, e.g., a list of choices for users.

When onlyShortNames is false then the list may contain some unsightly magic cookie strings.

In either case, the list may very well contain different names for the same underlying Serializer, as most are registered with several aliases.

Note that only serializers extending from s11n::io::data_node_serializer<NodeT> are returned.

Maintenance note: i don't encourage the direc use of s11n::fac here, but that is currently the only way to get the list of class names from the factory layer.

Definition at line 45 of file serializers.hpp.

References s11n::fac::alias().

entity_translation_map& s11n::io::simplexml_serializer_translations (  ) 

The entity translations map used by simplexml_serializer.

Referenced by s11n::io::simplexml_serializer< NodeType >::entity_translations().

entity_translation_map& s11n::io::wesnoth_serializer_translations (  ) 

The entity translations map used by wesnoth_serializer.

Referenced by s11n::io::wesnoth_serializer< NodeType >::entity_translations().


Generated on Sun Apr 27 13:16:05 2008 for libs11n by  doxygen 1.5.3