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.71 by root, Sun Nov 29 21:32:01 2020 UTC vs.
Revision 1.81 by root, Fri Dec 11 06:10:26 2020 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.83;
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;
… …
704=back 704=back
705 705
706=head2 TYPE CASTS 706=head2 TYPE CASTS
707 707
708B<EXPERIMENTAL>: As an experimental extension, C<CBOR::XS> allows you to 708B<EXPERIMENTAL>: As an experimental extension, C<CBOR::XS> allows you to
709force specific cbor types to be used when encoding. That allows you to 709force 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 710encode types not normally accessible (e.g. half floats) as well as force
711string types even when C<text_strings> is in effect. 711string types even when C<text_strings> is in effect.
712 712
713Type forcing is done by calling a special "cast" function which keeps a 713Type 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 714copy of the value and returns a new value that can be handed over to any
715CBOR encoder function. 715CBOR encoder function.
716 716
717The following casts are currently available (all of which are unary operators): 717The following casts are currently available (all of which are unary
718operators, that is, have a prototype of C<$>):
718 719
719=over 720=over
720 721
722=item CBOR::XS::as_int $value
723
724Forces the value to be encoded as some form of (basic, not bignum) integer
725type.
726
721=item CBOR::XS::as_text $value 727=item CBOR::XS::as_text $value
722 728
723Forces the value to be encoded as (UTF-8) text values. 729Forces the value to be encoded as (UTF-8) text values.
724 730
725=item CBOR::XS::as_bytes $value 731=item CBOR::XS::as_bytes $value
726 732
727Forces the value to be encoded as a (binary) string value. 733Forces the value to be encoded as a (binary) string value.
728 734
735Example: encode a perl string as binary even though C<text_strings> is in
736effect.
737
738 CBOR::XS->new->text_strings->encode ([4, "text", CBOR::XS::bytes "bytevalue"]);
739
740=item CBOR::XS::as_bool $value
741
742Converts a Perl boolean (which can be any kind of scalar) into a CBOR
743boolean. Strictly the same, but shorter to write, than:
744
745 $value ? Types::Serialiser::true : Types::Serialiser::false
746
729=item CBOR::XS::as_float16 $value 747=item CBOR::XS::as_float16 $value
730 748
731Forces half-float (IEEE 754 binary16) encoding of the given value. 749Forces half-float (IEEE 754 binary16) encoding of the given value.
732 750
733=item CBOR::XS::as_float32 $value 751=item CBOR::XS::as_float32 $value
… …
736 754
737=item CBOR::XS::as_float64 $value 755=item CBOR::XS::as_float64 $value
738 756
739Forces double-float (IEEE 754 binary64) encoding of the given value. 757Forces double-float (IEEE 754 binary64) encoding of the given value.
740 758
741=item, CBOR::XS::as_cbor $cbor_text 759=item CBOR::XS::as_cbor $cbor_text
742 760
743Bot a type cast per-se, this type cast forces the argument to eb encoded 761Not a type cast per-se, this type cast forces the argument to be encoded
744as-is. This can be used to embed pre-encoded CBOR data. 762as-is. This can be used to embed pre-encoded CBOR data.
745 763
746Note that no checking on the validity of the C<$cbor_text> is done - it's 764Note that no checking on the validity of the C<$cbor_text> is done - it's
747the callers responsibility to correctly encode values. 765the callers responsibility to correctly encode values.
748 766
767=item CBOR::XS::as_map [key => value...]
768
769Treat the array reference as key value pairs and output a CBOR map. This
770allows you to generate CBOR maps with arbitrary key types (or, if you
771don't care about semantics, duplicate keys or pairs in a custom order),
772which is otherwise hard to do with Perl.
773
774The single argument must be an array reference with an even number of
775elements.
776
777Note that only the reference to the array is copied, the array itself is
778not. Modifications done to the array before calling an encoding function
779will be reflected in the encoded output.
780
781Example: encode a CBOR map with a string and an integer as keys.
782
783 encode_cbor CBOR::XS::as_map [string => "value", 5 => "value"]
784
749=back 785=back
750 786
751Example: encode a perl string as binary even though C<text_strings> is in
752effect.
753
754 CBOR::XS->new->text_strings->encode ([4, "text", CBOR::XS::bytes "bytevalue"]);
755
756=cut 787=cut
757 788
758sub CBOR::XS::as_cbor ($) { bless [$_[0], 0, undef], CBOR::XS::Tagged:: } 789sub CBOR::XS::as_cbor ($) { bless [$_[0], 0, undef], CBOR::XS::Tagged:: }
790sub CBOR::XS::as_int ($) { bless [$_[0], 1, undef], CBOR::XS::Tagged:: }
759sub CBOR::XS::as_bytes ($) { bless [$_[0], 1, undef], CBOR::XS::Tagged:: } 791sub CBOR::XS::as_bytes ($) { bless [$_[0], 2, undef], CBOR::XS::Tagged:: }
760sub CBOR::XS::as_text ($) { bless [$_[0], 2, undef], CBOR::XS::Tagged:: } 792sub CBOR::XS::as_text ($) { bless [$_[0], 3, undef], CBOR::XS::Tagged:: }
761sub CBOR::XS::as_float16 ($) { bless [$_[0], 3, undef], CBOR::XS::Tagged:: } 793sub CBOR::XS::as_float16 ($) { bless [$_[0], 4, undef], CBOR::XS::Tagged:: }
762sub CBOR::XS::as_float32 ($) { bless [$_[0], 4, undef], CBOR::XS::Tagged:: } 794sub CBOR::XS::as_float32 ($) { bless [$_[0], 5, undef], CBOR::XS::Tagged:: }
763sub CBOR::XS::as_float64 ($) { bless [$_[0], 5, undef], CBOR::XS::Tagged:: } 795sub CBOR::XS::as_float64 ($) { bless [$_[0], 6, undef], CBOR::XS::Tagged:: }
796
797sub CBOR::XS::as_bool ($) { $_[0] ? $Types::Serialiser::true : $Types::Serialiser::false }
798
799sub CBOR::XS::as_map ($) {
800 ARRAY:: eq ref $_[0]
801 and $#{ $_[0] } & 1
802 or do { require Carp; Carp::croak ("CBOR::XS::as_map only acepts array references with an even number of elements, caught") };
803
804 bless [$_[0], 7, undef], CBOR::XS::Tagged::
805}
764 806
765=head2 OBJECT SERIALISATION 807=head2 OBJECT SERIALISATION
766 808
767This module implements both a CBOR-specific and the generic 809This module implements both a CBOR-specific and the generic
768L<Types::Serialier> object serialisation protocol. The following 810L<Types::Serialier> object serialisation protocol. The following

Diff Legend

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