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

Comparing CBOR-XS/README (file contents):
Revision 1.7 by root, Tue Oct 29 15:56:31 2013 UTC vs.
Revision 1.9 by root, Fri Nov 22 16:18:59 2013 UTC

… …
23 } 23 }
24 24
25DESCRIPTION 25DESCRIPTION
26 WARNING! This module is very new, and not very well tested (that's up to 26 WARNING! This module is very new, and not very well tested (that's up to
27 you to do). Furthermore, details of the implementation might change 27 you to do). Furthermore, details of the implementation might change
28 freely before version 1.0. And lastly, the object serialisation protocol 28 freely before version 1.0. And lastly, most extensions depend on an IANA
29 depends on a pending IANA assignment, and until that assignment is 29 assignment, and until that assignment is official, this implementation
30 official, this implementation is not interoperable with other 30 is not interoperable with other implementations (even future versions of
31 implementations (even future versions of this module) until the 31 this module) until the assignment is done.
32 assignment is done.
33 32
34 You are still invited to try out CBOR, and this module. 33 You are still invited to try out CBOR, and this module.
35 34
36 This module converts Perl data structures to the Concise Binary Object 35 This module converts Perl data structures to the Concise Binary Object
37 Representation (CBOR) and vice versa. CBOR is a fast binary 36 Representation (CBOR) and vice versa. CBOR is a fast binary
… …
42 In short, CBOR is a faster and very compact binary alternative to JSON, 41 In short, CBOR is a faster and very compact binary alternative to JSON,
43 with the added ability of supporting serialisation of Perl objects. 42 with the added ability of supporting serialisation of Perl objects.
44 (JSON often compresses better than CBOR though, so if you plan to 43 (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). 44 compress the data later you might want to compare both formats first).
46 45
46 To give you a general idea about speed, with texts in the megabyte
47 range, "CBOR::XS" usually encodes roughly twice as fast as Storable or
48 JSON::XS and decodes about 15%-30% faster than those. The shorter the
49 data, the worse Storable performs in comparison.
50
51 As for compactness, "CBOR::XS" encoded data structures are usually about
52 20% smaller than the same data encoded as (compact) JSON or Storable.
53
54 In addition to the core CBOR data format, this module implements a
55 number of extensions, to support cyclic and self-referencing data
56 structures (see "allow_sharing"), string deduplication (see
57 "allow_stringref") and scalar references (always enabled).
58
47 The primary goal of this module is to be *correct* and the secondary 59 The primary goal of this module is to be *correct* and the secondary
48 goal is to be *fast*. To reach the latter goal it was written in C. 60 goal is to be *fast*. To reach the latter goal it was written in C.
49 61
50 See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and 62 See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
51 vice versa. 63 vice versa.
… …
72 *disabled*. 84 *disabled*.
73 85
74 The mutators for flags all return the CBOR object again and thus 86 The mutators for flags all return the CBOR object again and thus
75 calls can be chained: 87 calls can be chained:
76 88
77 #TODO my $cbor = CBOR::XS->new->encode ({a => [1,2]}); 89 my $cbor = CBOR::XS->new->encode ({a => [1,2]});
78 90
79 $cbor = $cbor->max_depth ([$maximum_nesting_depth]) 91 $cbor = $cbor->max_depth ([$maximum_nesting_depth])
80 $max_depth = $cbor->get_max_depth 92 $max_depth = $cbor->get_max_depth
81 Sets the maximum nesting level (default 512) accepted while encoding 93 Sets the maximum nesting level (default 512) accepted while encoding
82 or decoding. If a higher nesting level is detected in CBOR data or a 94 or decoding. If a higher nesting level is detected in CBOR data or a
… …
113 as when 0 is specified). 125 as when 0 is specified).
114 126
115 See SECURITY CONSIDERATIONS, below, for more info on why this is 127 See SECURITY CONSIDERATIONS, below, for more info on why this is
116 useful. 128 useful.
117 129
130 $cbor = $cbor->allow_unknown ([$enable])
131 $enabled = $cbor->get_allow_unknown
132 If $enable is true (or missing), then "encode" will *not* throw an
133 exception when it encounters values it cannot represent in CBOR (for
134 example, filehandles) but instead will encode a CBOR "error" value.
135
136 If $enable is false (the default), then "encode" will throw an
137 exception when it encounters anything it cannot encode as CBOR.
138
139 This option does not affect "decode" in any way, and it is
140 recommended to leave it off unless you know your communications
141 partner.
142
143 $cbor = $cbor->allow_sharing ([$enable])
144 $enabled = $cbor->get_allow_sharing
145 If $enable is true (or missing), then "encode" will not
146 double-encode values that have been referenced before (e.g. when the
147 same object, such as an array, is referenced multiple times), but
148 instead will emit a reference to the earlier value.
149
150 This means that such values will only be encoded once, and will not
151 result in a deep cloning of the value on decode, in decoders
152 supporting the value sharing extension.
153
154 It is recommended to leave it off unless you know your communication
155 partner supports the value sharing extensions to CBOR
156 (http://cbor.schmorp.de/value-sharing).
157
158 Detecting shared values incurs a runtime overhead when values are
159 encoded that have a reference counter large than one, and might
160 unnecessarily increase the encoded size, as potentially shared
161 values are encode as sharable whether or not they are actually
162 shared.
163
164 At the moment, only targets of references can be shared (e.g.
165 scalars, arrays or hashes pointed to by a reference). Weirder
166 constructs, such as an array with multiple "copies" of the *same*
167 string, which are hard but not impossible to create in Perl, are not
168 supported (this is the same as for Storable).
169
170 If $enable is false (the default), then "encode" will encode
171 exception when it encounters anything it cannot encode as CBOR.
172
173 This option does not affect "decode" in any way - shared values and
174 references will always be decoded properly if present.
175
176 $cbor = $cbor->allow_stringref ([$enable])
177 $enabled = $cbor->get_allow_stringref
178 If $enable is true (or missing), then "encode" will try not to
179 encode the same string twice, but will instead encode a reference to
180 the string instead. Depending on your data format. this can save a
181 lot of space, but also results in a very large runtime overhead
182 (expect encoding times to be 2-4 times as high as without).
183
184 It is recommended to leave it off unless you know your
185 communications partner supports the stringref extension to CBOR
186 (http://cbor.schmorp.de/stringref).
187
188 If $enable is false (the default), then "encode" will encode
189 exception when it encounters anything it cannot encode as CBOR.
190
191 This option does not affect "decode" in any way - string references
192 will always be decoded properly if present.
193
194 $cbor = $cbor->filter ([$cb->($tag, $value)])
195 $cb_or_undef = $cbor->get_filter
196 Sets or replaces the tagged value decoding filter (when $cb is
197 specified) or clears the filter (if no argument or "undef" is
198 provided).
199
200 The filter callback is called only during decoding, when a
201 non-enforced tagged value has been decoded (see "TAG HANDLING AND
202 EXTENSIONS" for a list of enforced tags). For specific tags, it's
203 often better to provide a default converter using the
204 %CBOR::XS::FILTER hash (see below).
205
206 The first argument is the numerical tag, the second is the (decoded)
207 value that has been tagged.
208
209 The filter function should return either exactly one value, which
210 will replace the tagged value in the decoded data structure, or no
211 values, which will result in default handling, which currently means
212 the decoder creates a "CBOR::XS::Tagged" object to hold the tag and
213 the value.
214
215 When the filter is cleared (the default state), the default filter
216 function, "CBOR::XS::default_filter", is used. This function simply
217 looks up the tag in the %CBOR::XS::FILTER hash. If an entry exists
218 it must be a code reference that is called with tag and value, and
219 is responsible for decoding the value. If no entry exists, it
220 returns no values.
221
222 Example: decode all tags not handled internally into
223 CBOR::XS::Tagged objects, with no other special handling (useful
224 when working with potentially "unsafe" CBOR data).
225
226 CBOR::XS->new->filter (sub { })->decode ($cbor_data);
227
228 Example: provide a global filter for tag 1347375694, converting the
229 value into some string form.
230
231 $CBOR::XS::FILTER{1347375694} = sub {
232 my ($tag, $value);
233
234 "tag 1347375694 value $value"
235 };
236
118 $cbor_data = $cbor->encode ($perl_scalar) 237 $cbor_data = $cbor->encode ($perl_scalar)
119 Converts the given Perl data structure (a scalar value) to its CBOR 238 Converts the given Perl data structure (a scalar value) to its CBOR
120 representation. 239 representation.
121 240
122 $perl_scalar = $cbor->decode ($cbor_data) 241 $perl_scalar = $cbor->decode ($cbor_data)
… …
174 "Types:Serialiser::false" and "Types::Serialiser::error", 293 "Types:Serialiser::false" and "Types::Serialiser::error",
175 respectively. They are overloaded to act almost exactly like the 294 respectively. They are overloaded to act almost exactly like the
176 numbers 1 and 0 (for true and false) or to throw an exception on 295 numbers 1 and 0 (for true and false) or to throw an exception on
177 access (for error). See the Types::Serialiser manpage for details. 296 access (for error). See the Types::Serialiser manpage for details.
178 297
179 CBOR tag 256 (perl object) 298 tagged values
180 The tag value 256 (TODO: pending iana registration) will be used to
181 deserialise a Perl object serialised with "FREEZE". See OBJECT
182 SERIALISATION, below, for details.
183
184 CBOR tag 55799 (magic header)
185 The tag 55799 is ignored (this tag implements the magic header).
186
187 other CBOR tags
188 Tagged items consists of a numeric tag and another CBOR value. Tags 299 Tagged items consists of a numeric tag and another CBOR value.
189 not handled internally are currently converted into a
190 CBOR::XS::Tagged object, which is simply a blessed array reference
191 consisting of the numeric tag value followed by the (decoded) CBOR
192 value.
193 300
194 In the future, support for user-supplied conversions might get 301 See "TAG HANDLING AND EXTENSIONS" and the description of "->filter"
195 added. 302 for details.
196 303
197 anything else 304 anything else
198 Anything else (e.g. unsupported simple values) will raise a decoding 305 Anything else (e.g. unsupported simple values) will raise a decoding
199 error. 306 error.
200 307
… …
231 values, respectively. You can also use "\1", "\0" and "\undef" 338 values, respectively. You can also use "\1", "\0" and "\undef"
232 directly if you want. 339 directly if you want.
233 340
234 other blessed objects 341 other blessed objects
235 Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See 342 Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See
236 "OBJECT SERIALISATION", below, for details. 343 "TAG HANDLING AND EXTENSIONS" for specific classes handled by this
344 module, and "OBJECT SERIALISATION" for generic object serialisation.
237 345
238 simple scalars 346 simple scalars
239 TODO Simple Perl scalars (any scalar that is not a reference) are 347 Simple Perl scalars (any scalar that is not a reference) are the
240 the most difficult objects to encode: CBOR::XS will encode undefined 348 most difficult objects to encode: CBOR::XS will encode undefined
241 scalars as CBOR null values, scalars that have last been used in a 349 scalars as CBOR null values, scalars that have last been used in a
242 string context before encoding as CBOR strings, and anything else as 350 string context before encoding as CBOR strings, and anything else as
243 number value: 351 number value:
244 352
245 # dump as number 353 # dump as number
… …
376 484
377MAGIC HEADER 485MAGIC HEADER
378 There is no way to distinguish CBOR from other formats programmatically. 486 There is no way to distinguish CBOR from other formats programmatically.
379 To make it easier to distinguish CBOR from other formats, the CBOR 487 To make it easier to distinguish CBOR from other formats, the CBOR
380 specification has a special "magic string" that can be prepended to any 488 specification has a special "magic string" that can be prepended to any
381 CBOR string without changing it's meaning. 489 CBOR string without changing its meaning.
382 490
383 This string is available as $CBOR::XS::MAGIC. This module does not 491 This string is available as $CBOR::XS::MAGIC. This module does not
384 prepend this string tot he CBOR data it generates, but it will ignroe it 492 prepend this string to the CBOR data it generates, but it will ignore it
385 if present, so users can prepend this string as a "file type" indicator 493 if present, so users can prepend this string as a "file type" indicator
386 as required. 494 as required.
387 495
388THE CBOR::XS::Tagged CLASS 496THE CBOR::XS::Tagged CLASS
389 CBOR has the concept of tagged values - any CBOR value can be tagged 497 CBOR has the concept of tagged values - any CBOR value can be tagged
… …
440 Wrap CBOR data in CBOR: 548 Wrap CBOR data in CBOR:
441 549
442 my $cbor_cbor = encode_cbor 550 my $cbor_cbor = encode_cbor
443 CBOR::XS::tag 24, 551 CBOR::XS::tag 24,
444 encode_cbor [1, 2, 3]; 552 encode_cbor [1, 2, 3];
553
554TAG HANDLING AND EXTENSIONS
555 This section describes how this module handles specific tagged values
556 and extensions. If a tag is not mentioned here and no additional filters
557 are provided for it, then the default handling applies (creating a
558 CBOR::XS::Tagged object on decoding, and only encoding the tag when
559 explicitly requested).
560
561 Tags not handled specifically are currently converted into a
562 CBOR::XS::Tagged object, which is simply a blessed array reference
563 consisting of the numeric tag value followed by the (decoded) CBOR
564 value.
565
566 Future versions of this module reserve the right to special case
567 additional tags (such as base64url).
568
569 ENFORCED TAGS
570 These tags are always handled when decoding, and their handling cannot
571 be overriden by the user.
572
573 <unassigned> (perl-object, <http://cbor.schmorp.de/perl-object>)
574 These tags are automatically created (and decoded) for serialisable
575 objects using the "FREEZE/THAW" methods (the Types::Serialier object
576 serialisation protocol). See "OBJECT SERIALISATION" for details.
577
578 <unassigned>, <unassigned> (sharable, sharedref, L
579 <http://cbor.schmorp.de/value-sharing>)
580 These tags are automatically decoded when encountered, resulting in
581 shared values in the decoded object. They are only encoded, however,
582 when "allow_sharable" is enabled.
583
584 <unassigned>, <unassigned> (stringref-namespace, stringref, L
585 <http://cbor.schmorp.de/stringref>)
586 These tags are automatically decoded when encountered. They are only
587 encoded, however, when "allow_stringref" is enabled.
588
589 22098 (indirection, <http://cbor.schmorp.de/indirection>)
590 This tag is automatically generated when a reference are encountered
591 (with the exception of hash and array refernces). It is converted to
592 a reference when decoding.
593
594 55799 (self-describe CBOR, RFC 7049)
595 This value is not generated on encoding (unless explicitly requested
596 by the user), and is simply ignored when decoding.
597
598 NON-ENFORCED TAGS
599 These tags have default filters provided when decoding. Their handling
600 can be overriden by changing the %CBOR::XS::FILTER entry for the tag, or
601 by providing a custom "filter" callback when decoding.
602
603 When they result in decoding into a specific Perl class, the module
604 usually provides a corresponding "TO_CBOR" method as well.
605
606 When any of these need to load additional modules that are not part of
607 the perl core distribution (e.g. URI), it is (currently) up to the user
608 to provide these modules. The decoding usually fails with an exception
609 if the required module cannot be loaded.
610
611 2, 3 (positive/negative bignum)
612 These tags are decoded into Math::BigInt objects. The corresponding
613 "Math::BigInt::TO_CBOR" method encodes "small" bigints into normal
614 CBOR integers, and others into positive/negative CBOR bignums.
615
616 4, 5 (decimal fraction/bigfloat)
617 Both decimal fractions and bigfloats are decoded into Math::BigFloat
618 objects. The corresponding "Math::BigFloat::TO_CBOR" method *always*
619 encodes into a decimal fraction.
620
621 CBOR cannot represent bigfloats with *very* large exponents -
622 conversion of such big float objects is undefined.
623
624 Also, NaN and infinities are not encoded properly.
625
626 21, 22, 23 (expected later JSON conversion)
627 CBOR::XS is not a CBOR-to-JSON converter, and will simply ignore
628 these tags.
629
630 32 (URI)
631 These objects decode into URI objects. The corresponding
632 "URI::TO_CBOR" method again results in a CBOR URI value.
445 633
446CBOR and JSON 634CBOR and JSON
447 CBOR is supposed to implement a superset of the JSON data model, and is, 635 CBOR is supposed to implement a superset of the JSON data model, and is,
448 with some coercion, able to represent all JSON texts (something that 636 with some coercion, able to represent all JSON texts (something that
449 other "binary JSON" formats such as BSON generally do not support). 637 other "binary JSON" formats such as BSON generally do not support).

Diff Legend

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