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 | 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 | 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 |
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, bool ExternalData=true) |
Returns an input stream for the given file name. | |
std::string | get_magic_cookie (const std::string &src, bool ExternalData=true) |
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_classload_serializer (std::istream &is) |
Tries to load a NodeType object from the given node. | |
template<typename NodeType> | |
NodeType * | load_node_classload_serializer (std::string const &src) |
Overloaded to take a filename. | |
template<typename NodeType> | |
NodeType * | load_node (std::istream &is) |
Tries to load a node from the given input stream. | |
template<typename NodeType> | |
NodeType * | load_node (const std::string &src, bool ExternalData=true) |
Overloaded form of load_node( istream ), provided for convenience. | |
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, bool ExternalData=true) |
An overloaded form which takes an input string. | |
entity_translation_map & | expat_serializer_translations () |
The entity translations map used by expat_serializer. | |
entity_translation_map & | funtxt_serializer_translations () |
The entity translations map used by funtxt_serializer. | |
entity_translation_map & | funxml_serializer_translations () |
The entity translations map used by funxml_serializer. | |
entity_translation_map & | parens_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 new instance of the given serializer class, or 0 if one could not be loaded. | |
entity_translation_map & | simplexml_serializer_translations () |
The entity translations map used by simplexml_serializer. | |
entity_translation_map & | wesnoth_serializer_translations () |
The entity translations map used by wesnoth_serializer. |
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.
|
convenience typedef
Definition at line 56 of file data_node_format.hpp. |
|
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. |
|
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, sharing::simplexml_sharing_context >::deserialize(). |
|
The entity translations map used by expat_serializer.
Referenced by s11n::io::expat_serializer< NodeType >::serialize(). |
|
The entity translations map used by funtxt_serializer.
Referenced by s11n::io::funtxt_serializer< NodeType >::entity_translations(). |
|
The entity translations map used by funxml_serializer.
Referenced by s11n::io::funxml_serializer< NodeType >::entity_translations(). |
|
Returns an input stream for the given file name. Caller owns the returned pointer, which may be 0. 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. If ExternalData is false then name is assumed to be a string containing input, and a string-reading stream is returned. Referenced by s11n::io::data_node_serializer< NodeType >::deserialize(), guess_serializer(), load_node(), and load_serializable(). |
|
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. |
|
Convenience function for grabbing the first line of a file. If ExternalData == true then returns the first line of the file, else returns up to the first newline of src. See get_magic_cookie( istream & ) for notes on a minor functional change introduced in version 1.2.1. Referenced by guess_serializer(). |
|
Returns an output stream for the given file name. Caller owns the returned pointer, which may be 0. 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(). |
|
An overload which assumes infile is a local file. Added in 1.2.1. Definition at line 498 of file data_node_io.hpp. References get_istream(). |
|
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 464 of file data_node_io.hpp. References get_magic_cookie(). |
|
Overloaded form of load_node( istream ), provided for convenience. If ExternalData is true, input is treated as a file, otherwise it is treated as a string containing input to parse. ACHTUNG: Only usable for loading ROOT nodes. Behaviour change in 1.2.1: If (ExternalData) then this call is eventually passed to ASerializer->deserialize(src). In previous versions, src was "converted" to a stream and passed to ASerializer->deserialize(istream), which does not work for some Serializers. This was fixed in 1.2.1 to allow the sqlite3 add-on to play along more transparently with s11nconvert and s11nbrowser. Definition at line 623 of file data_node_io.hpp. References get_istream(). |
|
Tries to load a node from the given input stream. ACHTUNG: Only usable for loading ROOT nodes. Definition at line 597 of file data_node_io.hpp. Referenced by s11nlite::load_node_unary_f::operator()(), s11nlite::load_node_nullary_string_f::operator()(), and s11nlite::load_node_stream_nullary_f::operator()(). |
|
Overloaded to take a 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. Added in 1.2.1. Definition at line 563 of file data_node_io.hpp. |
|
Tries to load a NodeType object from the given node. 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 526 of file data_node_io.hpp. |
|
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. Behaviour chagne in 1.2.1 when (ExternalData): load_node(string) is used to load the snode tree, as opposed to load_node(stream). This change was to allow non-stream-friendly Serializers (e.g., DB-based) to integrate more fully into s11n. Definition at line 670 of file data_node_io.hpp. References get_istream(). |
|
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 644 of file data_node_io.hpp. References CERR. |
|
The entity translations map used by parens_serializer.
Referenced by s11n::io::parens_serializer< NodeType >::entity_translations(). |
|
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 128 of file serializers.hpp. |
|
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. The exact values returned by this function may change in the future. e.g., at the moment it does not return the "real" classnames, only registered aliases, but this is arguable behaviour and may change. 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 51 of file serializers.hpp. |
|
The entity translations map used by simplexml_serializer.
Referenced by s11n::io::simplexml_serializer< NodeType >::entity_translations(). |
|
The entity translations map used by wesnoth_serializer.
Referenced by s11n::io::wesnoth_serializer< NodeType >::entity_translations(). |