ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/CBOR-XS/README
(Generate patch)

Comparing CBOR-XS/README (file contents):
Revision 1.3 by root, Sat Oct 26 11:08:34 2013 UTC vs.
Revision 1.5 by root, Sun Oct 27 22:48:12 2013 UTC

… …
8 $perl_value = decode_cbor $binary_cbor_data; 8 $perl_value = decode_cbor $binary_cbor_data;
9 9
10 # OO-interface 10 # OO-interface
11 11
12 $coder = CBOR::XS->new; 12 $coder = CBOR::XS->new;
13 #TODO 13 $binary_cbor_data = $coder->encode ($perl_value);
14 $perl_value = $coder->decode ($binary_cbor_data);
15
16 # prefix decoding
17
18 my $many_cbor_strings = ...;
19 while (length $many_cbor_strings) {
20 my ($data, $length) = $cbor->decode_prefix ($many_cbor_strings);
21 # data was decoded
22 substr $many_cbor_strings, 0, $length, ""; # remove decoded cbor string
23 }
14 24
15DESCRIPTION 25DESCRIPTION
16 WARNING! THIS IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA 26 WARNING! THIS IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA
17 AND EAT YOUR CHILDREN! 27 AND EAT YOUR CHILDREN! (Actually, apart from being untested and a bit
28 feature-limited, it might already be useful).
18 29
19 This module converts Perl data structures to CBOR and vice versa. Its 30 This module converts Perl data structures to the Concise Binary Object
20 primary goal is to be *correct* and its secondary goal is to be *fast*. 31 Representation (CBOR) and vice versa. CBOR is a fast binary
32 serialisation format that aims to use a superset of the JSON data model,
33 i.e. when you can represent something in JSON, you should be able to
34 represent it in CBOR.
35
36 This makes it a faster and more compact binary alternative to JSON, with
37 the added ability of supporting serialising of perl objects.
38
39 The primary goal of this module is to be *correct* and the secondary
21 To reach the latter goal it was written in C. 40 goal is to be *fast*. To reach the latter goal it was written in C.
22 41
23 See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and 42 See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
24 vice versa. 43 vice versa.
25 44
26FUNCTIONAL INTERFACE 45FUNCTIONAL INTERFACE
… …
118 For the more enlightened: note that in the following descriptions, 137 For the more enlightened: note that in the following descriptions,
119 lowercase *perl* refers to the Perl interpreter, while uppercase *Perl* 138 lowercase *perl* refers to the Perl interpreter, while uppercase *Perl*
120 refers to the abstract Perl language itself. 139 refers to the abstract Perl language itself.
121 140
122 CBOR -> PERL 141 CBOR -> PERL
123 True, False 142 integers
124 These CBOR values become "CBOR::XS::true" and "CBOR::XS::false", 143 CBOR integers become (numeric) perl scalars. On perls without 64 bit
144 support, 64 bit integers will be truncated or otherwise corrupted.
145
146 byte strings
147 Byte strings will become octet strings in Perl (the byte values
148 0..255 will simply become characters of the same value in Perl).
149
150 UTF-8 strings
151 UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be
152 decoded into proper Unicode code points. At the moment, the validity
153 of the UTF-8 octets will not be validated - corrupt input will
154 result in corrupted Perl strings.
155
156 arrays, maps
157 CBOR arrays and CBOR maps will be converted into references to a
158 Perl array or hash, respectively. The keys of the map will be
159 stringified during this process.
160
161 null
162 CBOR null becomes "undef" in Perl.
163
164 true, false, undefined
165 These CBOR values become "Types:Serialiser::true",
166 "Types:Serialiser::false" and "Types::Serialiser::error",
125 respectively. They are overloaded to act almost exactly like the 167 respectively. They are overloaded to act almost exactly like the
126 numbers 1 and 0. You can check whether a scalar is a CBOR boolean by 168 numbers 1 and 0 (for true and false) or to throw an exception on
127 using the "CBOR::XS::is_bool" function. 169 access (for error). See the Types::Serialiser manpage for details.
128 170
129 Null, Undefined 171 CBOR tag 256 (perl object)
130 CBOR Null and Undefined values becomes "undef" in Perl (in the 172 The tag value 256 (TODO: pending iana registration) will be used to
131 future, Undefined may raise an exception). 173 deserialise a Perl object serialised with "FREEZE". See "OBJECT
174 SERIALISATION", below, for details.
175
176 CBOR tag 55799 (magic header)
177 The tag 55799 is ignored (this tag implements the magic header).
178
179 other CBOR tags
180 Tagged items consists of a numeric tag and another CBOR value. Tags
181 not handled internally are currently converted into a
182 CBOR::XS::Tagged object, which is simply a blessed array reference
183 consisting of the numeric tag value followed by the (decoded) CBOR
184 value.
185
186 In the future, support for user-supplied conversions might get
187 added.
188
189 anything else
190 Anything else (e.g. unsupported simple values) will raise a decoding
191 error.
132 192
133 PERL -> CBOR 193 PERL -> CBOR
134 The mapping from Perl to CBOR is slightly more difficult, as Perl is a 194 The mapping from Perl to CBOR is slightly more difficult, as Perl is a
135 truly typeless language, so we can only guess which CBOR type is meant 195 truly typeless language, so we can only guess which CBOR type is meant
136 by a Perl value. 196 by a Perl value.
… …
138 hash references 198 hash references
139 Perl hash references become CBOR maps. As there is no inherent 199 Perl hash references become CBOR maps. As there is no inherent
140 ordering in hash keys (or CBOR maps), they will usually be encoded 200 ordering in hash keys (or CBOR maps), they will usually be encoded
141 in a pseudo-random order. 201 in a pseudo-random order.
142 202
203 Currently, tied hashes will use the indefinite-length format, while
204 normal hashes will use the fixed-length format.
205
143 array references 206 array references
144 Perl array references become CBOR arrays. 207 Perl array references become fixed-length CBOR arrays.
145 208
146 other references 209 other references
147 Other unblessed references are generally not allowed and will cause 210 Other unblessed references are generally not allowed and will cause
148 an exception to be thrown, except for references to the integers 0 211 an exception to be thrown, except for references to the integers 0
149 and 1, which get turned into "False" and "True" in CBOR. 212 and 1, which get turned into false and true in CBOR.
150 213
151 CBOR::XS::true, CBOR::XS::false 214 CBOR::XS::Tagged objects
215 Objects of this type must be arrays consisting of a single "[tag,
216 value]" pair. The (numerical) tag will be encoded as a CBOR tag, the
217 value will be encoded as appropriate for the value.
218
219 Types::Serialiser::true, Types::Serialiser::false,
220 Types::Serialiser::error
152 These special values become CBOR True and CBOR False values, 221 These special values become CBOR true, CBOR false and CBOR undefined
153 respectively. You can also use "\1" and "\0" directly if you want. 222 values, respectively. You can also use "\1", "\0" and "\undef"
223 directly if you want.
154 224
155 blessed objects 225 other blessed objects
156 Blessed objects are not directly representable in CBOR. TODO See the 226 Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See
157 "allow_blessed" and "convert_blessed" methods on various options on 227 "OBJECT SERIALISATION", below, for details.
158 how to deal with this: basically, you can choose between throwing an
159 exception, encoding the reference as if it weren't blessed, or
160 provide your own serialiser method.
161 228
162 simple scalars 229 simple scalars
163 TODO Simple Perl scalars (any scalar that is not a reference) are 230 TODO Simple Perl scalars (any scalar that is not a reference) are
164 the most difficult objects to encode: CBOR::XS will encode undefined 231 the most difficult objects to encode: CBOR::XS will encode undefined
165 scalars as CBOR "Null" values, scalars that have last been used in a 232 scalars as CBOR null values, scalars that have last been used in a
166 string context before encoding as CBOR strings, and anything else as 233 string context before encoding as CBOR strings, and anything else as
167 number value: 234 number value:
168 235
169 # dump as number 236 # dump as number
170 encode_cbor [2] # yields [2] 237 encode_cbor [2] # yields [2]
… …
193 260
194 You can not currently force the type in other, less obscure, ways. 261 You can not currently force the type in other, less obscure, ways.
195 Tell me if you need this capability (but don't forget to explain why 262 Tell me if you need this capability (but don't forget to explain why
196 it's needed :). 263 it's needed :).
197 264
198 Note that numerical precision has the same meaning as under Perl (so 265 Perl values that seem to be integers generally use the shortest
199 binary to decimal conversion follows the same rules as in Perl, 266 possible representation. Floating-point values will use either the
200 which can differ to other languages). Also, your perl interpreter 267 IEEE single format if possible without loss of precision, otherwise
201 might expose extensions to the floating point numbers of your 268 the IEEE double format will be used. Perls that use formats other
202 platform, such as infinities or NaN's - these cannot be represented 269 than IEEE double to represent numerical values are supported, but
203 in CBOR, and it is an error to pass those in. 270 might suffer loss of precision.
204 271
272 OBJECT SERIALISATION
273 This module knows two way to serialise a Perl object: The CBOR-specific
274 way, and the generic way.
275
276 Whenever the encoder encounters a Perl object that it cnanot serialise
277 directly (most of them), it will first look up the "TO_CBOR" method on
278 it.
279
280 If it has a "TO_CBOR" method, it will call it with the object as only
281 argument, and expects exactly one return value, which it will then
282 substitute and encode it in the place of the object.
283
284 Otherwise, it will look up the "FREEZE" method. If it exists, it will
285 call it with the object as first argument, and the constant string
286 "CBOR" as the second argument, to distinguish it from other serialisers.
287
288 The "FREEZE" method can return any number of values (i.e. zero or more).
289 These will be encoded as CBOR perl object, together with the classname.
290
291 If an object supports neither "TO_CBOR" nor "FREEZE", encoding will fail
292 with an error.
293
294 Objects encoded via "TO_CBOR" cannot be automatically decoded, but
295 objects encoded via "FREEZE" can be decoded using the following
296 protocol:
297
298 When an encoded CBOR perl object is encountered by the decoder, it will
299 look up the "THAW" method, by using the stored classname, and will fail
300 if the method cannot be found.
301
302 After the lookup it will call the "THAW" method with the stored
303 classname as first argument, the constant string "CBOR" as second
304 argument, and all values returned by "FREEZE" as remaining arguments.
305
306 EXAMPLES
307 Here is an example "TO_CBOR" method:
308
309 sub My::Object::TO_CBOR {
310 my ($obj) = @_;
311
312 ["this is a serialised My::Object object", $obj->{id}]
313 }
314
315 When a "My::Object" is encoded to CBOR, it will instead encode a simple
316 array with two members: a string, and the "object id". Decoding this
317 CBOR string will yield a normal perl array reference in place of the
318 object.
319
320 A more useful and practical example would be a serialisation method for
321 the URI module. CBOR has a custom tag value for URIs, namely 32:
322
323 sub URI::TO_CBOR {
324 my ($self) = @_;
325 my $uri = "$self"; # stringify uri
326 utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string
327 CBOR::XS::tagged 32, "$_[0]"
328 }
329
330 This will encode URIs as a UTF-8 string with tag 32, which indicates an
331 URI.
332
333 Decoding such an URI will not (currently) give you an URI object, but
334 instead a CBOR::XS::Tagged object with tag number 32 and the string -
335 exactly what was returned by "TO_CBOR".
336
337 To serialise an object so it can automatically be deserialised, you need
338 to use "FREEZE" and "THAW". To take the URI module as example, this
339 would be a possible implementation:
340
341 sub URI::FREEZE {
342 my ($self, $serialiser) = @_;
343 "$self" # encode url string
344 }
345
346 sub URI::THAW {
347 my ($class, $serialiser, $uri) = @_;
348
349 $class->new ($uri)
350 }
351
352 Unlike "TO_CBOR", multiple values can be returned by "FREEZE". For
353 example, a "FREEZE" method that returns "type", "id" and "variant"
354 values would cause an invocation of "THAW" with 5 arguments:
355
356 sub My::Object::FREEZE {
357 my ($self, $serialiser) = @_;
358
359 ($self->{type}, $self->{id}, $self->{variant})
360 }
361
362 sub My::Object::THAW {
363 my ($class, $serialiser, $type, $id, $variant) = @_;
364
365 $class-<new (type => $type, id => $id, variant => $variant)
366 }
367
205 MAGIC HEADER 368MAGIC HEADER
206 There is no way to distinguish CBOR from other formats programmatically. 369 There is no way to distinguish CBOR from other formats programmatically.
207 To make it easier to distinguish CBOR from other formats, the CBOR 370 To make it easier to distinguish CBOR from other formats, the CBOR
208 specification has a special "magic string" that can be prepended to any 371 specification has a special "magic string" that can be prepended to any
209 CBOR string without changing it's meaning. 372 CBOR string without changing it's meaning.
210 373
211 This string is available as $CBOR::XS::MAGIC. This module does not 374 This string is available as $CBOR::XS::MAGIC. This module does not
212 prepend this string tot he CBOR data it generates, but it will ignroe it 375 prepend this string tot he CBOR data it generates, but it will ignroe it
213 if present, so users can prepend this string as a "file type" indicator 376 if present, so users can prepend this string as a "file type" indicator
214 as required. 377 as required.
215 378
216 CBOR and JSON 379CBOR and JSON
217 TODO 380 CBOR is supposed to implement a superset of the JSON data model, and is,
381 with some coercion, able to represent all JSON texts (something that
382 other "binary JSON" formats such as BSON generally do not support).
383
384 CBOR implements some extra hints and support for JSON interoperability,
385 and the spec offers further guidance for conversion between CBOR and
386 JSON. None of this is currently implemented in CBOR, and the guidelines
387 in the spec do not result in correct round-tripping of data. If JSON
388 interoperability is improved in the future, then the goal will be to
389 ensure that decoded JSON data will round-trip encoding and decoding to
390 CBOR intact.
218 391
219SECURITY CONSIDERATIONS 392SECURITY CONSIDERATIONS
220 When you are using CBOR in a protocol, talking to untrusted potentially 393 When you are using CBOR in a protocol, talking to untrusted potentially
221 hostile creatures requires relatively few measures. 394 hostile creatures requires relatively few measures.
222 395
… …
285 458
286SEE ALSO 459SEE ALSO
287 The JSON and JSON::XS modules that do similar, but human-readable, 460 The JSON and JSON::XS modules that do similar, but human-readable,
288 serialisation. 461 serialisation.
289 462
463 The Types::Serialiser module provides the data model for true, false and
464 error values.
465
290AUTHOR 466AUTHOR
291 Marc Lehmann <schmorp@schmorp.de> 467 Marc Lehmann <schmorp@schmorp.de>
292 http://home.schmorp.de/ 468 http://home.schmorp.de/
293 469

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines