[ViewVC] Diff of: cvs/CBOR-XS/XS.pm

Comparing CBOR-XS/XS.pm (file contents):
Revision 1.21 by root, Wed Nov 20 16:29:02 2013 UTC vs.
Revision 1.23 by root, Fri Nov 22 16:00:30 2013 UTC

…		…
118	strings. All boolean flags described below are by default I<disabled>.	118	strings. All boolean flags described below are by default I<disabled>.
119		119
120	The mutators for flags all return the CBOR object again and thus calls can	120	The mutators for flags all return the CBOR object again and thus calls can
121	be chained:	121	be chained:
122		122
123	#TODO
124	my $cbor = CBOR::XS->new->encode ({a => [1,2]});	123	my $cbor = CBOR::XS->new->encode ({a => [1,2]});
125		124
126	=item $cbor = $cbor->max_depth ([$maximum_nesting_depth])	125	=item $cbor = $cbor->max_depth ([$maximum_nesting_depth])
127		126
128	=item $max_depth = $cbor->get_max_depth	127	=item $max_depth = $cbor->get_max_depth
…		…
230	exception when it encounters anything it cannot encode as CBOR.	229	exception when it encounters anything it cannot encode as CBOR.
231		230
232	This option does not affect C<decode> in any way - string references will	231	This option does not affect C<decode> in any way - string references will
233	always be decoded properly if present.	232	always be decoded properly if present.
234		233
		234	=item $cbor = $cbor->filter ([$cb->($tag, $value)])
		235
		236	=item $cb_or_undef = $cbor->get_filter
		237
		238	TODO
		239
235	=item $cbor_data = $cbor->encode ($perl_scalar)	240	=item $cbor_data = $cbor->encode ($perl_scalar)
236		241
237	Converts the given Perl data structure (a scalar value) to its CBOR	242	Converts the given Perl data structure (a scalar value) to its CBOR
238	representation.	243	representation.
239		244
…		…
307	C<Types:Serialiser::false> and C<Types::Serialiser::error>,	312	C<Types:Serialiser::false> and C<Types::Serialiser::error>,
308	respectively. They are overloaded to act almost exactly like the numbers	313	respectively. They are overloaded to act almost exactly like the numbers
309	C<1> and C<0> (for true and false) or to throw an exception on access (for	314	C<1> and C<0> (for true and false) or to throw an exception on access (for
310	error). See the L<Types::Serialiser> manpage for details.	315	error). See the L<Types::Serialiser> manpage for details.
311		316
312	=item CBOR tag 256 (perl object)	317	=item tagged values
313		318
314	The tag value C<256> (TODO: pending iana registration) will be used
315	to deserialise a Perl object serialised with C<FREEZE>. See L<OBJECT
316	SERIALISATION>, below, for details.
317
318	=item CBOR tag 55799 (magic header)
319
320	The tag 55799 is ignored (this tag implements the magic header).
321
322	=item other CBOR tags
323
324	Tagged items consists of a numeric tag and another CBOR value. Tags not	319	Tagged items consists of a numeric tag and another CBOR value.
325	handled internally are currently converted into a L<CBOR::XS::Tagged>
326	object, which is simply a blessed array reference consisting of the
327	numeric tag value followed by the (decoded) CBOR value.
328		320
329	In the future, support for user-supplied conversions might get added.	321	See L<TAG HANDLING AND EXTENSIONS> and the description of C<< ->filter >>
		322	for details.
330		323
331	=item anything else	324	=item anything else
332		325
333	Anything else (e.g. unsupported simple values) will raise a decoding	326	Anything else (e.g. unsupported simple values) will raise a decoding
334	error.	327	error.
…		…
377	if you want.	370	if you want.
378		371
379	=item other blessed objects	372	=item other blessed objects
380		373
381	Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See	374	Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See
382	L<OBJECT SERIALISATION>, below, for details.	375	L<TAG HANDLING AND EXTENSIONS> for specific classes handled by this
		376	module, and L<OBJECT SERIALISATION> for generic object serialisation.
383		377
384	=item simple scalars	378	=item simple scalars
385		379
386	TODO
387	Simple Perl scalars (any scalar that is not a reference) are the most	380	Simple Perl scalars (any scalar that is not a reference) are the most
388	difficult objects to encode: CBOR::XS will encode undefined scalars as	381	difficult objects to encode: CBOR::XS will encode undefined scalars as
389	CBOR null values, scalars that have last been used in a string context	382	CBOR null values, scalars that have last been used in a string context
390	before encoding as CBOR strings, and anything else as number value:	383	before encoding as CBOR strings, and anything else as number value:
391		384
…		…
627	CBOR::XS::tag 24,	620	CBOR::XS::tag 24,
628	encode_cbor [1, 2, 3];	621	encode_cbor [1, 2, 3];
629		622
630	=head1 TAG HANDLING AND EXTENSIONS	623	=head1 TAG HANDLING AND EXTENSIONS
631		624
632	This section describes how this module handles specific tagged values and	625	This section describes how this module handles specific tagged values
633	extensions. If a tag is not mentioned here, then the default handling	626	and extensions. If a tag is not mentioned here and no additional filters
		627	are provided for it, then the default handling applies (creating a
634	applies (creating a CBOR::XS::Tagged object on decoding, and only encoding	628	CBOR::XS::Tagged object on decoding, and only encoding the tag when
635	the tag when explicitly requested).	629	explicitly requested).
		630
		631	Tags not handled specifically are currently converted into a
		632	L<CBOR::XS::Tagged> object, which is simply a blessed array reference
		633	consisting of the numeric tag value followed by the (decoded) CBOR value.
636		634
637	Future versions of this module reserve the right to special case	635	Future versions of this module reserve the right to special case
638	additional tags (such as bigfloat or base64url).	636	additional tags (such as base64url).
		637
		638	=head2 ENFORCED TAGS
		639
		640	These tags are always handled when decoding, and their handling cannot be
		641	overriden by the user.
639		642
640	=over 4	643	=over 4
641		644
642	=item <unassigned> (perl-object, L<http://cbor.schmorp.de/perl-object>)	645	=item <unassigned> (perl-object, L<http://cbor.schmorp.de/perl-object>)
643		646
644	These tags are automatically created for serialisable objects using the	647	These tags are automatically created (and decoded) for serialisable
645	C<FREEZE/THAW> methods (the L<Types::Serialier> object serialisation	648	objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object
646	protocol).	649	serialisation protocol). See L<OBJECT SERIALISATION> for details.
647		650
648	=item <unassigned>, <unassigned> (sharable, sharedref, L <http://cbor.schmorp.de/value-sharing>)	651	=item <unassigned>, <unassigned> (sharable, sharedref, L <http://cbor.schmorp.de/value-sharing>)
649		652
650	These tags are automatically decoded when encountered, resulting in	653	These tags are automatically decoded when encountered, resulting in
651	shared values in the decoded object. They are only encoded, however, when	654	shared values in the decoded object. They are only encoded, however, when
…		…
666		669
667	This value is not generated on encoding (unless explicitly requested by	670	This value is not generated on encoding (unless explicitly requested by
668	the user), and is simply ignored when decoding.	671	the user), and is simply ignored when decoding.
669		672
670	=back	673	=back
		674
		675	=head2 OPTIONAL TAGS
		676
		677	These tags have default filters provided when decoding. Their handling can
		678	be overriden by changing the C<%CBOR::XS::FILTER> entry for the tag, or by
		679	providing a custom C<filter> function when decoding.
		680
		681	When they result in decoding into a specific Perl class, the module
		682	usually provides a corresponding C<TO_CBOR> method as well.
		683
		684	When any of these need to load additional modules that are not part of the
		685	perl core distribution (e.g. L<URI>), it is (currently) up to the user to
		686	provide these modules. The decoding usually fails with an exception if the
		687	required module cannot be loaded.
		688
		689	=over 4
		690
		691	=item 2, 3 (positive/negative bignum)
		692
		693	These tags are decoded into L<Math::BigInt> objects. The corresponding
		694	C<Math::BigInt::TO_CBOR> method encodes "small" bigints into normal CBOR
		695	integers, and others into positive/negative CBOR bignums.
		696
		697	=item 4, 5 (decimal fraction/bigfloat)
		698
		699	Both decimal fractions and bigfloats are decoded into L<Math::BigFloat>
		700	objects. The corresponding C<Math::BigFloat::TO_CBOR> method I<always>
		701	encodes into a decimal fraction.
		702
		703	CBOR cannot represent bigfloats with I<very> large exponents - conversion
		704	of such big float objects is undefined.
		705
		706	Also, NaN and infinities are not encoded properly.
		707
		708	=item 21, 22, 23 (expected later JSON conversion)
		709
		710	CBOR::XS is not a CBOR-to-JSON converter, and will simply ignore these
		711	tags.
		712
		713	=item 32 (URI)
		714
		715	These objects decode into L<URI> objects. The corresponding
		716	C<URI::TO_CBOR> method again results in a CBOR URI value.
		717
		718	=back
		719
		720	=cut
		721
		722	our %FILTER = (
		723	# 0 # rfc4287 datetime, utf-8
		724	# 1 # unix timestamp, any
		725
		726	2 => sub { # pos bigint
		727	require Math::BigInt;
		728	Math::BigInt->new ("0x" . unpack "H*", pop)
		729	},
		730
		731	3 => sub { # neg bigint
		732	require Math::BigInt;
		733	-Math::BigInt->new ("0x" . unpack "H*", pop)
		734	},
		735
		736	4 => sub { # decimal fraction, array
		737	require Math::BigFloat;
		738	Math::BigFloat->new ($_[1][1] . "E" . $_[1][0])
		739	},
		740
		741	5 => sub { # bigfloat, array
		742	require Math::BigFloat;
		743	scalar Math::BigFloat->new ($_[1][1])->blsft ($_[1][0], 2)
		744	},
		745
		746	21 => sub { pop }, # expected conversion to base64url encoding
		747	22 => sub { pop }, # expected conversion to base64 encoding
		748	23 => sub { pop }, # expected conversion to base16 encoding
		749
		750	# 24 # embedded cbor, byte string
		751
		752	32 => sub {
		753	require URI;
		754	URI->new (pop)
		755	},
		756
		757	# 33 # base64url rfc4648, utf-8
		758	# 34 # base64 rfc46484, utf-8
		759	# 35 # regex pcre/ecma262, utf-8
		760	# 36 # mime message rfc2045, utf-8
		761	);
671		762
672		763
673	=head1 CBOR and JSON	764	=head1 CBOR and JSON
674		765
675	CBOR is supposed to implement a superset of the JSON data model, and is,	766	CBOR is supposed to implement a superset of the JSON data model, and is,
…		…
758	Please refrain from using rt.cpan.org or any other bug reporting	849	Please refrain from using rt.cpan.org or any other bug reporting
759	service. I put the contact address into my modules for a reason.	850	service. I put the contact address into my modules for a reason.
760		851
761	=cut	852	=cut
762		853
		854	our %FILTER = (
		855	# 0 # rfc4287 datetime, utf-8
		856	# 1 # unix timestamp, any
		857
		858	2 => sub { # pos bigint
		859	require Math::BigInt;
		860	Math::BigInt->new ("0x" . unpack "H*", pop)
		861	},
		862
		863	3 => sub { # neg bigint
		864	require Math::BigInt;
		865	-Math::BigInt->new ("0x" . unpack "H*", pop)
		866	},
		867
		868	4 => sub { # decimal fraction, array
		869	require Math::BigFloat;
		870	Math::BigFloat->new ($_[1][1] . "E" . $_[1][0])
		871	},
		872
		873	5 => sub { # bigfloat, array
		874	require Math::BigFloat;
		875	scalar Math::BigFloat->new ($_[1][1])->blsft ($_[1][0], 2)
		876	},
		877
		878	21 => sub { pop }, # expected conversion to base64url encoding
		879	22 => sub { pop }, # expected conversion to base64 encoding
		880	23 => sub { pop }, # expected conversion to base16 encoding
		881
		882	# 24 # embedded cbor, byte string
		883
		884	32 => sub {
		885	require URI;
		886	URI->new (pop)
		887	},
		888
		889	# 33 # base64url rfc4648, utf-8
		890	# 34 # base64 rfc46484, utf-8
		891	# 35 # regex pcre/ecma262, utf-8
		892	# 36 # mime message rfc2045, utf-8
		893	);
		894
		895	sub CBOR::XS::default_filter {
		896	&{ $FILTER{$_[0]} or return }
		897	}
		898
		899	sub URI::TO_CBOR {
		900	my $uri = $_[0]->as_string;
		901	utf8::upgrade $uri;
		902	CBOR::XS::tag 32, $uri
		903	}
		904
		905	sub Math::BigInt::TO_CBOR {
		906	if ($_[0] >= -2147483648 && $_[0] <= 2147483647) {
		907	$_[0]->numify
		908	} else {
		909	my $hex = substr $_[0]->as_hex, 2;
		910	$hex = "0$hex" if 1 & length $hex; # sigh
		911	CBOR::XS::tag $_[0] >= 0 ? 2 : 3, pack "H*", $hex
		912	}
		913	}
		914
		915	sub Math::BigFloat::TO_CBOR {
		916	my ($m, $e) = $_[0]->parts;
		917	CBOR::XS::tag 4, [$e->numify, $m]
		918	}
		919
763	XSLoader::load "CBOR::XS", $VERSION;	920	XSLoader::load "CBOR::XS", $VERSION;
764		921
765	=head1 SEE ALSO	922	=head1 SEE ALSO
766		923
767	The L<JSON> and L<JSON::XS> modules that do similar, but human-readable,	924	The L<JSON> and L<JSON::XS> modules that do similar, but human-readable,

Diff Legend

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

Comparing CBOR-XS/XS.pm (file contents): Revision 1.21 by root, Wed Nov 20 16:29:02 2013 UTC vs. Revision 1.23 by root, Fri Nov 22 16:00:30 2013 UTC

Diff Legend

Comparing CBOR-XS/XS.pm (file contents):
Revision 1.21 by root, Wed Nov 20 16:29:02 2013 UTC vs.
Revision 1.23 by root, Fri Nov 22 16:00:30 2013 UTC