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

Comparing CBOR-XS/README (file contents):
Revision 1.5 by root, Sun Oct 27 22:48:12 2013 UTC vs.
Revision 1.7 by root, Tue Oct 29 15:56:31 2013 UTC

… …
21 # data was decoded 21 # data was decoded
22 substr $many_cbor_strings, 0, $length, ""; # remove decoded cbor string 22 substr $many_cbor_strings, 0, $length, ""; # remove decoded cbor string
23 } 23 }
24 24
25DESCRIPTION 25DESCRIPTION
26 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
27 AND EAT YOUR CHILDREN! (Actually, apart from being untested and a bit 27 you to do). Furthermore, details of the implementation might change
28 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.
29 35
30 This module converts Perl data structures to the Concise Binary Object 36 This module converts Perl data structures to the Concise Binary Object
31 Representation (CBOR) and vice versa. CBOR is a fast binary 37 Representation (CBOR) and vice versa. CBOR is a fast binary
32 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,
33 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
34 represent it in CBOR. 40 represent it in CBOR.
35 41
36 This makes it a faster and more compact binary alternative to JSON, with 42 In short, CBOR is a faster and very compact binary alternative to JSON,
37 the added ability of supporting serialising of perl objects. 43 with the added ability of supporting serialisation of Perl objects.
44 (JSON often compresses better than CBOR though, so if you plan to
45 compress the data later you might want to compare both formats first).
38 46
39 The primary goal of this module is to be *correct* and the secondary 47 The primary goal of this module is to be *correct* and the secondary
40 goal is to be *fast*. To reach the latter goal it was written in C. 48 goal is to be *fast*. To reach the latter goal it was written in C.
41 49
42 See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and 50 See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
… …
168 numbers 1 and 0 (for true and false) or to throw an exception on 176 numbers 1 and 0 (for true and false) or to throw an exception on
169 access (for error). See the Types::Serialiser manpage for details. 177 access (for error). See the Types::Serialiser manpage for details.
170 178
171 CBOR tag 256 (perl object) 179 CBOR tag 256 (perl object)
172 The tag value 256 (TODO: pending iana registration) will be used to 180 The tag value 256 (TODO: pending iana registration) will be used to
173 deserialise a Perl object serialised with "FREEZE". See "OBJECT 181 deserialise a Perl object serialised with "FREEZE". See OBJECT
174 SERIALISATION", below, for details. 182 SERIALISATION, below, for details.
175 183
176 CBOR tag 55799 (magic header) 184 CBOR tag 55799 (magic header)
177 The tag 55799 is ignored (this tag implements the magic header). 185 The tag 55799 is ignored (this tag implements the magic header).
178 186
179 other CBOR tags 187 other CBOR tags
… …
212 and 1, which get turned into false and true in CBOR. 220 and 1, which get turned into false and true in CBOR.
213 221
214 CBOR::XS::Tagged objects 222 CBOR::XS::Tagged objects
215 Objects of this type must be arrays consisting of a single "[tag, 223 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 224 value]" pair. The (numerical) tag will be encoded as a CBOR tag, the
217 value will be encoded as appropriate for the value. 225 value will be encoded as appropriate for the value. You cna use
226 "CBOR::XS::tag" to create such objects.
218 227
219 Types::Serialiser::true, Types::Serialiser::false, 228 Types::Serialiser::true, Types::Serialiser::false,
220 Types::Serialiser::error 229 Types::Serialiser::error
221 These special values become CBOR true, CBOR false and CBOR undefined 230 These special values become CBOR true, CBOR false and CBOR undefined
222 values, respectively. You can also use "\1", "\0" and "\undef" 231 values, respectively. You can also use "\1", "\0" and "\undef"
… …
373 382
374 This string is available as $CBOR::XS::MAGIC. This module does not 383 This string is available as $CBOR::XS::MAGIC. This module does not
375 prepend this string tot he CBOR data it generates, but it will ignroe it 384 prepend this string tot he CBOR data it generates, but it will ignroe it
376 if present, so users can prepend this string as a "file type" indicator 385 if present, so users can prepend this string as a "file type" indicator
377 as required. 386 as required.
387
388THE CBOR::XS::Tagged CLASS
389 CBOR has the concept of tagged values - any CBOR value can be tagged
390 with a numeric 64 bit number, which are centrally administered.
391
392 "CBOR::XS" handles a few tags internally when en- or decoding. You can
393 also create tags yourself by encoding "CBOR::XS::Tagged" objects, and
394 the decoder will create "CBOR::XS::Tagged" objects itself when it hits
395 an unknown tag.
396
397 These objects are simply blessed array references - the first member of
398 the array being the numerical tag, the second being the value.
399
400 You can interact with "CBOR::XS::Tagged" objects in the following ways:
401
402 $tagged = CBOR::XS::tag $tag, $value
403 This function(!) creates a new "CBOR::XS::Tagged" object using the
404 given $tag (0..2**64-1) to tag the given $value (which can be any
405 Perl value that can be encoded in CBOR, including serialisable Perl
406 objects and "CBOR::XS::Tagged" objects).
407
408 $tagged->[0]
409 $tagged->[0] = $new_tag
410 $tag = $tagged->tag
411 $new_tag = $tagged->tag ($new_tag)
412 Access/mutate the tag.
413
414 $tagged->[1]
415 $tagged->[1] = $new_value
416 $value = $tagged->value
417 $new_value = $tagged->value ($new_value)
418 Access/mutate the tagged value.
419
420 EXAMPLES
421 Here are some examples of "CBOR::XS::Tagged" uses to tag objects.
422
423 You can look up CBOR tag value and emanings in the IANA registry at
424 <http://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml>.
425
426 Prepend a magic header ($CBOR::XS::MAGIC):
427
428 my $cbor = encode_cbor CBOR::XS::tag 55799, $value;
429 # same as:
430 my $cbor = $CBOR::XS::MAGIC . encode_cbor $value;
431
432 Serialise some URIs and a regex in an array:
433
434 my $cbor = encode_cbor [
435 (CBOR::XS::tag 32, "http://www.nethype.de/"),
436 (CBOR::XS::tag 32, "http://software.schmorp.de/"),
437 (CBOR::XS::tag 35, "^[Pp][Ee][Rr][lL]\$"),
438 ];
439
440 Wrap CBOR data in CBOR:
441
442 my $cbor_cbor = encode_cbor
443 CBOR::XS::tag 24,
444 encode_cbor [1, 2, 3];
378 445
379CBOR and JSON 446CBOR and JSON
380 CBOR is supposed to implement a superset of the JSON data model, and is, 447 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 448 with some coercion, able to represent all JSON texts (something that
382 other "binary JSON" formats such as BSON generally do not support). 449 other "binary JSON" formats such as BSON generally do not support).

Diff Legend

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