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