Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
| SHA1 Hash: | 034d7cf6ba7b5430c6afefc1ce9f28615e934642 |
|---|---|
| Date: | 2008-11-13 20:41:52 |
| User: | stephan |
| Comment: | doc updates |
Changes
Changes to include/s11n.net/c11n/io/c11n_io.h
| Old (9dbf5d93642321c4) | New (5114d970cb224ba4) | |||
|---|---|---|---|---|
| 1 | #ifndef S11N_NET_C11N_IO_H_INCLUDED | 1 | #ifndef S11N_NET_C11N_IO_H_INCLUDED | |
| 2 | #define S11N_NET_C11N_IO_H_INCLUDED 1 | 2 | #define S11N_NET_C11N_IO_H_INCLUDED 1 | |
| 3 | /* | 3 | /* | |
| 4 | This file contains declarations and documentation for the generic | 4 | This file contains declarations and documentation for the generic | |
| 5 | i/o routines for c11n. The core does not know about this API and no | 5 | i/o routines for c11n. The core does not know about this API and no | |
| 6 hidden lines | ||||
| 12 | */ | 12 | */ | |
| 13 | 13 | |||
| 14 | /** | 14 | /** | |
| 15 | @page c11n_io c11n i/o model | 15 | @page c11n_io c11n i/o model | |
| 16 | 16 | |||
| > | 17 | @section c11n_io_overview c11n i/o model overview | ||
| > | 18 | |||
| > | 19 | |||
| 17 | The c11n i/o model is inherited from libs11n, and it goes | 20 | The c11n i/o model is inherited from libs11n, and it goes | |
| 18 | something like this... | 21 | something like this... | |
| 19 | 22 | |||
| 20 | Serialization is a two-phase process, broken down into the | 23 | Serialization is a two-phase process, broken down into the | |
| 21 | following steps: | 24 | following steps: | |
| 42 hidden lines | ||||
| 64 | format"). | 67 | format"). | |
| 65 | 68 | |||
| 66 | - A handful of utility routines which provide commonly-used features | 69 | - A handful of utility routines which provide commonly-used features | |
| 67 | such as saving or loading a Serializable object. | 70 | such as saving or loading a Serializable object. | |
| 68 | 71 | |||
| 69 | The c11n_stream abstract class requires concreate implementations | | | 72 | The <b>c11n_stream</b> abstract class requires concreate implementations |
| 70 | to provide i/o operations for underlying (or "native") stream | 73 | to provide i/o operations for underlying (or "native") stream | |
| 71 | types. Implementations are provided for FILE handles and a | 74 | types. Implementations are provided for FILE handles and a | |
| 72 | streaming in-memory buffer, and it is simple to add implementations | 75 | streaming in-memory buffer, and it is simple to add implementations | |
| 73 | for nearly any stream-like API. The API requires only sequential access, | 76 | for nearly any stream-like API. The API requires only sequential access, | |
| 74 | and does not require that both read and write operations be allowed | 77 | and does not require that both read and write operations be allowed | |
| 75 | on any given stream, so it should be trivial to wrap, e.g., a network | 78 | on any given stream, so it should be trivial to wrap, e.g., a network | |
| 76 | stream using the c11n_stream API. | 79 | stream using the c11n_stream API. | |
| 77 | 80 | |||
| 78 | The c11n_io_handler interface uses the c11n_node and c11n_stream | | | 81 | The <b>c11n_io_handler</b> interface uses the c11n_node and c11n_stream |
| 79 | APIs to marshall c11n_nodes to/from streams. In principal, c11n's | 82 | APIs to marshall c11n_nodes to/from streams. In principal, c11n's | |
| 80 | i/o model allows for any number of handlers to exist. As a | 83 | i/o model allows for any number of handlers to exist. As a | |
| 81 | reference point, libs11n (which is much older but uses the same | 84 | reference point, libs11n (which is much older but uses the same | |
| 82 | model) has 6 or 7 formats. c11n currently (November 2008) has only | 85 | model) has 6 or 7 formats. c11n currently (November 2008) has only | |
| 83 | two formats, one which looks like binary data (but isn't) and one | 86 | two formats, one which looks like binary data (but isn't) and one | |
| 84 | which serializes to SQL code and uses sqlite3 as a back-end to | 87 | which serializes to SQL code and uses sqlite3 as a back-end to | |
| 85 | deserialize that SQL code. In essence an arbitrary number of | 88 | deserialize that SQL code. In essence an arbitrary number of | |
| 86 | formats can be added without changing the library code, in any case | 89 | formats can be added without changing the library code, in any case | |
| 87 | (see c11n_io_handler_register()). | 90 | (see c11n_io_handler_register()). | |
| > | 91 | |||
| > | 92 | @section c11n_io_formats The c11n i/o formats | ||
| > | 93 | |||
| > | 94 | This section gives an overview of the available i/o formats for | ||
| > | 95 | c11n. Over time, support for more formats may be added (with a | ||
| > | 96 | preference for porting over formats from libs11n). The format names | ||
| > | 97 | used below can be used with c11n_io_handler_by_name() and | ||
| > | 98 | c11nconvert. | ||
| > | 99 | |||
| > | 100 | @subsection c11n_io_handler_binarish The binarish format | ||
| > | 101 | |||
| > | 102 | The <b>binarish</b> (a.k.a. "compact" and "51191011") handler is a | ||
| > | 103 | "built-in" format, not requiring any additional 3rd-party library | ||
| > | 104 | support and therefore always built in with the library. It is | ||
| > | 105 | derived from the libs11n project (where it is called "compact" or | ||
| > | 106 | "51191011") and is compatible with that library's handler. The | ||
| > | 107 | format is "nearly binary", not human editable and barely human | ||
| > | 108 | readable. It is probably the overall most efficient of the various | ||
| > | 109 | formats, as its parser is exceedingly simple and for output it does | ||
| > | 110 | not need to escape any characters (as most other formats need | ||
| > | 111 | to). This format has a couple notable limitations: | ||
| > | 112 | |||
| > | 113 | - Node names, node class names, and property keys must not exceed | ||
| > | 114 | 255 characters. | ||
| > | 115 | - Node properties must not exceed 64k (that is, 0xffff) in length. | ||
| > | 116 | |||
| > | 117 | In practice these are not normally a problem. The handler can | ||
| > | 118 | easily be changed to work around those limitations, should they | ||
| > | 119 | pose a problem, but it would mean breaking compatibility with | ||
| > | 120 | libs11n and introducing a new cookie for the new sub-format. | ||
| > | 121 | |||
| > | 122 | @subsection c11n_io_handler_sql The sql format | ||
| > | 123 | |||
| > | 124 | The optional <b>sql</b> handler writes objects out as SQL code (compatible | ||
| > | 125 | with sqlite3). For loading it reads SQL into an internal sqlite3 | ||
| > | 126 | database (the client must supply libsqlite3), then loads the object | ||
| > | 127 | tree from the database. | ||
| > | 128 | |||
| > | 129 | The caveats associated with this handler are: | ||
| > | 130 | |||
| > | 131 | - It requires libsqlite3 (but that's available almost everywhere). | ||
| > | 132 | |||
| > | 133 | - Wen reading the parser is extremely memory-hungry. It | ||
| > | 134 | unfortunately must buffer its entire SQL input in memory and | ||
| > | 135 | populate an sqlite3 database. Currently that db is in memory, but | ||
| > | 136 | there are plans to extend it to be able to use a file-bound | ||
| > | 137 | database (much slower but also less memory-intensive). | ||
| > | 138 | |||
| > | 139 | @subsection c11n_io_handler_expat The expat format | ||
| > | 140 | |||
| > | 141 | The optional <b>expat</b> handler writes and reads an XML dialect compatible with | ||
| > | 142 | libs11n's format of the same name. It requires | ||
| > | 143 | <a href='http://www.libexpat.org/'>libexpat</a> to do the input parsing. | ||
| > | 144 | |||
| > | 145 | The only significant drawback of this format is that it requires | ||
| > | 146 | that libexpat be installed. That said, many systems use libexpat | ||
| > | 147 | and have it installed. | ||
| > | 148 | */ | ||
| > | 149 | |||
| > | 150 | /** @page c11nconvert c11nconvert | ||
| > | 151 | |||
| > | 152 | The c11nconvert program, included in the c11n source tree, is a very basic tool | ||
| > | 153 | for converting c11n-saved data between arbitrary c11n formats. It supported | ||
| > | 154 | any format which is registered with the c11n i/o API (see @ref c11n_io_formats). | ||
| > | 155 | |||
| > | 156 | It's usage is trivial: | ||
| > | 157 | |||
| > | 158 | @code | ||
| > | 159 | ~> c11nconvert compact < myfile.c11n | ||
| > | 160 | @endcode | ||
| > | 161 | |||
| > | 162 | Will convert the contents of myfile.c11n to the "compact" (a.k.a. "binarish") format | ||
| > | 163 | and send it to stdout. It optionally takes an input file as the second argument: | ||
| > | 164 | |||
| > | 165 | @code | ||
| > | 166 | ~> c11nconvert compact myfile.c11n > output.c11n | ||
| > | 167 | @endcode | ||
| > | 168 | |||
| > | 169 | It doesn't have any options or curious flags, though maybe someday it will. (To be | ||
| > | 170 | honest, i just don't want to have to write the arguments parser.) | ||
| > | 171 | |||
| > | 172 | Since some c11n formats are compatible with formats supported by libs11n, it is | ||
| > | 173 | also possible to use s11nconvert for certain tasks. e.g. if we have a file in | ||
| > | 174 | a format from s11n which is not supported by c11n, we can convert it to the | ||
| > | 175 | binarish format (which both libs support): | ||
| > | 176 | |||
| > | 177 | @code | ||
| > | 178 | ~> s11nconvert -f myfile.s11n -s compact -o outfile.c11n | ||
| > | 179 | @endcode | ||
| > | 180 | |||
| > | 181 | libc11n could then read <tt>outfile.c11n</tt>. | ||
| 88 | 182 | |||
| 89 | */ | 183 | */ | |
| 90 | 184 | |||
| 91 | #include "s11n.net/c11n/c11n.h" | 185 | #include "s11n.net/c11n/c11n.h" | |
| 92 | #ifdef __cplusplus | 186 | #ifdef __cplusplus | |
| 700 hidden lines | ||||
| 793 | #ifdef __cplusplus | 887 | #ifdef __cplusplus | |
| 794 | } /* extern "C" */ | 888 | } /* extern "C" */ | |
| 795 | #endif | 889 | #endif | |
| 796 | 890 | |||
| 797 | #endif // S11N_NET_C11N_IO_H_INCLUDED | 891 | #endif // S11N_NET_C11N_IO_H_INCLUDED | |
Changes to include/s11n.net/c11n/io/c11n_io_handler_expat.h
| Old (fc528579da23b3cc) | New (bbf1d5f2f7a438be) | |||
|---|---|---|---|---|
| 1 | #if !defined(_S11N_NET_C11N_IO_HANDLER_EXPAT_H_INCLUDED_) | 1 | #if !defined(_S11N_NET_C11N_IO_HANDLER_EXPAT_H_INCLUDED_) | |
| 2 | #define _S11N_NET_C11N_IO_HANDLER_EXPAT_H_INCLUDED_ 1 | 2 | #define _S11N_NET_C11N_IO_HANDLER_EXPAT_H_INCLUDED_ 1 | |
| 3 | 3 | |||
| 4 | #include "c11n_io.h" | 4 | #include "c11n_io.h" | |
| 5 | #ifdef __cplusplus | 5 | #ifdef __cplusplus | |
| 6 | extern "C" { | 6 | extern "C" { | |
| 7 | #endif | 7 | #endif | |
| 8 | 8 | |||
| 9 | /** | | | 9 | /** @def C11N_IO_HANDLER_EXPAT_S11N_COMPAT |
| 10 | If c11n is built with C11N_IO_HANDLER_EXPAT_S11N_COMPAT set to true | 10 | If c11n is built with C11N_IO_HANDLER_EXPAT_S11N_COMPAT set to true | |
| 11 | then the expat-based i/o handler works in compatibility more with | | | 11 | then the expat-based i/o handler works in compatibility mode with |
| 12 | libs11n's "expat" format, otherwise we disable compatibility mode. | 12 | libs11n's "expat" format, otherwise we disable compatibility mode. | |
| 13 | Compatibility mode mainly means accommodating a minor mistake in | 13 | Compatibility mode mainly means accommodating a minor mistake in | |
| 14 | the libs11n expat handler's design which causes it to escape more | 14 | the libs11n expat handler's design which causes it to escape more | |
| 15 | characters than are strictly necessary. It also changes the cookie | 15 | characters than are strictly necessary. It also changes the cookie | |
| 16 | used by output files. | 16 | used by output files. | |
| 17 | < | |||
| 18 | Compat mode is turned off by default because it is possible (and | < | ||
| 19 | more efficient) to use the "binarish" format to convert data | < | ||
| 20 | between libs11n and libc11n. | < | ||
| 21 | */ | 17 | */ | |
| 22 | #define C11N_IO_HANDLER_EXPAT_S11N_COMPAT 1 | 18 | #define C11N_IO_HANDLER_EXPAT_S11N_COMPAT 1 | |
| 23 | 19 | |||
| 24 | /** @def C11N_IO_HANDLER_EXPAT_COOKIE | 20 | /** @def C11N_IO_HANDLER_EXPAT_COOKIE | |
| 25 | Unfortunately C11N_IO_HANDLER_EXPAT_COOKIE must be defined as a macro | 21 | Unfortunately C11N_IO_HANDLER_EXPAT_COOKIE must be defined as a macro | |
| 24 hidden lines | ||||
| 50 | 46 | |||
| 51 | #ifdef __cplusplus | 47 | #ifdef __cplusplus | |
| 52 | } /* extern "C" */ | 48 | } /* extern "C" */ | |
| 53 | #endif | 49 | #endif | |
| 54 | #endif /* _S11N_NET_C11N_IO_HANDLER_EXPAT_H_INCLUDED_ */ | 50 | #endif /* _S11N_NET_C11N_IO_HANDLER_EXPAT_H_INCLUDED_ */ | |