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

Diff Legend

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