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

Comparing CBOR-XS/README (file contents):
Revision 1.4 by root, Sat Oct 26 23:02:55 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! (Actually, apart from being untested and a bit 27 you to do). Furthermore, details of the implementation might change
18 feature-limited, it might already be useful). 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.
33
34 You are still invited to try out CBOR, and this module.
19 35
20 This module converts Perl data structures to the Concise Binary Object 36 This module converts Perl data structures to the Concise Binary Object
21 Representation (CBOR) and vice versa. CBOR is a fast binary 37 Representation (CBOR) and vice versa. CBOR is a fast binary
22 serialisation format that aims to use a superset of the JSON data model, 38 serialisation format that aims to use a superset of the JSON data model,
23 i.e. when you can represent something in JSON, you should be able to 39 i.e. when you can represent something in JSON, you should be able to
24 represent it in CBOR. 40 represent it in CBOR.
25 41
26 This makes it a faster and more compact binary alternative to JSON. 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.
27 44
28 The primary goal of this module is to be *correct* and the secondary 45 The primary goal of this module is to be *correct* and the secondary
29 goal is to be *fast*. 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.
30 47
31 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
… …
145 arrays, maps 162 arrays, maps
146 CBOR arrays and CBOR maps will be converted into references to a 163 CBOR arrays and CBOR maps will be converted into references to a
147 Perl array or hash, respectively. The keys of the map will be 164 Perl array or hash, respectively. The keys of the map will be
148 stringified during this process. 165 stringified during this process.
149 166
150 true, false 167 null
151 These CBOR values become "CBOR::XS::true" and "CBOR::XS::false", 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",
152 respectively. They are overloaded to act almost exactly like the 173 respectively. They are overloaded to act almost exactly like the
153 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
154 using the "CBOR::XS::is_bool" function. 175 access (for error). See the Types::Serialiser manpage for details.
155 176
156 null, undefined 177 CBOR tag 256 (perl object)
157 CBOR null and undefined values becomes "undef" in Perl (in the 178 The tag value 256 (TODO: pending iana registration) will be used to
158 future, Undefined may raise an exception or something else). 179 deserialise a Perl object serialised with "FREEZE". See "OBJECT
180 SERIALISATION", below, for details.
159 181
160 tags 182 CBOR tag 55799 (magic header)
161 Tagged items consists of a numeric tag and another CBOR value. The
162 tag 55799 is ignored (this tag implements the magic header). 183 The tag 55799 is ignored (this tag implements the magic header).
163 184
164 All other tags are currently converted into a CBOR::XS::Tagged 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
165 object, which is simply a blessed array reference consistsing of the 188 CBOR::XS::Tagged object, which is simply a blessed array reference
166 numeric tag value followed by the (decoded) BOR value. 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.
167 194
168 anything else 195 anything else
169 Anything else (e.g. unsupported simple values) will raise a decoding 196 Anything else (e.g. unsupported simple values) will raise a decoding
170 error. 197 error.
171 198
… …
193 CBOR::XS::Tagged objects 220 CBOR::XS::Tagged objects
194 Objects of this type must be arrays consisting of a single "[tag, 221 Objects of this type must be arrays consisting of a single "[tag,
195 value]" pair. The (numerical) tag will be encoded as a CBOR tag, the 222 value]" pair. The (numerical) tag will be encoded as a CBOR tag, the
196 value will be encoded as appropriate for the value. 223 value will be encoded as appropriate for the value.
197 224
198 CBOR::XS::true, CBOR::XS::false 225 Types::Serialiser::true, Types::Serialiser::false,
226 Types::Serialiser::error
199 These special values become CBOR true and CBOR false values, 227 These special values become CBOR true, CBOR false and CBOR undefined
200 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.
201 230
202 blessed objects 231 other blessed objects
203 Other blessed objects currently need to have a "TO_CBOR" method. It 232 Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See
204 will be called on every object that is being serialised, and must 233 "OBJECT SERIALISATION", below, for details.
205 return something that can be encoded in CBOR.
206 234
207 simple scalars 235 simple scalars
208 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
209 the most difficult objects to encode: CBOR::XS will encode undefined 237 the most difficult objects to encode: CBOR::XS will encode undefined
210 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
… …
245 IEEE single format if possible without loss of precision, otherwise 273 IEEE single format if possible without loss of precision, otherwise
246 the IEEE double format will be used. Perls that use formats other 274 the IEEE double format will be used. Perls that use formats other
247 than IEEE double to represent numerical values are supported, but 275 than IEEE double to represent numerical values are supported, but
248 might suffer loss of precision. 276 might suffer loss of precision.
249 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
250 MAGIC HEADER 374MAGIC HEADER
251 There is no way to distinguish CBOR from other formats programmatically. 375 There is no way to distinguish CBOR from other formats programmatically.
252 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
253 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
254 CBOR string without changing it's meaning. 378 CBOR string without changing it's meaning.
255 379
256 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
257 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
258 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
259 as required. 383 as required.
260 384
261 CBOR and JSON 385CBOR and JSON
262 CBOR is supposed to implement a superset of the JSON data model, and is, 386 CBOR is supposed to implement a superset of the JSON data model, and is,
263 with some coercion, able to represent all JSON texts (something that 387 with some coercion, able to represent all JSON texts (something that
264 other "binary JSON" formats such as BSON generally do not support). 388 other "binary JSON" formats such as BSON generally do not support).
265 389
266 CBOR implements some extra hints and support for JSON interoperability, 390 CBOR implements some extra hints and support for JSON interoperability,
… …
340 464
341SEE ALSO 465SEE ALSO
342 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,
343 serialisation. 467 serialisation.
344 468
469 The Types::Serialiser module provides the data model for true, false and
470 error values.
471
345AUTHOR 472AUTHOR
346 Marc Lehmann <schmorp@schmorp.de> 473 Marc Lehmann <schmorp@schmorp.de>
347 http://home.schmorp.de/ 474 http://home.schmorp.de/
348 475

Diff Legend

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