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

Comparing CBOR-XS/XS.pm (file contents):
Revision 1.22 by root, Fri Nov 22 15:28:38 2013 UTC vs.
Revision 1.26 by root, Thu Nov 28 12:11:06 2013 UTC

… …
56As for compactness, C<CBOR::XS> encoded data structures are usually about 56As for compactness, C<CBOR::XS> encoded data structures are usually about
5720% smaller than the same data encoded as (compact) JSON or L<Storable>. 5720% smaller than the same data encoded as (compact) JSON or L<Storable>.
58 58
59In addition to the core CBOR data format, this module implements a number 59In addition to the core CBOR data format, this module implements a number
60of extensions, to support cyclic and self-referencing data structures 60of extensions, to support cyclic and self-referencing data structures
61(see C<allow_sharing>), string deduplication (see C<allow_stringref>) and 61(see C<allow_sharing>), string deduplication (see C<pack_strings>) and
62scalar references (always enabled). 62scalar references (always enabled).
63 63
64The primary goal of this module is to be I<correct> and the secondary goal 64The primary goal of this module is to be I<correct> and the secondary goal
65is to be I<fast>. To reach the latter goal it was written in C. 65is to be I<fast>. To reach the latter goal it was written in C.
66 66
… …
71 71
72package CBOR::XS; 72package CBOR::XS;
73 73
74use common::sense; 74use common::sense;
75 75
76our $VERSION = 0.08; 76our $VERSION = 0.09;
77our @ISA = qw(Exporter); 77our @ISA = qw(Exporter);
78 78
79our @EXPORT = qw(encode_cbor decode_cbor); 79our @EXPORT = qw(encode_cbor decode_cbor);
80 80
81use Exporter; 81use Exporter;
… …
118strings. All boolean flags described below are by default I<disabled>. 118strings. All boolean flags described below are by default I<disabled>.
119 119
120The mutators for flags all return the CBOR object again and thus calls can 120The mutators for flags all return the CBOR object again and thus calls can
121be chained: 121be chained:
122 122
123#TODO
124 my $cbor = CBOR::XS->new->encode ({a => [1,2]}); 123 my $cbor = CBOR::XS->new->encode ({a => [1,2]});
125 124
126=item $cbor = $cbor->max_depth ([$maximum_nesting_depth]) 125=item $cbor = $cbor->max_depth ([$maximum_nesting_depth])
127 126
128=item $max_depth = $cbor->get_max_depth 127=item $max_depth = $cbor->get_max_depth
… …
187as an array, is referenced multiple times), but instead will emit a 186as an array, is referenced multiple times), but instead will emit a
188reference to the earlier value. 187reference to the earlier value.
189 188
190This means that such values will only be encoded once, and will not result 189This means that such values will only be encoded once, and will not result
191in a deep cloning of the value on decode, in decoders supporting the value 190in a deep cloning of the value on decode, in decoders supporting the value
192sharing extension. 191sharing extension. This also makes it possible to encode cyclic data
192structures.
193 193
194It is recommended to leave it off unless you know your 194It is recommended to leave it off unless you know your
195communication partner supports the value sharing extensions to CBOR 195communication partner supports the value sharing extensions to CBOR
196(http://cbor.schmorp.de/value-sharing). 196(L<http://cbor.schmorp.de/value-sharing>), as without decoder support, the
197resulting data structure might be unusable.
197 198
198Detecting shared values incurs a runtime overhead when values are encoded 199Detecting shared values incurs a runtime overhead when values are encoded
199that have a reference counter large than one, and might unnecessarily 200that have a reference counter large than one, and might unnecessarily
200increase the encoded size, as potentially shared values are encode as 201increase the encoded size, as potentially shared values are encode as
201sharable whether or not they are actually shared. 202sharable whether or not they are actually shared.
202 203
203At the moment, only targets of references can be shared (e.g. scalars, 204At the moment, only targets of references can be shared (e.g. scalars,
204arrays or hashes pointed to by a reference). Weirder constructs, such as 205arrays or hashes pointed to by a reference). Weirder constructs, such as
205an array with multiple "copies" of the I<same> string, which are hard but 206an array with multiple "copies" of the I<same> string, which are hard but
206not impossible to create in Perl, are not supported (this is the same as 207not impossible to create in Perl, are not supported (this is the same as
207for L<Storable>). 208with L<Storable>).
208 209
209If C<$enable> is false (the default), then C<encode> will encode 210If C<$enable> is false (the default), then C<encode> will encode shared
210exception when it encounters anything it cannot encode as CBOR. 211data structures repeatedly, unsharing them in the process. Cyclic data
212structures cannot be encoded in this mode.
211 213
212This option does not affect C<decode> in any way - shared values and 214This option does not affect C<decode> in any way - shared values and
213references will always be decoded properly if present. 215references will always be decoded properly if present.
214 216
215=item $cbor = $cbor->allow_stringref ([$enable]) 217=item $cbor = $cbor->pack_strings ([$enable])
216 218
217=item $enabled = $cbor->get_allow_stringref 219=item $enabled = $cbor->get_pack_strings
218 220
219If C<$enable> is true (or missing), then C<encode> will try not to encode 221If C<$enable> is true (or missing), then C<encode> will try not to encode
220the same string twice, but will instead encode a reference to the string 222the same string twice, but will instead encode a reference to the string
221instead. Depending on your data format. this can save a lot of space, but 223instead. Depending on your data format, this can save a lot of space, but
222also results in a very large runtime overhead (expect encoding times to be 224also results in a very large runtime overhead (expect encoding times to be
2232-4 times as high as without). 2252-4 times as high as without).
224 226
225It is recommended to leave it off unless you know your 227It is recommended to leave it off unless you know your
226communications partner supports the stringref extension to CBOR 228communications partner supports the stringref extension to CBOR
227(http://cbor.schmorp.de/stringref). 229(L<http://cbor.schmorp.de/stringref>), as without decoder support, the
230resulting data structure might not be usable.
228 231
229If C<$enable> is false (the default), then C<encode> will encode 232If C<$enable> is false (the default), then C<encode> will encode strings
230exception when it encounters anything it cannot encode as CBOR. 233the standard CBOR way.
231 234
232This option does not affect C<decode> in any way - string references will 235This option does not affect C<decode> in any way - string references will
233always be decoded properly if present. 236always be decoded properly if present.
237
238=item $cbor = $cbor->filter ([$cb->($tag, $value)])
239
240=item $cb_or_undef = $cbor->get_filter
241
242Sets or replaces the tagged value decoding filter (when C<$cb> is
243specified) or clears the filter (if no argument or C<undef> is provided).
244
245The filter callback is called only during decoding, when a non-enforced
246tagged value has been decoded (see L<TAG HANDLING AND EXTENSIONS> for a
247list of enforced tags). For specific tags, it's often better to provide a
248default converter using the C<%CBOR::XS::FILTER> hash (see below).
249
250The first argument is the numerical tag, the second is the (decoded) value
251that has been tagged.
252
253The filter function should return either exactly one value, which will
254replace the tagged value in the decoded data structure, or no values,
255which will result in default handling, which currently means the decoder
256creates a C<CBOR::XS::Tagged> object to hold the tag and the value.
257
258When the filter is cleared (the default state), the default filter
259function, C<CBOR::XS::default_filter>, is used. This function simply looks
260up the tag in the C<%CBOR::XS::FILTER> hash. If an entry exists it must be
261a code reference that is called with tag and value, and is responsible for
262decoding the value. If no entry exists, it returns no values.
263
264Example: decode all tags not handled internally into CBOR::XS::Tagged
265objects, with no other special handling (useful when working with
266potentially "unsafe" CBOR data).
267
268 CBOR::XS->new->filter (sub { })->decode ($cbor_data);
269
270Example: provide a global filter for tag 1347375694, converting the value
271into some string form.
272
273 $CBOR::XS::FILTER{1347375694} = sub {
274 my ($tag, $value);
275
276 "tag 1347375694 value $value"
277 };
234 278
235=item $cbor_data = $cbor->encode ($perl_scalar) 279=item $cbor_data = $cbor->encode ($perl_scalar)
236 280
237Converts the given Perl data structure (a scalar value) to its CBOR 281Converts the given Perl data structure (a scalar value) to its CBOR
238representation. 282representation.
… …
307C<Types:Serialiser::false> and C<Types::Serialiser::error>, 351C<Types:Serialiser::false> and C<Types::Serialiser::error>,
308respectively. They are overloaded to act almost exactly like the numbers 352respectively. They are overloaded to act almost exactly like the numbers
309C<1> and C<0> (for true and false) or to throw an exception on access (for 353C<1> and C<0> (for true and false) or to throw an exception on access (for
310error). See the L<Types::Serialiser> manpage for details. 354error). See the L<Types::Serialiser> manpage for details.
311 355
312=item CBOR tag 256 (perl object) 356=item tagged values
313 357
314The tag value C<256> (TODO: pending iana registration) will be used
315to deserialise a Perl object serialised with C<FREEZE>. See L<OBJECT
316SERIALISATION>, below, for details.
317
318=item CBOR tag 55799 (magic header)
319
320The tag 55799 is ignored (this tag implements the magic header).
321
322=item other CBOR tags
323
324Tagged items consists of a numeric tag and another CBOR value. Tags not 358Tagged items consists of a numeric tag and another CBOR value.
325handled internally are currently converted into a L<CBOR::XS::Tagged>
326object, which is simply a blessed array reference consisting of the
327numeric tag value followed by the (decoded) CBOR value.
328 359
329In the future, support for user-supplied conversions might get added. 360See L<TAG HANDLING AND EXTENSIONS> and the description of C<< ->filter >>
361for details.
330 362
331=item anything else 363=item anything else
332 364
333Anything else (e.g. unsupported simple values) will raise a decoding 365Anything else (e.g. unsupported simple values) will raise a decoding
334error. 366error.
… …
377if you want. 409if you want.
378 410
379=item other blessed objects 411=item other blessed objects
380 412
381Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See 413Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See
382L<OBJECT SERIALISATION>, below, for details. 414L<TAG HANDLING AND EXTENSIONS> for specific classes handled by this
415module, and L<OBJECT SERIALISATION> for generic object serialisation.
383 416
384=item simple scalars 417=item simple scalars
385 418
386TODO
387Simple Perl scalars (any scalar that is not a reference) are the most 419Simple Perl scalars (any scalar that is not a reference) are the most
388difficult objects to encode: CBOR::XS will encode undefined scalars as 420difficult objects to encode: CBOR::XS will encode undefined scalars as
389CBOR null values, scalars that have last been used in a string context 421CBOR null values, scalars that have last been used in a string context
390before encoding as CBOR strings, and anything else as number value: 422before encoding as CBOR strings, and anything else as number value:
391 423
… …
633and extensions. If a tag is not mentioned here and no additional filters 665and extensions. If a tag is not mentioned here and no additional filters
634are provided for it, then the default handling applies (creating a 666are provided for it, then the default handling applies (creating a
635CBOR::XS::Tagged object on decoding, and only encoding the tag when 667CBOR::XS::Tagged object on decoding, and only encoding the tag when
636explicitly requested). 668explicitly requested).
637 669
670Tags not handled specifically are currently converted into a
671L<CBOR::XS::Tagged> object, which is simply a blessed array reference
672consisting of the numeric tag value followed by the (decoded) CBOR value.
673
638Future versions of this module reserve the right to special case 674Future versions of this module reserve the right to special case
639additional tags (such as base64url). 675additional tags (such as base64url).
640 676
641=head2 ENFORCED TAGS 677=head2 ENFORCED TAGS
642 678
643These tags are always handled when decoding, and their handling cannot be 679These tags are always handled when decoding, and their handling cannot be
644overriden by the user. 680overriden by the user.
645 681
646=over 4 682=over 4
647 683
648=item <unassigned> (perl-object, L<http://cbor.schmorp.de/perl-object>) 684=item 26 (perl-object, L<http://cbor.schmorp.de/perl-object>)
649 685
650These tags are automatically created for serialisable objects using the 686These tags are automatically created (and decoded) for serialisable
651C<FREEZE/THAW> methods (the L<Types::Serialier> object serialisation 687objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object
652protocol). 688serialisation protocol). See L<OBJECT SERIALISATION> for details.
653 689
654=item <unassigned>, <unassigned> (sharable, sharedref, L <http://cbor.schmorp.de/value-sharing>) 690=item 28, 29 (sharable, sharedref, L <http://cbor.schmorp.de/value-sharing>)
655 691
656These tags are automatically decoded when encountered, resulting in 692These tags are automatically decoded when encountered, resulting in
657shared values in the decoded object. They are only encoded, however, when 693shared values in the decoded object. They are only encoded, however, when
658C<allow_sharable> is enabled. 694C<allow_sharable> is enabled.
659 695
660=item <unassigned>, <unassigned> (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>) 696=item 256, 25 (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>)
661 697
662These tags are automatically decoded when encountered. They are only 698These tags are automatically decoded when encountered. They are only
663encoded, however, when C<allow_stringref> is enabled. 699encoded, however, when C<pack_strings> is enabled.
664 700
665=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>) 701=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>)
666 702
667This tag is automatically generated when a reference are encountered (with 703This tag is automatically generated when a reference are encountered (with
668the exception of hash and array refernces). It is converted to a reference 704the exception of hash and array refernces). It is converted to a reference
… …
673This value is not generated on encoding (unless explicitly requested by 709This value is not generated on encoding (unless explicitly requested by
674the user), and is simply ignored when decoding. 710the user), and is simply ignored when decoding.
675 711
676=back 712=back
677 713
678=head2 OPTIONAL TAGS 714=head2 NON-ENFORCED TAGS
679 715
680These tags have default filters provided when decoding. Their handling can 716These tags have default filters provided when decoding. Their handling can
681be overriden by changing the C<%CBOR::XS::FILTER> entry for the tag, or by 717be overriden by changing the C<%CBOR::XS::FILTER> entry for the tag, or by
682providing a custom C<filter> function when decoding. 718providing a custom C<filter> callback when decoding.
683 719
684When they result in decoding into a specific Perl class, the module 720When they result in decoding into a specific Perl class, the module
685usually provides a corresponding C<TO_CBOR> method as well. 721usually provides a corresponding C<TO_CBOR> method as well.
686 722
687When any of these need to load additional modules that are not part of the 723When any of these need to load additional modules that are not part of the

Diff Legend

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