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.70 by root, Sat Nov 9 07:30:36 2019 UTC vs.
Revision 1.87 by root, Mon Dec 19 20:31:33 2022 UTC

… …
64 64
65package CBOR::XS; 65package CBOR::XS;
66 66
67use common::sense; 67use common::sense;
68 68
69our $VERSION = 1.71; 69our $VERSION = 1.86;
70our @ISA = qw(Exporter); 70our @ISA = qw(Exporter);
71 71
72our @EXPORT = qw(encode_cbor decode_cbor); 72our @EXPORT = qw(encode_cbor decode_cbor);
73 73
74use Exporter; 74use Exporter;
… …
121but configures the coder object to be safe to use with untrusted 121but configures the coder object to be safe to use with untrusted
122data. Currently, this is equivalent to: 122data. Currently, this is equivalent to:
123 123
124 my $cbor = CBOR::XS 124 my $cbor = CBOR::XS
125 ->new 125 ->new
126 ->validate_utf8
126 ->forbid_objects 127 ->forbid_objects
127 ->filter (\&CBOR::XS::safe_filter) 128 ->filter (\&CBOR::XS::safe_filter)
128 ->max_size (1e8); 129 ->max_size (1e8);
129 130
130But is more future proof (it is better to crash because of a change than 131But is more future proof (it is better to crash because of a change than
… …
133=cut 134=cut
134 135
135sub new_safe { 136sub new_safe {
136 CBOR::XS 137 CBOR::XS
137 ->new 138 ->new
139 ->validate_utf8
138 ->forbid_objects 140 ->forbid_objects
139 ->filter (\&CBOR::XS::safe_filter) 141 ->filter (\&CBOR::XS::safe_filter)
140 ->max_size (1e8) 142 ->max_size (1e8)
141} 143}
142 144
… …
330strings as CBOR byte strings. 332strings as CBOR byte strings.
331 333
332This option does not affect C<decode> in any way. 334This option does not affect C<decode> in any way.
333 335
334This option has similar advantages and disadvantages as C<text_keys>. In 336This option has similar advantages and disadvantages as C<text_keys>. In
335addition, this option effectively removes the ability to encode byte 337addition, this option effectively removes the ability to automatically
336strings, which might break some C<FREEZE> and C<TO_CBOR> methods that rely 338encode byte strings, which might break some C<FREEZE> and C<TO_CBOR>
337on this, such as bignum encoding, so this option is mainly useful for very 339methods that rely on this.
338simple data. 340
341A workaround is to use explicit type casts, which are unaffected by this option.
339 342
340=item $cbor = $cbor->validate_utf8 ([$enable]) 343=item $cbor = $cbor->validate_utf8 ([$enable])
341 344
342=item $enabled = $cbor->get_validate_utf8 345=item $enabled = $cbor->get_validate_utf8
343 346
… …
470Perl data structure in memory at one time, it does allow you to parse a 473Perl data structure in memory at one time, it does allow you to parse a
471CBOR stream incrementally, using a similar to using "decode_prefix" to see 474CBOR stream incrementally, using a similar to using "decode_prefix" to see
472if a full CBOR object is available, but is much more efficient. 475if a full CBOR object is available, but is much more efficient.
473 476
474It basically works by parsing as much of a CBOR string as possible - if 477It basically works by parsing as much of a CBOR string as possible - if
475the CBOR data is not complete yet, the pasrer will remember where it was, 478the CBOR data is not complete yet, the parser will remember where it was,
476to be able to restart when more data has been accumulated. Once enough 479to be able to restart when more data has been accumulated. Once enough
477data is available to either decode a complete CBOR value or raise an 480data is available to either decode a complete CBOR value or raise an
478error, a real decode will be attempted. 481error, a real decode will be attempted.
479 482
480A typical use case would be a network protocol that consists of sending 483A typical use case would be a network protocol that consists of sending
… …
632create such objects. 635create such objects.
633 636
634=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error 637=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
635 638
636These special values become CBOR true, CBOR false and CBOR undefined 639These special values become CBOR true, CBOR false and CBOR undefined
637values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly 640values, respectively.
638if you want.
639 641
640=item other blessed objects 642=item other blessed objects
641 643
642Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See 644Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See
643L<TAG HANDLING AND EXTENSIONS> for specific classes handled by this 645L<TAG HANDLING AND EXTENSIONS> for specific classes handled by this
… …
668 "$x"; # stringified 670 "$x"; # stringified
669 $x .= ""; # another, more awkward way to stringify 671 $x .= ""; # another, more awkward way to stringify
670 print $x; # perl does it for you, too, quite often 672 print $x; # perl does it for you, too, quite often
671 673
672You can force whether a string is encoded as byte or text string by using 674You can force whether a string is encoded as byte or text string by using
673C<utf8::upgrade> and C<utf8::downgrade> (if C<text_strings> is disabled): 675C<utf8::upgrade> and C<utf8::downgrade> (if C<text_strings> is disabled).
674 676
675 utf8::upgrade $x; # encode $x as text string 677 utf8::upgrade $x; # encode $x as text string
676 utf8::downgrade $x; # encode $x as byte string 678 utf8::downgrade $x; # encode $x as byte string
679
680More options are available, see L<TYPE CASTS>, below, and the C<text_keys>
681and C<text_strings> options.
677 682
678Perl doesn't define what operations up- and downgrade strings, so if the 683Perl doesn't define what operations up- and downgrade strings, so if the
679difference between byte and text is important, you should up- or downgrade 684difference between byte and text is important, you should up- or downgrade
680your string as late as possible before encoding. You can also force the 685your string as late as possible before encoding. You can also force the
681use of CBOR text strings by using C<text_keys> or C<text_strings>. 686use of CBOR text strings by using C<text_keys> or C<text_strings>.
… …
696format will be used. Perls that use formats other than IEEE double to 701format will be used. Perls that use formats other than IEEE double to
697represent numerical values are supported, but might suffer loss of 702represent numerical values are supported, but might suffer loss of
698precision. 703precision.
699 704
700=back 705=back
706
707=head2 TYPE CASTS
708
709B<EXPERIMENTAL>: As an experimental extension, C<CBOR::XS> allows you to
710force specific CBOR types to be used when encoding. That allows you to
711encode types not normally accessible (e.g. half floats) as well as force
712string types even when C<text_strings> is in effect.
713
714Type forcing is done by calling a special "cast" function which keeps a
715copy of the value and returns a new value that can be handed over to any
716CBOR encoder function.
717
718The following casts are currently available (all of which are unary
719operators, that is, have a prototype of C<$>):
720
721=over
722
723=item CBOR::XS::as_int $value
724
725Forces the value to be encoded as some form of (basic, not bignum) integer
726type.
727
728=item CBOR::XS::as_text $value
729
730Forces the value to be encoded as (UTF-8) text values.
731
732=item CBOR::XS::as_bytes $value
733
734Forces the value to be encoded as a (binary) string value.
735
736Example: encode a perl string as binary even though C<text_strings> is in
737effect.
738
739 CBOR::XS->new->text_strings->encode ([4, "text", CBOR::XS::bytes "bytevalue"]);
740
741=item CBOR::XS::as_bool $value
742
743Converts a Perl boolean (which can be any kind of scalar) into a CBOR
744boolean. Strictly the same, but shorter to write, than:
745
746 $value ? Types::Serialiser::true : Types::Serialiser::false
747
748=item CBOR::XS::as_float16 $value
749
750Forces half-float (IEEE 754 binary16) encoding of the given value.
751
752=item CBOR::XS::as_float32 $value
753
754Forces single-float (IEEE 754 binary32) encoding of the given value.
755
756=item CBOR::XS::as_float64 $value
757
758Forces double-float (IEEE 754 binary64) encoding of the given value.
759
760=item CBOR::XS::as_cbor $cbor_text
761
762Not a type cast per-se, this type cast forces the argument to be encoded
763as-is. This can be used to embed pre-encoded CBOR data.
764
765Note that no checking on the validity of the C<$cbor_text> is done - it's
766the callers responsibility to correctly encode values.
767
768=item CBOR::XS::as_map [key => value...]
769
770Treat the array reference as key value pairs and output a CBOR map. This
771allows you to generate CBOR maps with arbitrary key types (or, if you
772don't care about semantics, duplicate keys or pairs in a custom order),
773which is otherwise hard to do with Perl.
774
775The single argument must be an array reference with an even number of
776elements.
777
778Note that only the reference to the array is copied, the array itself is
779not. Modifications done to the array before calling an encoding function
780will be reflected in the encoded output.
781
782Example: encode a CBOR map with a string and an integer as keys.
783
784 encode_cbor CBOR::XS::as_map [string => "value", 5 => "value"]
785
786=back
787
788=cut
789
790sub CBOR::XS::as_cbor ($) { bless [$_[0], 0, undef], CBOR::XS::Tagged:: }
791sub CBOR::XS::as_int ($) { bless [$_[0], 1, undef], CBOR::XS::Tagged:: }
792sub CBOR::XS::as_bytes ($) { bless [$_[0], 2, undef], CBOR::XS::Tagged:: }
793sub CBOR::XS::as_text ($) { bless [$_[0], 3, undef], CBOR::XS::Tagged:: }
794sub CBOR::XS::as_float16 ($) { bless [$_[0], 4, undef], CBOR::XS::Tagged:: }
795sub CBOR::XS::as_float32 ($) { bless [$_[0], 5, undef], CBOR::XS::Tagged:: }
796sub CBOR::XS::as_float64 ($) { bless [$_[0], 6, undef], CBOR::XS::Tagged:: }
797
798sub CBOR::XS::as_bool ($) { $_[0] ? $Types::Serialiser::true : $Types::Serialiser::false }
799
800sub CBOR::XS::as_map ($) {
801 ARRAY:: eq ref $_[0]
802 and $#{ $_[0] } & 1
803 or do { require Carp; Carp::croak ("CBOR::XS::as_map only acepts array references with an even number of elements, caught") };
804
805 bless [$_[0], 7, undef], CBOR::XS::Tagged::
806}
701 807
702=head2 OBJECT SERIALISATION 808=head2 OBJECT SERIALISATION
703 809
704This module implements both a CBOR-specific and the generic 810This module implements both a CBOR-specific and the generic
705L<Types::Serialier> object serialisation protocol. The following 811L<Types::Serialier> object serialisation protocol. The following
… …
1228=head1 LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT 1334=head1 LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT
1229 1335
1230On perls that were built without 64 bit integer support (these are rare 1336On perls that were built without 64 bit integer support (these are rare
1231nowadays, even on 32 bit architectures, as all major Perl distributions 1337nowadays, even on 32 bit architectures, as all major Perl distributions
1232are built with 64 bit integer support), support for any kind of 64 bit 1338are built with 64 bit integer support), support for any kind of 64 bit
1233integer in CBOR is very limited - most likely, these 64 bit values will 1339value in CBOR is very limited - most likely, these 64 bit values will
1234be truncated, corrupted, or otherwise not decoded correctly. This also 1340be truncated, corrupted, or otherwise not decoded correctly. This also
1235includes string, array and map sizes that are stored as 64 bit integers. 1341includes string, float, array and map sizes that are stored as 64 bit
1342integers.
1236 1343
1237 1344
1238=head1 THREADS 1345=head1 THREADS
1239 1346
1240This module is I<not> guaranteed to be thread safe and there are no 1347This module is I<not> guaranteed to be thread safe and there are no

Diff Legend

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