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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.145 by root, Tue Oct 29 00:06:40 2013 UTC vs.
Revision 1.153 by root, Sun Mar 2 20:41:14 2014 UTC

…		…
101		101
102	package JSON::XS;	102	package JSON::XS;
103		103
104	use common::sense;	104	use common::sense;
105		105
106	our $VERSION = '3.0';	106	our $VERSION = 3.01;
107	our @ISA = qw(Exporter);	107	our @ISA = qw(Exporter);
108		108
109	our @EXPORT = qw(encode_json decode_json);	109	our @EXPORT = qw(encode_json decode_json);
110		110
111	use Exporter;	111	use Exporter;
…		…
467		467
468	=item $json = $json->allow_blessed ([$enable])	468	=item $json = $json->allow_blessed ([$enable])
469		469
470	=item $enabled = $json->get_allow_blessed	470	=item $enabled = $json->get_allow_blessed
471		471
		472	See L<OBJECT SERIALISATION> for details.
		473
472	If C<$enable> is true (or missing), then the C<encode> method will not	474	If C<$enable> is true (or missing), then the C<encode> method will not
473	barf when it encounters a blessed reference. Instead, the value of the	475	barf when it encounters a blessed reference that it cannot convert
474	B<convert_blessed> option will decide whether C<null> (C<convert_blessed>	476	otherwise. Instead, a JSON C<null> value is encoded instead of the object.
475	disabled or no C<TO_JSON> method found) or a representation of the
476	object (C<convert_blessed> enabled and C<TO_JSON> method found) is being
477	encoded. Has no effect on C<decode>.
478		477
479	If C<$enable> is false (the default), then C<encode> will throw an	478	If C<$enable> is false (the default), then C<encode> will throw an
480	exception when it encounters a blessed object.	479	exception when it encounters a blessed object that it cannot convert
		480	otherwise.
		481
		482	This setting has no effect on C<decode>.
481		483
482	=item $json = $json->convert_blessed ([$enable])	484	=item $json = $json->convert_blessed ([$enable])
483		485
484	=item $enabled = $json->get_convert_blessed	486	=item $enabled = $json->get_convert_blessed
		487
		488	See L<OBJECT SERIALISATION> for details.
485		489
486	If C<$enable> is true (or missing), then C<encode>, upon encountering a	490	If C<$enable> is true (or missing), then C<encode>, upon encountering a
487	blessed object, will check for the availability of the C<TO_JSON> method	491	blessed object, will check for the availability of the C<TO_JSON> method
488	on the object's class. If found, it will be called in scalar context	492	on the object's class. If found, it will be called in scalar context and
489	and the resulting scalar will be encoded instead of the object. If no	493	the resulting scalar will be encoded instead of the object.
490	C<TO_JSON> method is found, the value of C<allow_blessed> will decide what
491	to do.
492		494
493	The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>	495	The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
494	returns other blessed objects, those will be handled in the same	496	returns other blessed objects, those will be handled in the same
495	way. C<TO_JSON> must take care of not causing an endless recursion cycle	497	way. C<TO_JSON> must take care of not causing an endless recursion cycle
496	(== crash) in this case. The name of C<TO_JSON> was chosen because other	498	(== crash) in this case. The name of C<TO_JSON> was chosen because other
497	methods called by the Perl core (== not by the user of the object) are	499	methods called by the Perl core (== not by the user of the object) are
498	usually in upper case letters and to avoid collisions with any C<to_json>	500	usually in upper case letters and to avoid collisions with any C<to_json>
499	function or method.	501	function or method.
500		502
501	This setting does not yet influence C<decode> in any way, but in the	503	If C<$enable> is false (the default), then C<encode> will not consider
502	future, global hooks might get installed that influence C<decode> and are	504	this type of conversion.
503	enabled by this setting.
504		505
505	If C<$enable> is false, then the C<allow_blessed> setting will decide what	506	This setting has no effect on C<decode>.
506	to do when a blessed object is found.	507
		508	=item $json = $json->allow_tags ([$enable])
		509
		510	=item $enabled = $json->allow_tags
		511
		512	See L<OBJECT SERIALISATION> for details.
		513
		514	If C<$enable> is true (or missing), then C<encode>, upon encountering a
		515	blessed object, will check for the availability of the C<FREEZE> method on
		516	the object's class. If found, it will be used to serialise the object into
		517	a nonstandard tagged JSON value (that JSON decoders cannot decode).
		518
		519	It also causes C<decode> to parse such tagged JSON values and deserialise
		520	them via a call to the C<THAW> method.
		521
		522	If C<$enable> is false (the default), then C<encode> will not consider
		523	this type of conversion, and tagged JSON values will cause a parse error
		524	in C<decode>, as if tags were not part of the grammar.
507		525
508	=item $json = $json->filter_json_object ([$coderef->($hashref)])	526	=item $json = $json->filter_json_object ([$coderef->($hashref)])
509		527
510	When C<$coderef> is specified, it will be called from C<decode> each	528	When C<$coderef> is specified, it will be called from C<decode> each
511	time it decodes a JSON object. The only argument is a reference to the	529	time it decodes a JSON object. The only argument is a reference to the
…		…
999	Another nonstandard extension to the JSON syntax, enabled with the	1017	Another nonstandard extension to the JSON syntax, enabled with the
1000	C<allow_tags> setting, are tagged values. In this implementation, the	1018	C<allow_tags> setting, are tagged values. In this implementation, the
1001	I<tag> must be a perl package/class name encoded as a JSON string, and the	1019	I<tag> must be a perl package/class name encoded as a JSON string, and the
1002	I<value> must be a JSON array encoding optional constructor arguments.	1020	I<value> must be a JSON array encoding optional constructor arguments.
1003		1021
1004	See "OBJECT SERIALISATION", below, for details.	1022	See L<OBJECT SERIALISATION>, below, for details.
1005		1023
1006	=back	1024	=back
1007		1025
1008		1026
1009	=head2 PERL -> JSON	1027	=head2 PERL -> JSON
…		…
1048	directly if you want.	1066	directly if you want.
1049		1067
1050	=item blessed objects	1068	=item blessed objects
1051		1069
1052	Blessed objects are not directly representable in JSON, but C<JSON::XS>	1070	Blessed objects are not directly representable in JSON, but C<JSON::XS>
1053	allows various ways of handling objects. See "OBJECT SERIALISATION",	1071	allows various ways of handling objects. See L<OBJECT SERIALISATION>,
1054	below, for details.	1072	below, for details.
1055		1073
1056	=item simple scalars	1074	=item simple scalars
1057		1075
1058	Simple Perl scalars (any scalar that is not a reference) are the most	1076	Simple Perl scalars (any scalar that is not a reference) are the most
…		…
1111	C<allow_blessed>, C<convert_blessed> and C<allow_tags> settings, which are	1129	C<allow_blessed>, C<convert_blessed> and C<allow_tags> settings, which are
1112	used in this order:	1130	used in this order:
1113		1131
1114	=over 4	1132	=over 4
1115		1133
1116	=item 1. C<allow_tags> is enabled and object has a C<FREEZE> method.	1134	=item 1. C<allow_tags> is enabled and the object has a C<FREEZE> method.
1117		1135
1118	In this case, C<JSON::XS> uses the L<Types::Serialiser> object	1136	In this case, C<JSON::XS> uses the L<Types::Serialiser> object
1119	serialisation protocol to create a tagged JSON value, using a nonstandard	1137	serialisation protocol to create a tagged JSON value, using a nonstandard
1120	extension to the JSON syntax.	1138	extension to the JSON syntax.
1121		1139
…		…
1127	more). These values and the paclkage/classname of the object will then be	1145	more). These values and the paclkage/classname of the object will then be
1128	encoded as a tagged JSON value in the following format:	1146	encoded as a tagged JSON value in the following format:
1129		1147
1130	("classname")[FREEZE return values...]	1148	("classname")[FREEZE return values...]
1131		1149
		1150	e.g.:
		1151
		1152	("URI")["http://www.google.com/"]
		1153	("MyDate")[2013,10,29]
		1154	("ImageData::JPEG")["Z3...VlCg=="]
		1155
1132	For example, the hypothetical C<My::Object> C<FREEZE> method might use the	1156	For example, the hypothetical C<My::Object> C<FREEZE> method might use the
1133	objects C<type> and C<id> members to encode the object:	1157	objects C<type> and C<id> members to encode the object:
1134		1158
1135	sub My::Object::FREEZE {	1159	sub My::Object::FREEZE {
1136	my ($self, $serialiser) = @_;	1160	my ($self, $serialiser) = @_;
1137		1161
1138	($self->{type}, $self->{id})	1162	($self->{type}, $self->{id})
1139	}	1163	}
1140		1164
1141	=item 2. C<convert_blessed> is enabled and object has a C<TO_JSON> method.	1165	=item 2. C<convert_blessed> is enabled and the object has a C<TO_JSON> method.
1142		1166
1143	In this case, the C<TO_JSON> method of the object is invoked in scalar	1167	In this case, the C<TO_JSON> method of the object is invoked in scalar
1144	context. It must return a single scalar that can be directly encoded into	1168	context. It must return a single scalar that can be directly encoded into
1145	JSON. This scalar replaces the object in the JSON text.	1169	JSON. This scalar replaces the object in the JSON text.
1146		1170
…		…
1176	This section only considers the tagged value case: I a tagged JSON object	1200	This section only considers the tagged value case: I a tagged JSON object
1177	is encountered during decoding and C<allow_tags> is disabled, a parse	1201	is encountered during decoding and C<allow_tags> is disabled, a parse
1178	error will result (as if tagged values were not part of the grammar).	1202	error will result (as if tagged values were not part of the grammar).
1179		1203
1180	If C<allow_tags> is enabled, C<JSON::XS> will look up the C<THAW> method	1204	If C<allow_tags> is enabled, C<JSON::XS> will look up the C<THAW> method
1181	of the package/classname used during serialisation. If there is no such	1205	of the package/classname used during serialisation (it will not attempt
		1206	to load the package as a Perl module). If there is no such method, the
1182	method, the decoding will fail with an error.	1207	decoding will fail with an error.
1183		1208
1184	Otherwise, the C<THAW> method is invoked with the classname as first	1209	Otherwise, the C<THAW> method is invoked with the classname as first
1185	argument, the constant string C<JSON> as second argument, and all the	1210	argument, the constant string C<JSON> as second argument, and all the
1186	values from the JSON array (the values originally returned by the	1211	values from the JSON array (the values originally returned by the
1187	C<FREEZE> method) as remaining arguments.	1212	C<FREEZE> method) as remaining arguments.
…		…
1536	constants. That means that the JSON true and false values will be	1561	constants. That means that the JSON true and false values will be
1537	comaptible to true and false values of iother modules that do the same,	1562	comaptible to true and false values of iother modules that do the same,
1538	such as L<JSON::PP> and L<CBOR::XS>.	1563	such as L<JSON::PP> and L<CBOR::XS>.
1539		1564
1540		1565
		1566	=head1 INTEROPERABILITY WITH OTHER JSON DECODERS
		1567
		1568	As long as you only serialise data that can be directly expressed in JSON,
		1569	C<JSON::XS> is incapable of generating invalid JSON output (modulo bugs,
		1570	but C<JSON::XS> has found more bugs in the official JSON testsuite (1)
		1571	than the official JSON testsuite has found in C<JSON::XS> (0)).
		1572
		1573	When you have trouble decoding JSON generated by this module using other
		1574	decoders, then it is very likely that you have an encoding mismatch or the
		1575	other decoder is broken.
		1576
		1577	When decoding, C<JSON::XS> is strict by default and will likely catch all
		1578	errors. There are currently two settings that change this: C<relaxed>
		1579	makes C<JSON::XS> accept (but not generate) some non-standard extensions,
		1580	and C<allow_tags> will allow you to encode and decode Perl objects, at the
		1581	cost of not outputting valid JSON anymore.
		1582
		1583	=head2 TAGGED VALUE SYNTAX AND STANDARD JSON EN/DECODERS
		1584
		1585	When you use C<allow_tags> to use the extended (and also nonstandard and
		1586	invalid) JSON syntax for serialised objects, and you still want to decode
		1587	the generated When you want to serialise objects, you can run a regex
		1588	to replace the tagged syntax by standard JSON arrays (it only works for
		1589	"normal" packagesnames without comma, newlines or single colons). First,
		1590	the readable Perl version:
		1591
		1592	# if your FREEZE methods return no values, you need this replace first:
		1593	$json =~ s/$ \s* (" (?: [^\\":,]+\|\\.\|::)* ") \s* $ \s* \[\s*\]/[$1]/gx;
		1594
		1595	# this works for non-empty constructor arg lists:
		1596	$json =~ s/$ \s* (" (?: [^\\":,]+\|\\.\|::)* ") \s* $ \s* \[/[$1,/gx;
		1597
		1598	And here is a less readable version that is easy to adapt to other
		1599	languages:
		1600
		1601	$json =~ s/$\s("([^\\":,]+\|\\.\|::)")\s$\s\[/[$1,/g;
		1602
		1603	Here is an ECMAScript version (same regex):
		1604
		1605	json = json.replace (/$\s("([^\\":,]+\|\\.\|::)")\s$\s\[/g, "[$1,");
		1606
		1607	Since this syntax converts to standard JSON arrays, it might be hard to
		1608	distinguish serialised objects from normal arrays. You can prepend a
		1609	"magic number" as first array element to reduce chances of a collision:
		1610
		1611	$json =~ s/$\s("([^\\":,]+\|\\.\|::)")\s$\s\[/["XU1peReLzT4ggEllLanBYq4G9VzliwKF",$1,/g;
		1612
		1613	And after decoding the JSON text, you could walk the data
		1614	structure looking for arrays with a first element of
		1615	C<XU1peReLzT4ggEllLanBYq4G9VzliwKF>.
		1616
		1617	The same approach cna be used to create the tagged format with another
		1618	encoder. First, you create an array with the magic string as first member,
		1619	the classname as second, and constructor arguments last, encode it as part
		1620	of your JSON structure, and then:
		1621
		1622	$json =~ s/\[\s"XU1peReLzT4ggEllLanBYq4G9VzliwKF"\s,\s("([^\\":,]+\|\\.\|::)")\s*,/($1)[/g;
		1623
		1624	Again, this has some limitations - the magic string must not be encoded
		1625	with character escapes, and the constructor arguments must be non-empty.
		1626
		1627
		1628	=head1 RFC7158
		1629
		1630	Since this module was written, Google has written a new JSON RFC, RFC
		1631	7158. Unfortunately, this RFC breaks compatibility with both the original
		1632	JSON specification on www.json.org and RFC4627.
		1633
		1634	As far as I can see, you can get partial compatibility when parsing by
		1635	using C<< ->allow_nonref >>. However, consider thew security implications
		1636	of doing so.
		1637
		1638	I haven't decided yet whether to break compatibility with RFC4627 by
		1639	default (and potentially leave applications insecure), or change the
		1640	default to follow RFC7158.
		1641
		1642
1541	=head1 THREADS	1643	=head1 THREADS
1542		1644
1543	This module is I<not> guaranteed to be thread safe and there are no	1645	This module is I<not> guaranteed to be thread safe and there are no
1544	plans to change this until Perl gets thread support (as opposed to the	1646	plans to change this until Perl gets thread support (as opposed to the
1545	horribly slow so-called "threads" which are simply slow and bloated	1647	horribly slow so-called "threads" which are simply slow and bloated

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.145 by root, Tue Oct 29 00:06:40 2013 UTC vs. Revision 1.153 by root, Sun Mar 2 20:41:14 2014 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.145 by root, Tue Oct 29 00:06:40 2013 UTC vs.
Revision 1.153 by root, Sun Mar 2 20:41:14 2014 UTC