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.23 by root, Fri Nov 22 16:00:30 2013 UTC vs.
Revision 1.24 by root, Fri Nov 22 16:18:59 2013 UTC

… …
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;
… …
233 233
234=item $cbor = $cbor->filter ([$cb->($tag, $value)]) 234=item $cbor = $cbor->filter ([$cb->($tag, $value)])
235 235
236=item $cb_or_undef = $cbor->get_filter 236=item $cb_or_undef = $cbor->get_filter
237 237
238TODO 238Sets or replaces the tagged value decoding filter (when C<$cb> is
239specified) or clears the filter (if no argument or C<undef> is provided).
240
241The filter callback is called only during decoding, when a non-enforced
242tagged value has been decoded (see L<TAG HANDLING AND EXTENSIONS> for a
243list of enforced tags). For specific tags, it's often better to provide a
244default converter using the C<%CBOR::XS::FILTER> hash (see below).
245
246The first argument is the numerical tag, the second is the (decoded) value
247that has been tagged.
248
249The filter function should return either exactly one value, which will
250replace the tagged value in the decoded data structure, or no values,
251which will result in default handling, which currently means the decoder
252creates a C<CBOR::XS::Tagged> object to hold the tag and the value.
253
254When the filter is cleared (the default state), the default filter
255function, C<CBOR::XS::default_filter>, is used. This function simply looks
256up the tag in the C<%CBOR::XS::FILTER> hash. If an entry exists it must be
257a code reference that is called with tag and value, and is responsible for
258decoding the value. If no entry exists, it returns no values.
259
260Example: decode all tags not handled internally into CBOR::XS::Tagged
261objects, with no other special handling (useful when working with
262potentially "unsafe" CBOR data).
263
264 CBOR::XS->new->filter (sub { })->decode ($cbor_data);
265
266Example: provide a global filter for tag 1347375694, converting the value
267into some string form.
268
269 $CBOR::XS::FILTER{1347375694} = sub {
270 my ($tag, $value);
271
272 "tag 1347375694 value $value"
273 };
239 274
240=item $cbor_data = $cbor->encode ($perl_scalar) 275=item $cbor_data = $cbor->encode ($perl_scalar)
241 276
242Converts the given Perl data structure (a scalar value) to its CBOR 277Converts the given Perl data structure (a scalar value) to its CBOR
243representation. 278representation.
… …
670This value is not generated on encoding (unless explicitly requested by 705This value is not generated on encoding (unless explicitly requested by
671the user), and is simply ignored when decoding. 706the user), and is simply ignored when decoding.
672 707
673=back 708=back
674 709
675=head2 OPTIONAL TAGS 710=head2 NON-ENFORCED TAGS
676 711
677These tags have default filters provided when decoding. Their handling can 712These tags have default filters provided when decoding. Their handling can
678be overriden by changing the C<%CBOR::XS::FILTER> entry for the tag, or by 713be overriden by changing the C<%CBOR::XS::FILTER> entry for the tag, or by
679providing a custom C<filter> function when decoding. 714providing a custom C<filter> callback when decoding.
680 715
681When they result in decoding into a specific Perl class, the module 716When they result in decoding into a specific Perl class, the module
682usually provides a corresponding C<TO_CBOR> method as well. 717usually provides a corresponding C<TO_CBOR> method as well.
683 718
684When any of these need to load additional modules that are not part of the 719When any of these need to load additional modules that are not part of the

Diff Legend

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