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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.150 by root, Tue Oct 29 00:48:07 2013 UTC vs.
Revision 1.158 by root, Thu Sep 1 11:38:39 2016 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.02;
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;
…		…
402	character, after which more white-space and comments are allowed.	402	character, after which more white-space and comments are allowed.
403		403
404	[	404	[
405	1, # this comment not allowed in JSON	405	1, # this comment not allowed in JSON
406	# neither this one...	406	# neither this one...
		407	]
		408
		409	=item * literal ASCII TAB characters in strings
		410
		411	Literal ASCII TAB characters are now allowed in strings (and treated as
		412	C<\t>).
		413
		414	[
		415	"Hello\tWorld",
		416	"Hello<TAB>World", # literal <TAB> would not normally be allowed
407	]	417	]
408		418
409	=back	419	=back
410		420
411	=item $json = $json->canonical ([$enable])	421	=item $json = $json->canonical ([$enable])
…		…
687		697
688	This is useful if your JSON texts are not delimited by an outer protocol	698	This is useful if your JSON texts are not delimited by an outer protocol
689	and you need to know where the JSON text ends.	699	and you need to know where the JSON text ends.
690		700
691	JSON::XS->new->decode_prefix ("[1] the tail")	701	JSON::XS->new->decode_prefix ("[1] the tail")
692	=> ([], 3)	702	=> ([1], 3)
693		703
694	=back	704	=back
695		705
696		706
697	=head1 INCREMENTAL PARSING	707	=head1 INCREMENTAL PARSING
…		…
738	C<incr_skip> to skip the erroneous part). This is the most common way of	748	C<incr_skip> to skip the erroneous part). This is the most common way of
739	using the method.	749	using the method.
740		750
741	And finally, in list context, it will try to extract as many objects	751	And finally, in list context, it will try to extract as many objects
742	from the stream as it can find and return them, or the empty list	752	from the stream as it can find and return them, or the empty list
743	otherwise. For this to work, there must be no separators between the JSON	753	otherwise. For this to work, there must be no separators (other than
744	objects or arrays, instead they must be concatenated back-to-back. If	754	whitespace) between the JSON objects or arrays, instead they must be
745	an error occurs, an exception will be raised as in the scalar context	755	concatenated back-to-back. If an error occurs, an exception will be
746	case. Note that in this case, any previously-parsed JSON texts will be	756	raised as in the scalar context case. Note that in this case, any
747	lost.	757	previously-parsed JSON texts will be lost.
748		758
749	Example: Parse some JSON arrays/objects in a given string and return	759	Example: Parse some JSON arrays/objects in a given string and return
750	them.	760	them.
751		761
752	my @objs = JSON::XS->new->incr_parse ("[5][7][1,2]");	762	my @objs = JSON::XS->new->incr_parse ("[5][7][1,2]");
…		…
1553	are browser design bugs, but it is still you who will have to deal with	1563	are browser design bugs, but it is still you who will have to deal with
1554	it, as major browser developers care only for features, not about getting	1564	it, as major browser developers care only for features, not about getting
1555	security right).	1565	security right).
1556		1566
1557		1567
		1568	=head1 "OLD" VS. "NEW" JSON (RFC 4627 VS. RFC 7159)
		1569
		1570	TL;DR: Due to security concerns, JSON::XS will not allow scalar data in
		1571	JSON texts by default - you need to create your own JSON::XS object and
		1572	enable C<allow_nonref>:
		1573
		1574
		1575	my $json = JSON::XS->new->allow_nonref;
		1576
		1577	$text = $json->encode ($data);
		1578	$data = $json->decode ($text);
		1579
		1580	The long version: JSON being an important and supposedly stable format,
		1581	the IETF standardised it as RFC 4627 in 2006. Unfortunately, the inventor
		1582	of JSON, Dougles Crockford, unilaterally changed the definition of JSON in
		1583	javascript. Rather than create a fork, the IETF decided to standardise the
		1584	new syntax (apparently, so Iw as told, without finding it very amusing).
		1585
		1586	The biggest difference between thed original JSON and the new JSON is that
		1587	the new JSON supports scalars (anything other than arrays and objects) at
		1588	the toplevel of a JSON text. While this is strictly backwards compatible
		1589	to older versions, it breaks a number of protocols that relied on sending
		1590	JSON back-to-back, and is a minor security concern.
		1591
		1592	For example, imagine you have two banks communicating, and on one side,
		1593	trhe JSON coder gets upgraded. Two messages, such as C<10> and C<1000>
		1594	might then be confused to mean C<101000>, something that couldn't happen
		1595	in the original JSON, because niether of these messages would be valid
		1596	JSON.
		1597
		1598	If one side accepts these messages, then an upgrade in the coder on either
		1599	side could result in this becoming exploitable.
		1600
		1601	This module has always allowed these messages as an optional extension, by
		1602	default disabled. The security concerns are the reason why the default is
		1603	still disabled, but future versions might/will likely upgrade to the newer
		1604	RFC as default format, so you are advised to check your implementation
		1605	and/or override the default with C<< ->allow_nonref (0) >> to ensure that
		1606	future versions are safe.
		1607
		1608
1558	=head1 INTEROPERABILITY WITH OTHER MODULES	1609	=head1 INTEROPERABILITY WITH OTHER MODULES
1559		1610
1560	C<JSON::XS> uses the L<Types::Serialiser> module to provide boolean	1611	C<JSON::XS> uses the L<Types::Serialiser> module to provide boolean
1561	constants. That means that the JSON true and false values will be	1612	constants. That means that the JSON true and false values will be
1562	comaptible to true and false values of iother modules that do the same,	1613	comaptible to true and false values of iother modules that do the same,
1563	such as L<JSON::PP> and L<CBOR::XS>.	1614	such as L<JSON::PP> and L<CBOR::XS>.
		1615
		1616
		1617	=head1 INTEROPERABILITY WITH OTHER JSON DECODERS
		1618
		1619	As long as you only serialise data that can be directly expressed in JSON,
		1620	C<JSON::XS> is incapable of generating invalid JSON output (modulo bugs,
		1621	but C<JSON::XS> has found more bugs in the official JSON testsuite (1)
		1622	than the official JSON testsuite has found in C<JSON::XS> (0)).
		1623
		1624	When you have trouble decoding JSON generated by this module using other
		1625	decoders, then it is very likely that you have an encoding mismatch or the
		1626	other decoder is broken.
		1627
		1628	When decoding, C<JSON::XS> is strict by default and will likely catch all
		1629	errors. There are currently two settings that change this: C<relaxed>
		1630	makes C<JSON::XS> accept (but not generate) some non-standard extensions,
		1631	and C<allow_tags> will allow you to encode and decode Perl objects, at the
		1632	cost of not outputting valid JSON anymore.
		1633
		1634	=head2 TAGGED VALUE SYNTAX AND STANDARD JSON EN/DECODERS
		1635
		1636	When you use C<allow_tags> to use the extended (and also nonstandard and
		1637	invalid) JSON syntax for serialised objects, and you still want to decode
		1638	the generated When you want to serialise objects, you can run a regex
		1639	to replace the tagged syntax by standard JSON arrays (it only works for
		1640	"normal" packagesnames without comma, newlines or single colons). First,
		1641	the readable Perl version:
		1642
		1643	# if your FREEZE methods return no values, you need this replace first:
		1644	$json =~ s/$ \s* (" (?: [^\\":,]+\|\\.\|::)* ") \s* $ \s* \[\s*\]/[$1]/gx;
		1645
		1646	# this works for non-empty constructor arg lists:
		1647	$json =~ s/$ \s* (" (?: [^\\":,]+\|\\.\|::)* ") \s* $ \s* \[/[$1,/gx;
		1648
		1649	And here is a less readable version that is easy to adapt to other
		1650	languages:
		1651
		1652	$json =~ s/$\s("([^\\":,]+\|\\.\|::)")\s$\s\[/[$1,/g;
		1653
		1654	Here is an ECMAScript version (same regex):
		1655
		1656	json = json.replace (/$\s("([^\\":,]+\|\\.\|::)")\s$\s\[/g, "[$1,");
		1657
		1658	Since this syntax converts to standard JSON arrays, it might be hard to
		1659	distinguish serialised objects from normal arrays. You can prepend a
		1660	"magic number" as first array element to reduce chances of a collision:
		1661
		1662	$json =~ s/$\s("([^\\":,]+\|\\.\|::)")\s$\s\[/["XU1peReLzT4ggEllLanBYq4G9VzliwKF",$1,/g;
		1663
		1664	And after decoding the JSON text, you could walk the data
		1665	structure looking for arrays with a first element of
		1666	C<XU1peReLzT4ggEllLanBYq4G9VzliwKF>.
		1667
		1668	The same approach can be used to create the tagged format with another
		1669	encoder. First, you create an array with the magic string as first member,
		1670	the classname as second, and constructor arguments last, encode it as part
		1671	of your JSON structure, and then:
		1672
		1673	$json =~ s/\[\s"XU1peReLzT4ggEllLanBYq4G9VzliwKF"\s,\s("([^\\":,]+\|\\.\|::)")\s*,/($1)[/g;
		1674
		1675	Again, this has some limitations - the magic string must not be encoded
		1676	with character escapes, and the constructor arguments must be non-empty.
		1677
		1678
		1679	=head1 RFC7159
		1680
		1681	Since this module was written, Google has written a new JSON RFC, RFC 7159
		1682	(and RFC7158). Unfortunately, this RFC breaks compatibility with both the
		1683	original JSON specification on www.json.org and RFC4627.
		1684
		1685	As far as I can see, you can get partial compatibility when parsing by
		1686	using C<< ->allow_nonref >>. However, consider thew security implications
		1687	of doing so.
		1688
		1689	I haven't decided yet when to break compatibility with RFC4627 by default
		1690	(and potentially leave applications insecure) and change the default to
		1691	follow RFC7159, but application authors are well advised to call C<<
		1692	->allow_nonref(0) >> even if this is the current default, if they cannot
		1693	handle non-reference values, in preparation for the day when the4 default
		1694	will change.
1564		1695
1565		1696
1566	=head1 THREADS	1697	=head1 THREADS
1567		1698
1568	This module is I<not> guaranteed to be thread safe and there are no	1699	This module is I<not> guaranteed to be thread safe and there are no

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.150 by root, Tue Oct 29 00:48:07 2013 UTC vs. Revision 1.158 by root, Thu Sep 1 11:38:39 2016 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.150 by root, Tue Oct 29 00:48:07 2013 UTC vs.
Revision 1.158 by root, Thu Sep 1 11:38:39 2016 UTC