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.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
… …
471Perl 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
472CBOR stream incrementally, using a similar to using "decode_prefix" to see 474CBOR stream incrementally, using a similar to using "decode_prefix" to see
473if a full CBOR object is available, but is much more efficient. 475if a full CBOR object is available, but is much more efficient.
474 476
475It 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
476the 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,
477to 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
478data 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
479error, a real decode will be attempted. 481error, a real decode will be attempted.
480 482
481A 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
… …
633create such objects. 635create such objects.
634 636
635=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error 637=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
636 638
637These special values become CBOR true, CBOR false and CBOR undefined 639These special values become CBOR true, CBOR false and CBOR undefined
638values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly 640values, respectively.
639if you want.
640 641
641=item other blessed objects 642=item other blessed objects
642 643
643Other 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
644L<TAG HANDLING AND EXTENSIONS> for specific classes handled by this 645L<TAG HANDLING AND EXTENSIONS> for specific classes handled by this
… …
704=back 705=back
705 706
706=head2 TYPE CASTS 707=head2 TYPE CASTS
707 708
708B<EXPERIMENTAL>: As an experimental extension, C<CBOR::XS> allows you to 709B<EXPERIMENTAL>: As an experimental extension, C<CBOR::XS> allows you to
709force specific cbor types to be used when encoding. That allows you to 710force 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 711encode types not normally accessible (e.g. half floats) as well as force
711string types even when C<text_strings> is in effect. 712string types even when C<text_strings> is in effect.
712 713
713Type forcing is done by calling a special "cast" function which keeps a 714Type 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 715copy of the value and returns a new value that can be handed over to any
715CBOR encoder function. 716CBOR encoder function.
716 717
717The following casts are currently available (all of which are unary operators): 718The following casts are currently available (all of which are unary
719operators, that is, have a prototype of C<$>):
718 720
719=over 721=over
720 722
721=item CBOR::XS::as_int $value 723=item CBOR::XS::as_int $value
722 724
… …
729 731
730=item CBOR::XS::as_bytes $value 732=item CBOR::XS::as_bytes $value
731 733
732Forces the value to be encoded as a (binary) string value. 734Forces the value to be encoded as a (binary) string value.
733 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
734=item CBOR::XS::as_float16 $value 748=item CBOR::XS::as_float16 $value
735 749
736Forces half-float (IEEE 754 binary16) encoding of the given value. 750Forces half-float (IEEE 754 binary16) encoding of the given value.
737 751
738=item CBOR::XS::as_float32 $value 752=item CBOR::XS::as_float32 $value
… …
741 755
742=item CBOR::XS::as_float64 $value 756=item CBOR::XS::as_float64 $value
743 757
744Forces double-float (IEEE 754 binary64) encoding of the given value. 758Forces double-float (IEEE 754 binary64) encoding of the given value.
745 759
746=item, CBOR::XS::as_cbor $cbor_text 760=item CBOR::XS::as_cbor $cbor_text
747 761
748Bot a type cast per-se, this type cast forces the argument to eb encoded 762Not 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. 763as-is. This can be used to embed pre-encoded CBOR data.
750 764
751Note that no checking on the validity of the C<$cbor_text> is done - it's 765Note that no checking on the validity of the C<$cbor_text> is done - it's
752the callers responsibility to correctly encode values. 766the callers responsibility to correctly encode values.
753 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
754=back 786=back
755 787
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 788=cut
762 789
763sub CBOR::XS::as_int ($) { bless [$_[0], 0, undef], CBOR::XS::Tagged:: }
764sub CBOR::XS::as_cbor ($) { bless [$_[0], 1, undef], CBOR::XS::Tagged:: } 790sub CBOR::XS::as_cbor ($) { bless [$_[0], 0, undef], CBOR::XS::Tagged:: }
791sub CBOR::XS::as_int ($) { bless [$_[0], 1, undef], CBOR::XS::Tagged:: }
765sub CBOR::XS::as_bytes ($) { bless [$_[0], 2, undef], CBOR::XS::Tagged:: } 792sub CBOR::XS::as_bytes ($) { bless [$_[0], 2, undef], CBOR::XS::Tagged:: }
766sub CBOR::XS::as_text ($) { bless [$_[0], 3, undef], CBOR::XS::Tagged:: } 793sub CBOR::XS::as_text ($) { bless [$_[0], 3, undef], CBOR::XS::Tagged:: }
767sub CBOR::XS::as_float16 ($) { bless [$_[0], 4, undef], CBOR::XS::Tagged:: } 794sub CBOR::XS::as_float16 ($) { bless [$_[0], 4, undef], CBOR::XS::Tagged:: }
768sub CBOR::XS::as_float32 ($) { bless [$_[0], 5, undef], CBOR::XS::Tagged:: } 795sub CBOR::XS::as_float32 ($) { bless [$_[0], 5, undef], CBOR::XS::Tagged:: }
769sub CBOR::XS::as_float64 ($) { bless [$_[0], 6, 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}
770 807
771=head2 OBJECT SERIALISATION 808=head2 OBJECT SERIALISATION
772 809
773This module implements both a CBOR-specific and the generic 810This module implements both a CBOR-specific and the generic
774L<Types::Serialier> object serialisation protocol. The following 811L<Types::Serialier> object serialisation protocol. The following

Diff Legend

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