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