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.41 by root, Mon Jan 6 04:15:31 2014 UTC vs.
Revision 1.51 by root, Sun Apr 24 19:16:15 2016 UTC

64 64
65package CBOR::XS; 65package CBOR::XS;
66 66
67use common::sense; 67use common::sense;
68 68
69our $VERSION = 1.25; 69our $VERSION = 1.41;
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;
224cycles - future versions of this module might chose to decode cyclic data 224cycles - future versions of this module might chose to decode cyclic data
225structures using weak references when this option is off, instead of 225structures using weak references when this option is off, instead of
226throwing an error. 226throwing an error.
227 227
228This option does not affect C<encode> in any way - shared values and 228This option does not affect C<encode> in any way - shared values and
229references will always be decoded properly if present. 229references will always be encoded properly if present.
230 230
231=item $cbor = $cbor->pack_strings ([$enable]) 231=item $cbor = $cbor->pack_strings ([$enable])
232 232
233=item $enabled = $cbor->get_pack_strings 233=item $enabled = $cbor->get_pack_strings
234 234
261The concept of "valid UTF-8" used is perl's concept, which is a superset 261The concept of "valid UTF-8" used is perl's concept, which is a superset
262of the official UTF-8. 262of the official UTF-8.
263 263
264If C<$enable> is false (the default), then C<decode> will blindly accept 264If C<$enable> is false (the default), then C<decode> will blindly accept
265UTF-8 data, marking them as valid UTF-8 in the resulting data structure 265UTF-8 data, marking them as valid UTF-8 in the resulting data structure
266regardless of whether thats true or not. 266regardless of whether that's true or not.
267 267
268Perl isn't too happy about corrupted UTF-8 in strings, but should 268Perl isn't too happy about corrupted UTF-8 in strings, but should
269generally not crash or do similarly evil things. Extensions might be not 269generally not crash or do similarly evil things. Extensions might be not
270so forgiving, so it's recommended to turn on this setting if you receive 270so forgiving, so it's recommended to turn on this setting if you receive
271untrusted CBOR. 271untrusted CBOR.
481 481
482=item hash references 482=item hash references
483 483
484Perl hash references become CBOR maps. As there is no inherent ordering in 484Perl hash references become CBOR maps. As there is no inherent ordering in
485hash keys (or CBOR maps), they will usually be encoded in a pseudo-random 485hash keys (or CBOR maps), they will usually be encoded in a pseudo-random
486order. This order can be different each time a hahs is encoded. 486order. This order can be different each time a hash is encoded.
487 487
488Currently, tied hashes will use the indefinite-length format, while normal 488Currently, tied hashes will use the indefinite-length format, while normal
489hashes will use the fixed-length format. 489hashes will use the fixed-length format.
490 490
491=item array references 491=item array references
804additional tags (such as base64url). 804additional tags (such as base64url).
805 805
806=head2 ENFORCED TAGS 806=head2 ENFORCED TAGS
807 807
808These tags are always handled when decoding, and their handling cannot be 808These tags are always handled when decoding, and their handling cannot be
809overriden by the user. 809overridden by the user.
810 810
811=over 4 811=over 4
812 812
813=item 26 (perl-object, L<http://cbor.schmorp.de/perl-object>) 813=item 26 (perl-object, L<http://cbor.schmorp.de/perl-object>)
814 814
815These tags are automatically created (and decoded) for serialisable 815These tags are automatically created (and decoded) for serialisable
816objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object 816objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object
817serialisation protocol). See L<OBJECT SERIALISATION> for details. 817serialisation protocol). See L<OBJECT SERIALISATION> for details.
818 818
819=item 28, 29 (shareable, sharedref, L <http://cbor.schmorp.de/value-sharing>) 819=item 28, 29 (shareable, sharedref, L<http://cbor.schmorp.de/value-sharing>)
820 820
821These tags are automatically decoded when encountered (and they do not 821These tags are automatically decoded when encountered (and they do not
822result in a cyclic data structure, see C<allow_cycles>), resulting in 822result in a cyclic data structure, see C<allow_cycles>), resulting in
823shared values in the decoded object. They are only encoded, however, when 823shared values in the decoded object. They are only encoded, however, when
824C<allow_sharing> is enabled. 824C<allow_sharing> is enabled.
834will be shared, others will not. While non-reference shared values can be 834will be shared, others will not. While non-reference shared values can be
835generated in Perl with some effort, they were considered too unimportant 835generated in Perl with some effort, they were considered too unimportant
836to be supported in the encoder. The decoder, however, will decode these 836to be supported in the encoder. The decoder, however, will decode these
837values as shared values. 837values as shared values.
838 838
839=item 256, 25 (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>) 839=item 256, 25 (stringref-namespace, stringref, L<http://cbor.schmorp.de/stringref>)
840 840
841These tags are automatically decoded when encountered. They are only 841These tags are automatically decoded when encountered. They are only
842encoded, however, when C<pack_strings> is enabled. 842encoded, however, when C<pack_strings> is enabled.
843 843
844=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>) 844=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>)
845 845
846This tag is automatically generated when a reference are encountered (with 846This tag is automatically generated when a reference are encountered (with
847the exception of hash and array refernces). It is converted to a reference 847the exception of hash and array references). It is converted to a reference
848when decoding. 848when decoding.
849 849
850=item 55799 (self-describe CBOR, RFC 7049) 850=item 55799 (self-describe CBOR, RFC 7049)
851 851
852This value is not generated on encoding (unless explicitly requested by 852This value is not generated on encoding (unless explicitly requested by
855=back 855=back
856 856
857=head2 NON-ENFORCED TAGS 857=head2 NON-ENFORCED TAGS
858 858
859These tags have default filters provided when decoding. Their handling can 859These tags have default filters provided when decoding. Their handling can
860be overriden by changing the C<%CBOR::XS::FILTER> entry for the tag, or by 860be overridden by changing the C<%CBOR::XS::FILTER> entry for the tag, or by
861providing a custom C<filter> callback when decoding. 861providing a custom C<filter> callback when decoding.
862 862
863When they result in decoding into a specific Perl class, the module 863When they result in decoding into a specific Perl class, the module
864usually provides a corresponding C<TO_CBOR> method as well. 864usually provides a corresponding C<TO_CBOR> method as well.
865 865
907C<URI::TO_CBOR> method again results in a CBOR URI value. 907C<URI::TO_CBOR> method again results in a CBOR URI value.
908 908
909=back 909=back
910 910
911=cut 911=cut
912
913our %FILTER = (
914 # 0 # rfc4287 datetime, utf-8
915 # 1 # unix timestamp, any
916
917 2 => sub { # pos bigint
918 require Math::BigInt;
919 Math::BigInt->new ("0x" . unpack "H*", pop)
920 },
921
922 3 => sub { # neg bigint
923 require Math::BigInt;
924 -Math::BigInt->new ("0x" . unpack "H*", pop)
925 },
926
927 4 => sub { # decimal fraction, array
928 require Math::BigFloat;
929 Math::BigFloat->new ($_[1][1] . "E" . $_[1][0])
930 },
931
932 5 => sub { # bigfloat, array
933 require Math::BigFloat;
934 scalar Math::BigFloat->new ($_[1][1])->blsft ($_[1][0], 2)
935 },
936
937 21 => sub { pop }, # expected conversion to base64url encoding
938 22 => sub { pop }, # expected conversion to base64 encoding
939 23 => sub { pop }, # expected conversion to base16 encoding
940
941 # 24 # embedded cbor, byte string
942
943 32 => sub {
944 require URI;
945 URI->new (pop)
946 },
947
948 # 33 # base64url rfc4648, utf-8
949 # 34 # base64 rfc46484, utf-8
950 # 35 # regex pcre/ecma262, utf-8
951 # 36 # mime message rfc2045, utf-8
952);
953
954 912
955=head1 CBOR and JSON 913=head1 CBOR and JSON
956 914
957CBOR is supposed to implement a superset of the JSON data model, and is, 915CBOR is supposed to implement a superset of the JSON data model, and is,
958with some coercion, able to represent all JSON texts (something that other 916with some coercion, able to represent all JSON texts (something that other
1022 980
1023 981
1024=head1 LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT 982=head1 LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT
1025 983
1026On perls that were built without 64 bit integer support (these are rare 984On perls that were built without 64 bit integer support (these are rare
1027nowadays, even on 32 bit architectures), support for any kind of 64 bit 985nowadays, even on 32 bit architectures, as all major Perl distributions
986are built with 64 bit integer support), support for any kind of 64 bit
1028integer in CBOR is very limited - most likely, these 64 bit values will 987integer in CBOR is very limited - most likely, these 64 bit values will
1029be truncated, corrupted, or otherwise not decoded correctly. This also 988be truncated, corrupted, or otherwise not decoded correctly. This also
1030includes string, array and map sizes that are stored as 64 bit integers. 989includes string, array and map sizes that are stored as 64 bit integers.
1031 990
1032 991
1057 # Time::Piece::Strptime uses the "incredibly flexible date parsing routine" 1016 # Time::Piece::Strptime uses the "incredibly flexible date parsing routine"
1058 # from FreeBSD, which can't parse ISO 8601, RFC3339, RFC4287 or much of anything 1017 # from FreeBSD, which can't parse ISO 8601, RFC3339, RFC4287 or much of anything
1059 # else either. Whats incredibe over standard strptime totally escapes me. 1018 # else either. Whats incredibe over standard strptime totally escapes me.
1060 # doesn't do fractional times, either. sigh. 1019 # doesn't do fractional times, either. sigh.
1061 # In fact, it's all a lie, it uses whatever strptime it wants, and of course, 1020 # In fact, it's all a lie, it uses whatever strptime it wants, and of course,
1062 # they are all incomptible. The openbsd one simply ignores %z (but according to the 1021 # they are all incompatible. The openbsd one simply ignores %z (but according to the
1063 # docs, it would be much more incredibly flexible indeed. If it worked, that is.). 1022 # docs, it would be much more incredibly flexible indeed. If it worked, that is.).
1064 scalar eval { 1023 scalar eval {
1065 my $s = $_[1]; 1024 my $s = $_[1];
1066 1025
1067 $s =~ s/Z$/+00:00/; 1026 $s =~ s/Z$/+00:00/;
1095 Math::BigFloat->new ($_[1][1] . "E" . $_[1][0]) 1054 Math::BigFloat->new ($_[1][1] . "E" . $_[1][0])
1096 }, 1055 },
1097 1056
1098 5 => sub { # bigfloat, array 1057 5 => sub { # bigfloat, array
1099 require Math::BigFloat; 1058 require Math::BigFloat;
1100 scalar Math::BigFloat->new ($_[1][1])->blsft ($_[1][0], 2) 1059 scalar Math::BigFloat->new ($_[1][1]) * Math::BigFloat->new (2)->bpow ($_[1][0])
1101 }, 1060 },
1102 1061
1103 21 => sub { pop }, # expected conversion to base64url encoding 1062 21 => sub { pop }, # expected conversion to base64url encoding
1104 22 => sub { pop }, # expected conversion to base64 encoding 1063 22 => sub { pop }, # expected conversion to base64 encoding
1105 23 => sub { pop }, # expected conversion to base16 encoding 1064 23 => sub { pop }, # expected conversion to base16 encoding

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines