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

… …
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
… …
230exception when it encounters anything it cannot encode as CBOR. 229exception when it encounters anything it cannot encode as CBOR.
231 230
232This option does not affect C<decode> in any way - string references will 231This option does not affect C<decode> in any way - string references will
233always be decoded properly if present. 232always be decoded properly if present.
234 233
234=item $cbor = $cbor->filter ([$cb->($tag, $value)])
235
236=item $cb_or_undef = $cbor->get_filter
237
238TODO
239
235=item $cbor_data = $cbor->encode ($perl_scalar) 240=item $cbor_data = $cbor->encode ($perl_scalar)
236 241
237Converts the given Perl data structure (a scalar value) to its CBOR 242Converts the given Perl data structure (a scalar value) to its CBOR
238representation. 243representation.
239 244
… …
307C<Types:Serialiser::false> and C<Types::Serialiser::error>, 312C<Types:Serialiser::false> and C<Types::Serialiser::error>,
308respectively. They are overloaded to act almost exactly like the numbers 313respectively. 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 314C<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. 315error). See the L<Types::Serialiser> manpage for details.
311 316
312=item CBOR tag 256 (perl object) 317=item tagged values
313 318
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 319Tagged 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 320
329In the future, support for user-supplied conversions might get added. 321See L<TAG HANDLING AND EXTENSIONS> and the description of C<< ->filter >>
322for details.
330 323
331=item anything else 324=item anything else
332 325
333Anything else (e.g. unsupported simple values) will raise a decoding 326Anything else (e.g. unsupported simple values) will raise a decoding
334error. 327error.
… …
377if you want. 370if you want.
378 371
379=item other blessed objects 372=item other blessed objects
380 373
381Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See 374Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See
382L<OBJECT SERIALISATION>, below, for details. 375L<TAG HANDLING AND EXTENSIONS> for specific classes handled by this
376module, and L<OBJECT SERIALISATION> for generic object serialisation.
383 377
384=item simple scalars 378=item simple scalars
385 379
386TODO
387Simple Perl scalars (any scalar that is not a reference) are the most 380Simple Perl scalars (any scalar that is not a reference) are the most
388difficult objects to encode: CBOR::XS will encode undefined scalars as 381difficult objects to encode: CBOR::XS will encode undefined scalars as
389CBOR null values, scalars that have last been used in a string context 382CBOR null values, scalars that have last been used in a string context
390before encoding as CBOR strings, and anything else as number value: 383before encoding as CBOR strings, and anything else as number value:
391 384
… …
633and extensions. If a tag is not mentioned here and no additional filters 626and extensions. If a tag is not mentioned here and no additional filters
634are provided for it, then the default handling applies (creating a 627are provided for it, then the default handling applies (creating a
635CBOR::XS::Tagged object on decoding, and only encoding the tag when 628CBOR::XS::Tagged object on decoding, and only encoding the tag when
636explicitly requested). 629explicitly requested).
637 630
631Tags not handled specifically are currently converted into a
632L<CBOR::XS::Tagged> object, which is simply a blessed array reference
633consisting of the numeric tag value followed by the (decoded) CBOR value.
634
638Future versions of this module reserve the right to special case 635Future versions of this module reserve the right to special case
639additional tags (such as base64url). 636additional tags (such as base64url).
640 637
641=head2 ENFORCED TAGS 638=head2 ENFORCED TAGS
642 639
… …
645 642
646=over 4 643=over 4
647 644
648=item <unassigned> (perl-object, L<http://cbor.schmorp.de/perl-object>) 645=item <unassigned> (perl-object, L<http://cbor.schmorp.de/perl-object>)
649 646
650These tags are automatically created for serialisable objects using the 647These tags are automatically created (and decoded) for serialisable
651C<FREEZE/THAW> methods (the L<Types::Serialier> object serialisation 648objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object
652protocol). 649serialisation protocol). See L<OBJECT SERIALISATION> for details.
653 650
654=item <unassigned>, <unassigned> (sharable, sharedref, L <http://cbor.schmorp.de/value-sharing>) 651=item <unassigned>, <unassigned> (sharable, sharedref, L <http://cbor.schmorp.de/value-sharing>)
655 652
656These tags are automatically decoded when encountered, resulting in 653These tags are automatically decoded when encountered, resulting in
657shared values in the decoded object. They are only encoded, however, when 654shared values in the decoded object. They are only encoded, however, when

Diff Legend

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