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.85 by root, Thu Nov 4 16:49:35 2021 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
… …
668 "$x"; # stringified 671 "$x"; # stringified
669 $x .= ""; # another, more awkward way to stringify 672 $x .= ""; # another, more awkward way to stringify
670 print $x; # perl does it for you, too, quite often 673 print $x; # perl does it for you, too, quite often
671 674
672You can force whether a string is encoded as byte or text string by using 675You 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): 676C<utf8::upgrade> and C<utf8::downgrade> (if C<text_strings> is disabled).
674 677
675 utf8::upgrade $x; # encode $x as text string 678 utf8::upgrade $x; # encode $x as text string
676 utf8::downgrade $x; # encode $x as byte string 679 utf8::downgrade $x; # encode $x as byte string
680
681More options are available, see L<TYPE CASTS>, below, and the C<text_keys>
682and C<text_strings> options.
677 683
678Perl doesn't define what operations up- and downgrade strings, so if the 684Perl doesn't define what operations up- and downgrade strings, so if the
679difference between byte and text is important, you should up- or downgrade 685difference between byte and text is important, you should up- or downgrade
680your string as late as possible before encoding. You can also force the 686your 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>. 687use 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 702format will be used. Perls that use formats other than IEEE double to
697represent numerical values are supported, but might suffer loss of 703represent numerical values are supported, but might suffer loss of
698precision. 704precision.
699 705
700=back 706=back
707
708=head2 TYPE CASTS
709
710B<EXPERIMENTAL>: As an experimental extension, C<CBOR::XS> allows you to
711force specific CBOR types to be used when encoding. That allows you to
712encode types not normally accessible (e.g. half floats) as well as force
713string types even when C<text_strings> is in effect.
714
715Type forcing is done by calling a special "cast" function which keeps a
716copy of the value and returns a new value that can be handed over to any
717CBOR encoder function.
718
719The following casts are currently available (all of which are unary
720operators, that is, have a prototype of C<$>):
721
722=over
723
724=item CBOR::XS::as_int $value
725
726Forces the value to be encoded as some form of (basic, not bignum) integer
727type.
728
729=item CBOR::XS::as_text $value
730
731Forces the value to be encoded as (UTF-8) text values.
732
733=item CBOR::XS::as_bytes $value
734
735Forces the value to be encoded as a (binary) string value.
736
737Example: encode a perl string as binary even though C<text_strings> is in
738effect.
739
740 CBOR::XS->new->text_strings->encode ([4, "text", CBOR::XS::bytes "bytevalue"]);
741
742=item CBOR::XS::as_bool $value
743
744Converts a Perl boolean (which can be any kind of scalar) into a CBOR
745boolean. Strictly the same, but shorter to write, than:
746
747 $value ? Types::Serialiser::true : Types::Serialiser::false
748
749=item CBOR::XS::as_float16 $value
750
751Forces half-float (IEEE 754 binary16) encoding of the given value.
752
753=item CBOR::XS::as_float32 $value
754
755Forces single-float (IEEE 754 binary32) encoding of the given value.
756
757=item CBOR::XS::as_float64 $value
758
759Forces double-float (IEEE 754 binary64) encoding of the given value.
760
761=item CBOR::XS::as_cbor $cbor_text
762
763Not a type cast per-se, this type cast forces the argument to be encoded
764as-is. This can be used to embed pre-encoded CBOR data.
765
766Note that no checking on the validity of the C<$cbor_text> is done - it's
767the callers responsibility to correctly encode values.
768
769=item CBOR::XS::as_map [key => value...]
770
771Treat the array reference as key value pairs and output a CBOR map. This
772allows you to generate CBOR maps with arbitrary key types (or, if you
773don't care about semantics, duplicate keys or pairs in a custom order),
774which is otherwise hard to do with Perl.
775
776The single argument must be an array reference with an even number of
777elements.
778
779Note that only the reference to the array is copied, the array itself is
780not. Modifications done to the array before calling an encoding function
781will be reflected in the encoded output.
782
783Example: encode a CBOR map with a string and an integer as keys.
784
785 encode_cbor CBOR::XS::as_map [string => "value", 5 => "value"]
786
787=back
788
789=cut
790
791sub CBOR::XS::as_cbor ($) { bless [$_[0], 0, undef], CBOR::XS::Tagged:: }
792sub CBOR::XS::as_int ($) { bless [$_[0], 1, undef], CBOR::XS::Tagged:: }
793sub CBOR::XS::as_bytes ($) { bless [$_[0], 2, undef], CBOR::XS::Tagged:: }
794sub CBOR::XS::as_text ($) { bless [$_[0], 3, undef], CBOR::XS::Tagged:: }
795sub CBOR::XS::as_float16 ($) { bless [$_[0], 4, undef], CBOR::XS::Tagged:: }
796sub CBOR::XS::as_float32 ($) { bless [$_[0], 5, undef], CBOR::XS::Tagged:: }
797sub CBOR::XS::as_float64 ($) { bless [$_[0], 6, undef], CBOR::XS::Tagged:: }
798
799sub CBOR::XS::as_bool ($) { $_[0] ? $Types::Serialiser::true : $Types::Serialiser::false }
800
801sub CBOR::XS::as_map ($) {
802 ARRAY:: eq ref $_[0]
803 and $#{ $_[0] } & 1
804 or do { require Carp; Carp::croak ("CBOR::XS::as_map only acepts array references with an even number of elements, caught") };
805
806 bless [$_[0], 7, undef], CBOR::XS::Tagged::
807}
701 808
702=head2 OBJECT SERIALISATION 809=head2 OBJECT SERIALISATION
703 810
704This module implements both a CBOR-specific and the generic 811This module implements both a CBOR-specific and the generic
705L<Types::Serialier> object serialisation protocol. The following 812L<Types::Serialier> object serialisation protocol. The following
… …
1228=head1 LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT 1335=head1 LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT
1229 1336
1230On perls that were built without 64 bit integer support (these are rare 1337On perls that were built without 64 bit integer support (these are rare
1231nowadays, even on 32 bit architectures, as all major Perl distributions 1338nowadays, even on 32 bit architectures, as all major Perl distributions
1232are built with 64 bit integer support), support for any kind of 64 bit 1339are 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 1340value in CBOR is very limited - most likely, these 64 bit values will
1234be truncated, corrupted, or otherwise not decoded correctly. This also 1341be truncated, corrupted, or otherwise not decoded correctly. This also
1235includes string, array and map sizes that are stored as 64 bit integers. 1342includes string, float, array and map sizes that are stored as 64 bit
1343integers.
1236 1344
1237 1345
1238=head1 THREADS 1346=head1 THREADS
1239 1347
1240This module is I<not> guaranteed to be thread safe and there are no 1348This module is I<not> guaranteed to be thread safe and there are no

Diff Legend

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