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