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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.165 by root, Tue Sep 5 13:07:09 2017 UTC vs.
Revision 1.169 by root, Thu Nov 15 20:49:12 2018 UTC

…		…
202	=over 4	202	=over 4
203		203
204	=item $json = new JSON::XS	204	=item $json = new JSON::XS
205		205
206	Creates a new JSON::XS object that can be used to de/encode JSON	206	Creates a new JSON::XS object that can be used to de/encode JSON
207	strings. All boolean flags described below are by default I<disabled>.	207	strings. All boolean flags described below are by default I<disabled>
		208	(with the exception of C<allow_nonref>, which defaults to I<enabled> since
		209	version C<4.0>).
208		210
209	The mutators for flags all return the JSON object again and thus calls can	211	The mutators for flags all return the JSON object again and thus calls can
210	be chained:	212	be chained:
211		213
212	my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]})	214	my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]})
…		…
365		367
366	=item $enabled = $json->get_relaxed	368	=item $enabled = $json->get_relaxed
367		369
368	If C<$enable> is true (or missing), then C<decode> will accept some	370	If C<$enable> is true (or missing), then C<decode> will accept some
369	extensions to normal JSON syntax (see below). C<encode> will not be	371	extensions to normal JSON syntax (see below). C<encode> will not be
370	affected in anyway. I<Be aware that this option makes you accept invalid	372	affected in any way. I<Be aware that this option makes you accept invalid
371	JSON texts as if they were valid!>. I suggest only to use this option to	373	JSON texts as if they were valid!>. I suggest only to use this option to
372	parse application-specific files written by humans (configuration files,	374	parse application-specific files written by humans (configuration files,
373	resource files etc.)	375	resource files etc.)
374		376
375	If C<$enable> is false (the default), then C<decode> will only accept	377	If C<$enable> is false (the default), then C<decode> will only accept
…		…
441		443
442	=item $json = $json->allow_nonref ([$enable])	444	=item $json = $json->allow_nonref ([$enable])
443		445
444	=item $enabled = $json->get_allow_nonref	446	=item $enabled = $json->get_allow_nonref
445		447
		448	Unlike other boolean options, this opotion is enabled by default beginning
		449	with version C<4.0>. See L<SECURITY CONSIDERATIONS> for the gory details.
		450
446	If C<$enable> is true (or missing), then the C<encode> method can convert a	451	If C<$enable> is true (or missing), then the C<encode> method can convert a
447	non-reference into its corresponding string, number or null JSON value,	452	non-reference into its corresponding string, number or null JSON value,
448	which is an extension to RFC4627. Likewise, C<decode> will accept those JSON	453	which is an extension to RFC4627. Likewise, C<decode> will accept those JSON
449	values instead of croaking.	454	values instead of croaking.
450		455
451	If C<$enable> is false, then the C<encode> method will croak if it isn't	456	If C<$enable> is false, then the C<encode> method will croak if it isn't
452	passed an arrayref or hashref, as JSON texts must either be an object	457	passed an arrayref or hashref, as JSON texts must either be an object
453	or array. Likewise, C<decode> will croak if given something that is not a	458	or array. Likewise, C<decode> will croak if given something that is not a
454	JSON object or array.	459	JSON object or array.
455		460
456	Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,	461	Example, encode a Perl scalar as JSON value without enabled C<allow_nonref>,
457	resulting in an invalid JSON text:	462	resulting in an error:
458		463
459	JSON::XS->new->allow_nonref->encode ("Hello, World!")	464	JSON::XS->new->allow_nonref (0)->encode ("Hello, World!")
460	=> "Hello, World!"	465	=> hash- or arrayref expected...
461		466
462	=item $json = $json->allow_unknown ([$enable])	467	=item $json = $json->allow_unknown ([$enable])
463		468
464	=item $enabled = $json->get_allow_unknown	469	=item $enabled = $json->get_allow_unknown
465		470
…		…
515		520
516	This setting has no effect on C<decode>.	521	This setting has no effect on C<decode>.
517		522
518	=item $json = $json->allow_tags ([$enable])	523	=item $json = $json->allow_tags ([$enable])
519		524
520	=item $enabled = $json->allow_tags	525	=item $enabled = $json->get_allow_tags
521		526
522	See L<OBJECT SERIALISATION> for details.	527	See L<OBJECT SERIALISATION> for details.
523		528
524	If C<$enable> is true (or missing), then C<encode>, upon encountering a	529	If C<$enable> is true (or missing), then C<encode>, upon encountering a
525	blessed object, will check for the availability of the C<FREEZE> method on	530	blessed object, will check for the availability of the C<FREEZE> method on
…		…
534	in C<decode>, as if tags were not part of the grammar.	539	in C<decode>, as if tags were not part of the grammar.
535		540
536	=item $json = $json->filter_json_object ([$coderef->($hashref)])	541	=item $json = $json->filter_json_object ([$coderef->($hashref)])
537		542
538	When C<$coderef> is specified, it will be called from C<decode> each	543	When C<$coderef> is specified, it will be called from C<decode> each
539	time it decodes a JSON object. The only argument is a reference to the	544	time it decodes a JSON object. The only argument is a reference to
540	newly-created hash. If the code references returns a single scalar (which	545	the newly-created hash. If the code reference returns a single scalar
541	need not be a reference), this value (i.e. a copy of that scalar to avoid	546	(which need not be a reference), this value (or rather a copy of it) is
542	aliasing) is inserted into the deserialised data structure. If it returns	547	inserted into the deserialised data structure. If it returns an empty
543	an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the	548	list (NOTE: I<not> C<undef>, which is a valid scalar), the original
544	original deserialised hash will be inserted. This setting can slow down	549	deserialised hash will be inserted. This setting can slow down decoding
545	decoding considerably.	550	considerably.
546		551
547	When C<$coderef> is omitted or undefined, any existing callback will	552	When C<$coderef> is omitted or undefined, any existing callback will
548	be removed and C<decode> will not change the deserialised hash in any	553	be removed and C<decode> will not change the deserialised hash in any
549	way.	554	way.
550		555
…		…
1567	are browser design bugs, but it is still you who will have to deal with	1572	are browser design bugs, but it is still you who will have to deal with
1568	it, as major browser developers care only for features, not about getting	1573	it, as major browser developers care only for features, not about getting
1569	security right).	1574	security right).
1570		1575
1571		1576
1572	=head1 "OLD" VS. "NEW" JSON (RFC 4627 VS. RFC 7159)	1577	=head2 "OLD" VS. "NEW" JSON (RFC 4627 VS. RFC 7159)
1573		1578
1574	TL;DR: Due to security concerns, JSON::XS will not allow scalar data in	1579	JSON originally required JSON texts to represent an array or object -
1575	JSON texts by default - you need to create your own JSON::XS object and	1580	scalar values were explicitly not allowed. This has changed, and versions
1576	enable C<allow_nonref>:	1581	of JSON::XS beginning with C<4.0> reflect this by allowing scalar values
		1582	by default.
1577		1583
		1584	One reason why one might not want this is that this removes a fundamental
		1585	property of JSON texts, namely that they are self-delimited and
		1586	self-contained, or in other words, you could take any number of "old"
		1587	JSON texts and paste them together, and the result would be unambiguously
		1588	parseable:
1578		1589
		1590	[1,3]{"k":5}[][null] # four JSON texts, without doubt
		1591
		1592	By allowing scalars, this property is lost: in the following example, is
		1593	this one JSON text (the number 12) or two JSON texts (the numbers 1 and
		1594	2):
		1595
		1596	12 # could be 12, or 1 and 2
		1597
		1598	Another lost property of "old" JSON is that no lookahead is required to
		1599	know the end of a JSON text, i.e. the JSON text definitely ended at the
		1600	last C<]> or C<}> character, there was no need to read extra characters.
		1601
		1602	For example, a viable network protocol with "old" JSON was to simply
		1603	exchange JSON texts without delimiter. For "new" JSON, you have to use a
		1604	suitable delimiter (such as a newline) after every JSON text or ensure you
		1605	never encode/decode scalar values.
		1606
		1607	Most protocols do work by only transferring arrays or objects, and the
		1608	easiest way to avoid problems with the "new" JSON definition is to
		1609	explicitly disallow scalar values in your encoder and decoder:
		1610
1579	my $json = JSON::XS->new->allow_nonref;	1611	$json_coder = JSON::XS->new->allow_nonref (0)
1580		1612
1581	$text = $json->encode ($data);	1613	This is a somewhat unhappy situation, and the blame can fully be put on
1582	$data = $json->decode ($text);	1614	JSON's inmventor, Douglas Crockford, who unilaterally changed the format
1583		1615	in 2006 without consulting the IETF, forcing the IETF to either fork the
1584	The long version: JSON being an important and supposedly stable format,	1616	format or go with it (as I was told, the IETF wasn't amused).
1585	the IETF standardised it as RFC 4627 in 2006. Unfortunately, the inventor
1586	of JSON, Dougles Crockford, unilaterally changed the definition of JSON in
1587	javascript. Rather than create a fork, the IETF decided to standardise the
1588	new syntax (apparently, so Iw as told, without finding it very amusing).
1589
1590	The biggest difference between thed original JSON and the new JSON is that
1591	the new JSON supports scalars (anything other than arrays and objects) at
1592	the toplevel of a JSON text. While this is strictly backwards compatible
1593	to older versions, it breaks a number of protocols that relied on sending
1594	JSON back-to-back, and is a minor security concern.
1595
1596	For example, imagine you have two banks communicating, and on one side,
1597	trhe JSON coder gets upgraded. Two messages, such as C<10> and C<1000>
1598	might then be confused to mean C<101000>, something that couldn't happen
1599	in the original JSON, because niether of these messages would be valid
1600	JSON.
1601
1602	If one side accepts these messages, then an upgrade in the coder on either
1603	side could result in this becoming exploitable.
1604
1605	This module has always allowed these messages as an optional extension, by
1606	default disabled. The security concerns are the reason why the default is
1607	still disabled, but future versions might/will likely upgrade to the newer
1608	RFC as default format, so you are advised to check your implementation
1609	and/or override the default with C<< ->allow_nonref (0) >> to ensure that
1610	future versions are safe.
1611		1617
1612		1618
1613	=head1 INTEROPERABILITY WITH OTHER MODULES	1619	=head1 INTEROPERABILITY WITH OTHER MODULES
1614		1620
1615	C<JSON::XS> uses the L<Types::Serialiser> module to provide boolean	1621	C<JSON::XS> uses the L<Types::Serialiser> module to provide boolean
…		…
1700		1706
1701	=head1 (I-)THREADS	1707	=head1 (I-)THREADS
1702		1708
1703	This module is I<not> guaranteed to be ithread (or MULTIPLICITY-) safe	1709	This module is I<not> guaranteed to be ithread (or MULTIPLICITY-) safe
1704	and there are no plans to change this. Note that perl's builtin so-called	1710	and there are no plans to change this. Note that perl's builtin so-called
1705	theeads/ithreads are officially deprecated and should not be used.	1711	threads/ithreads are officially deprecated and should not be used.
1706		1712
1707		1713
1708	=head1 THE PERILS OF SETLOCALE	1714	=head1 THE PERILS OF SETLOCALE
1709		1715
1710	Sometimes people avoid the Perl locale support and directly call the	1716	Sometimes people avoid the Perl locale support and directly call the

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.165 by root, Tue Sep 5 13:07:09 2017 UTC vs. Revision 1.169 by root, Thu Nov 15 20:49:12 2018 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.165 by root, Tue Sep 5 13:07:09 2017 UTC vs.
Revision 1.169 by root, Thu Nov 15 20:49:12 2018 UTC