s11n.hpp

Go to the documentation of this file.
00001 #ifndef s11n_S11N_H_INCLUDED
00002 #define s11n_S11N_H_INCLUDED 1
00003 
00004 ////////////////////////////////////////////////////////////////////////
00005 // s11n.hpp:
00006 // Author: stephan beal <stephan@s11n.net>
00007 // License: Public Domain
00008 //
00009 // This header includes "everything most clients would want" regarding
00010 // the core s11n library. It does not include any i/o- or s11nlite-
00011 // related headers.
00012 //
00013 // The s11n namespace docs go here so doxygen will pick them up nicely.
00014 ////////////////////////////////////////////////////////////////////////
00015 
00016 #include <string>
00017 
00018 /**
00019    The s11n serialization (s11n) framework is an object serialization
00020    framework for C++ modelled heavily off work by Rusty Ballinger
00021    (bozo@users.sourceforge.net http://libfunutil.sourceforge.net). 
00022    It provides a framework off of which a wide variety of C++ objects
00023    can be serialized and deserialized (saved and loaded) with a
00024    trivial amount of effort.
00025 
00026    As far as i know Rusty was the one to coin the phrase "s11n" (short
00027    for "serialization", in the same way that i18n is short for
00028    "internationalization").
00029 
00030    In addition to the API documentation, please see the library
00031    manual, available in the source tree, in the docs subdir.
00032    It is also available for download on our web site in other
00033    formats (i.e., not LyX).
00034 
00035    The most important concepts for clients to understand:
00036 
00037    - Data Node (a.k.a. S11n Node or SNode), as described in the
00038    library manual and demonstrated by the reference implementation,
00039    s11n::s11n_node.
00040 
00041    - the serialize() and deserialize() family of free functions.
00042 
00043    - Serializable type registration, as covered in the library manual.
00044 
00045    See the source tree, under <tt>src/client/sample</tt>, for
00046    many examples of client code.
00047 */
00048 namespace s11n
00049 {
00050 
00051         /**
00052            Returns the string form of the s11n library version.
00053         */
00054         std::string library_version();
00055 
00056         /**
00057            The Private namespace holds internal library types: these
00058            should not be used in client code. See also the Detail
00059            namespace, which is similar but subtly different.
00060         */
00061         namespace Private
00062         {
00063         }
00064 
00065         /**
00066            The s11n::io namespace defines some i/o-related types which
00067            conform to the conventions expected by the
00068            <code>s11n::de/serialize()</code> core functions. This
00069            namespace deals with the de/serialization of Data Nodes at
00070            the stream/file level, leaving the s11n core to only deal
00071            with de/serialization of containers.
00072 
00073            Clients can swap out these types and still use the core
00074            s11n interface. The core has no dependencies on this
00075            namespace. s11nlite combines the s11n core and i/o
00076            interfaces into a single, easy-to-use API, and users who
00077            don't <em>need</em> to directly act with the Serializers
00078            are strongly encouraged to stick to using s11nlite for
00079            their save/load needs.
00080 
00081            s11n's default Serializer implementations all live
00082            in the s11n::io namespace, and are derived from
00083            <code>serializer<NodeT></code>. Clients
00084            who subclass this type and follow the conventions
00085            laid out by the reference implementations can plug
00086            their own Serializers into the framework with very
00087            little effort. For an example of a plug-in Serializer
00088            see the <a href="http://s11n.net/mysql/">mysql_serializer</a>.
00089         */
00090         namespace io {
00091         }
00092 
00093 
00094     /**
00095        The Detail namespace holds types which aren't strictly
00096        internal/private, but are nonetheless considered to be
00097        "implementation details." Unless specifically documented
00098        otherwise, clients are discouraged from using the
00099        Detail-namespace API from client code, as any part of it
00100        may change significantly or be replaced/removed without any
00101        warning.
00102 
00103        Clients wishing to use Detail-namespace code are instead
00104        encouraged to make their own copy, rename the namespace,
00105        and tweak to suit.
00106 
00107        The main difference between the Private and Detail
00108        namespaces is... well, vague. As a "general guideline",
00109        most Private code is specific to one certain area of this
00110        library, where as Detail code might have utility in
00111        throughout the library, or even play a fundamental role in
00112        the implementation. An example of a Detail is the phoenix<>
00113        class: it plays no direct part in serialization proper, and
00114        thus was moved out of the top-level s11n namespace, but is
00115        used throughout the framework to provide shared object
00116        instances for many purposes.
00117     */
00118     namespace Detail {
00119     }
00120 
00121 }
00122 
00123 #include <s11n.net/s11n/s11n_config.hpp> // configure/build-time config vars
00124 #include <s11n.net/s11n/classload.hpp> // classloader API
00125 #include <s11n.net/s11n/traits.hpp> // node_traits and s11n_traits
00126 #include <s11n.net/s11n/exception.hpp> // exception types
00127 #include <s11n.net/s11n/serialize.hpp> // serialize() and friends
00128 #include <s11n.net/s11n/algo.hpp> // generic algos used by the framework
00129 #include <s11n.net/s11n/s11n_node.hpp> // Reference Data Node implementation
00130 #include <s11n.net/s11n/tags.hpp> // de/serialize operator tags
00131 
00132 #endif // s11n_S11N_H_INCLUDED

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