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.21 by root, Wed Nov 20 16:29:02 2013 UTC vs.
Revision 1.22 by root, Fri Nov 22 15:28:38 2013 UTC

… …
627 CBOR::XS::tag 24, 627 CBOR::XS::tag 24,
628 encode_cbor [1, 2, 3]; 628 encode_cbor [1, 2, 3];
629 629
630=head1 TAG HANDLING AND EXTENSIONS 630=head1 TAG HANDLING AND EXTENSIONS
631 631
632This section describes how this module handles specific tagged values and 632This section describes how this module handles specific tagged values
633extensions. If a tag is not mentioned here, then the default handling 633and extensions. If a tag is not mentioned here and no additional filters
634are provided for it, then the default handling applies (creating a
634applies (creating a CBOR::XS::Tagged object on decoding, and only encoding 635CBOR::XS::Tagged object on decoding, and only encoding the tag when
635the tag when explicitly requested). 636explicitly requested).
636 637
637Future versions of this module reserve the right to special case 638Future versions of this module reserve the right to special case
638additional tags (such as bigfloat or base64url). 639additional tags (such as base64url).
640
641=head2 ENFORCED TAGS
642
643These tags are always handled when decoding, and their handling cannot be
644overriden by the user.
639 645
640=over 4 646=over 4
641 647
642=item <unassigned> (perl-object, L<http://cbor.schmorp.de/perl-object>) 648=item <unassigned> (perl-object, L<http://cbor.schmorp.de/perl-object>)
643 649
… …
666 672
667This value is not generated on encoding (unless explicitly requested by 673This value is not generated on encoding (unless explicitly requested by
668the user), and is simply ignored when decoding. 674the user), and is simply ignored when decoding.
669 675
670=back 676=back
677
678=head2 OPTIONAL TAGS
679
680These tags have default filters provided when decoding. Their handling can
681be overriden by changing the C<%CBOR::XS::FILTER> entry for the tag, or by
682providing a custom C<filter> function when decoding.
683
684When they result in decoding into a specific Perl class, the module
685usually provides a corresponding C<TO_CBOR> method as well.
686
687When any of these need to load additional modules that are not part of the
688perl core distribution (e.g. L<URI>), it is (currently) up to the user to
689provide these modules. The decoding usually fails with an exception if the
690required module cannot be loaded.
691
692=over 4
693
694=item 2, 3 (positive/negative bignum)
695
696These tags are decoded into L<Math::BigInt> objects. The corresponding
697C<Math::BigInt::TO_CBOR> method encodes "small" bigints into normal CBOR
698integers, and others into positive/negative CBOR bignums.
699
700=item 4, 5 (decimal fraction/bigfloat)
701
702Both decimal fractions and bigfloats are decoded into L<Math::BigFloat>
703objects. The corresponding C<Math::BigFloat::TO_CBOR> method I<always>
704encodes into a decimal fraction.
705
706CBOR cannot represent bigfloats with I<very> large exponents - conversion
707of such big float objects is undefined.
708
709Also, NaN and infinities are not encoded properly.
710
711=item 21, 22, 23 (expected later JSON conversion)
712
713CBOR::XS is not a CBOR-to-JSON converter, and will simply ignore these
714tags.
715
716=item 32 (URI)
717
718These objects decode into L<URI> objects. The corresponding
719C<URI::TO_CBOR> method again results in a CBOR URI value.
720
721=back
722
723=cut
724
725our %FILTER = (
726 # 0 # rfc4287 datetime, utf-8
727 # 1 # unix timestamp, any
728
729 2 => sub { # pos bigint
730 require Math::BigInt;
731 Math::BigInt->new ("0x" . unpack "H*", pop)
732 },
733
734 3 => sub { # neg bigint
735 require Math::BigInt;
736 -Math::BigInt->new ("0x" . unpack "H*", pop)
737 },
738
739 4 => sub { # decimal fraction, array
740 require Math::BigFloat;
741 Math::BigFloat->new ($_[1][1] . "E" . $_[1][0])
742 },
743
744 5 => sub { # bigfloat, array
745 require Math::BigFloat;
746 scalar Math::BigFloat->new ($_[1][1])->blsft ($_[1][0], 2)
747 },
748
749 21 => sub { pop }, # expected conversion to base64url encoding
750 22 => sub { pop }, # expected conversion to base64 encoding
751 23 => sub { pop }, # expected conversion to base16 encoding
752
753 # 24 # embedded cbor, byte string
754
755 32 => sub {
756 require URI;
757 URI->new (pop)
758 },
759
760 # 33 # base64url rfc4648, utf-8
761 # 34 # base64 rfc46484, utf-8
762 # 35 # regex pcre/ecma262, utf-8
763 # 36 # mime message rfc2045, utf-8
764);
671 765
672 766
673=head1 CBOR and JSON 767=head1 CBOR and JSON
674 768
675CBOR is supposed to implement a superset of the JSON data model, and is, 769CBOR is supposed to implement a superset of the JSON data model, and is,
… …
758Please refrain from using rt.cpan.org or any other bug reporting 852Please refrain from using rt.cpan.org or any other bug reporting
759service. I put the contact address into my modules for a reason. 853service. I put the contact address into my modules for a reason.
760 854
761=cut 855=cut
762 856
857our %FILTER = (
858 # 0 # rfc4287 datetime, utf-8
859 # 1 # unix timestamp, any
860
861 2 => sub { # pos bigint
862 require Math::BigInt;
863 Math::BigInt->new ("0x" . unpack "H*", pop)
864 },
865
866 3 => sub { # neg bigint
867 require Math::BigInt;
868 -Math::BigInt->new ("0x" . unpack "H*", pop)
869 },
870
871 4 => sub { # decimal fraction, array
872 require Math::BigFloat;
873 Math::BigFloat->new ($_[1][1] . "E" . $_[1][0])
874 },
875
876 5 => sub { # bigfloat, array
877 require Math::BigFloat;
878 scalar Math::BigFloat->new ($_[1][1])->blsft ($_[1][0], 2)
879 },
880
881 21 => sub { pop }, # expected conversion to base64url encoding
882 22 => sub { pop }, # expected conversion to base64 encoding
883 23 => sub { pop }, # expected conversion to base16 encoding
884
885 # 24 # embedded cbor, byte string
886
887 32 => sub {
888 require URI;
889 URI->new (pop)
890 },
891
892 # 33 # base64url rfc4648, utf-8
893 # 34 # base64 rfc46484, utf-8
894 # 35 # regex pcre/ecma262, utf-8
895 # 36 # mime message rfc2045, utf-8
896);
897
898sub CBOR::XS::default_filter {
899 &{ $FILTER{$_[0]} or return }
900}
901
902sub URI::TO_CBOR {
903 my $uri = $_[0]->as_string;
904 utf8::upgrade $uri;
905 CBOR::XS::tag 32, $uri
906}
907
908sub Math::BigInt::TO_CBOR {
909 if ($_[0] >= -2147483648 && $_[0] <= 2147483647) {
910 $_[0]->numify
911 } else {
912 my $hex = substr $_[0]->as_hex, 2;
913 $hex = "0$hex" if 1 & length $hex; # sigh
914 CBOR::XS::tag $_[0] >= 0 ? 2 : 3, pack "H*", $hex
915 }
916}
917
918sub Math::BigFloat::TO_CBOR {
919 my ($m, $e) = $_[0]->parts;
920 CBOR::XS::tag 4, [$e->numify, $m]
921}
922
763XSLoader::load "CBOR::XS", $VERSION; 923XSLoader::load "CBOR::XS", $VERSION;
764 924
765=head1 SEE ALSO 925=head1 SEE ALSO
766 926
767The L<JSON> and L<JSON::XS> modules that do similar, but human-readable, 927The L<JSON> and L<JSON::XS> modules that do similar, but human-readable,

Diff Legend

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