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.72 by root, Sun Nov 29 21:35:06 2020 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
… …
704=back 706=back
705 707
706=head2 TYPE CASTS 708=head2 TYPE CASTS
707 709
708B<EXPERIMENTAL>: As an experimental extension, C<CBOR::XS> allows you to 710B<EXPERIMENTAL>: As an experimental extension, C<CBOR::XS> allows you to
709force specific cbor types to be used when encoding. That allows you to 711force specific CBOR types to be used when encoding. That allows you to
710encode types not normally accessible (e.g. half floats) as well as force 712encode types not normally accessible (e.g. half floats) as well as force
711string types even when C<text_strings> is in effect. 713string types even when C<text_strings> is in effect.
712 714
713Type forcing is done by calling a special "cast" function which keeps a 715Type forcing is done by calling a special "cast" function which keeps a
714copy of the value and returns a new value that can be handed over to any 716copy of the value and returns a new value that can be handed over to any
715CBOR encoder function. 717CBOR encoder function.
716 718
717The following casts are currently available (all of which are unary operators): 719The following casts are currently available (all of which are unary
720operators, that is, have a prototype of C<$>):
718 721
719=over 722=over
720 723
721=item CBOR::XS::as_int $value 724=item CBOR::XS::as_int $value
722 725
… …
729 732
730=item CBOR::XS::as_bytes $value 733=item CBOR::XS::as_bytes $value
731 734
732Forces the value to be encoded as a (binary) string value. 735Forces the value to be encoded as a (binary) string value.
733 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
734=item CBOR::XS::as_float16 $value 749=item CBOR::XS::as_float16 $value
735 750
736Forces half-float (IEEE 754 binary16) encoding of the given value. 751Forces half-float (IEEE 754 binary16) encoding of the given value.
737 752
738=item CBOR::XS::as_float32 $value 753=item CBOR::XS::as_float32 $value
… …
741 756
742=item CBOR::XS::as_float64 $value 757=item CBOR::XS::as_float64 $value
743 758
744Forces double-float (IEEE 754 binary64) encoding of the given value. 759Forces double-float (IEEE 754 binary64) encoding of the given value.
745 760
746=item, CBOR::XS::as_cbor $cbor_text 761=item CBOR::XS::as_cbor $cbor_text
747 762
748Bot a type cast per-se, this type cast forces the argument to eb encoded 763Not a type cast per-se, this type cast forces the argument to be encoded
749as-is. This can be used to embed pre-encoded CBOR data. 764as-is. This can be used to embed pre-encoded CBOR data.
750 765
751Note that no checking on the validity of the C<$cbor_text> is done - it's 766Note that no checking on the validity of the C<$cbor_text> is done - it's
752the callers responsibility to correctly encode values. 767the callers responsibility to correctly encode values.
753 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
754=back 787=back
755 788
756Example: encode a perl string as binary even though C<text_strings> is in
757effect.
758
759 CBOR::XS->new->text_strings->encode ([4, "text", CBOR::XS::bytes "bytevalue"]);
760
761=cut 789=cut
762 790
763sub CBOR::XS::as_int ($) { bless [$_[0], 0, undef], CBOR::XS::Tagged:: }
764sub CBOR::XS::as_cbor ($) { bless [$_[0], 1, undef], CBOR::XS::Tagged:: } 791sub CBOR::XS::as_cbor ($) { bless [$_[0], 0, undef], CBOR::XS::Tagged:: }
792sub CBOR::XS::as_int ($) { bless [$_[0], 1, undef], CBOR::XS::Tagged:: }
765sub CBOR::XS::as_bytes ($) { bless [$_[0], 2, undef], CBOR::XS::Tagged:: } 793sub CBOR::XS::as_bytes ($) { bless [$_[0], 2, undef], CBOR::XS::Tagged:: }
766sub CBOR::XS::as_text ($) { bless [$_[0], 3, undef], CBOR::XS::Tagged:: } 794sub CBOR::XS::as_text ($) { bless [$_[0], 3, undef], CBOR::XS::Tagged:: }
767sub CBOR::XS::as_float16 ($) { bless [$_[0], 4, undef], CBOR::XS::Tagged:: } 795sub CBOR::XS::as_float16 ($) { bless [$_[0], 4, undef], CBOR::XS::Tagged:: }
768sub CBOR::XS::as_float32 ($) { bless [$_[0], 5, undef], CBOR::XS::Tagged:: } 796sub CBOR::XS::as_float32 ($) { bless [$_[0], 5, undef], CBOR::XS::Tagged:: }
769sub CBOR::XS::as_float64 ($) { bless [$_[0], 6, 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}
770 808
771=head2 OBJECT SERIALISATION 809=head2 OBJECT SERIALISATION
772 810
773This module implements both a CBOR-specific and the generic 811This module implements both a CBOR-specific and the generic
774L<Types::Serialier> object serialisation protocol. The following 812L<Types::Serialier> object serialisation protocol. The following

Diff Legend

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