[ViewVC] Diff of: cvs/JSON-XS/README

Comparing JSON-XS/README (file contents):
Revision 1.24 by root, Thu Mar 27 06:37:35 2008 UTC vs.
Revision 1.43 by root, Thu Nov 15 23:07:55 2018 UTC

…		…
20	$perl_scalar = $coder->decode ($unicode_json_text);	20	$perl_scalar = $coder->decode ($unicode_json_text);
21		21
22	# Note that JSON version 2.0 and above will automatically use JSON::XS	22	# Note that JSON version 2.0 and above will automatically use JSON::XS
23	# if available, at virtually no speed overhead either, so you should	23	# if available, at virtually no speed overhead either, so you should
24	# be able to just:	24	# be able to just:
25		25
26	use JSON;	26	use JSON;
27		27
28	# and do the same things, except that you have a pure-perl fallback now.	28	# and do the same things, except that you have a pure-perl fallback now.
29		29
30	DESCRIPTION	30	DESCRIPTION
31	This module converts Perl data structures to JSON and vice versa. Its	31	This module converts Perl data structures to JSON and vice versa. Its
32	primary goal is to be correct and its secondary goal is to be fast.	32	primary goal is to be correct and its secondary goal is to be fast.
33	To reach the latter goal it was written in C.	33	To reach the latter goal it was written in C.
34		34
35	Beginning with version 2.0 of the JSON module, when both JSON and
36	JSON::XS are installed, then JSON will fall back on JSON::XS (this can
37	be overriden) with no overhead due to emulation (by inheritign
38	constructor and methods). If JSON::XS is not available, it will fall
39	back to the compatible JSON::PP module as backend, so using JSON instead
40	of JSON::XS gives you a portable JSON API that can be fast when you need
41	and doesn't require a C compiler when that is a problem.
42
43	As this is the n-th-something JSON module on CPAN, what was the reason
44	to write yet another JSON module? While it seems there are many JSON
45	modules, none of them correctly handle all corner cases, and in most
46	cases their maintainers are unresponsive, gone missing, or not listening
47	to bug reports for other reasons.
48
49	See COMPARISON, below, for a comparison to some other JSON modules.
50
51	See MAPPING, below, on how JSON::XS maps perl values to JSON values and	35	See MAPPING, below, on how JSON::XS maps perl values to JSON values and
52	vice versa.	36	vice versa.
53		37
54	FEATURES	38	FEATURES
55	* correct Unicode handling	39	* correct Unicode handling
…		…
57	This module knows how to handle Unicode, documents how and when it	41	This module knows how to handle Unicode, documents how and when it
58	does so, and even documents what "correct" means.	42	does so, and even documents what "correct" means.
59		43
60	* round-trip integrity	44	* round-trip integrity
61		45
62	When you serialise a perl data structure using only datatypes	46	When you serialise a perl data structure using only data types
63	supported by JSON, the deserialised data structure is identical on	47	supported by JSON and Perl, the deserialised data structure is
64	the Perl level. (e.g. the string "2.0" doesn't suddenly become "2"	48	identical on the Perl level. (e.g. the string "2.0" doesn't suddenly
65	just because it looks like a number). There minor are exceptions	49	become "2" just because it looks like a number). There are minor
66	to this, read the MAPPING section below to learn about those.	50	exceptions to this, read the MAPPING section below to learn about
		51	those.
67		52
68	* strict checking of JSON correctness	53	* strict checking of JSON correctness
69		54
70	There is no guessing, no generating of illegal JSON texts by	55	There is no guessing, no generating of illegal JSON texts by
71	default, and only JSON is accepted as input by default (the latter	56	default, and only JSON is accepted as input by default (the latter
…		…
78	too.	63	too.
79		64
80	* simple to use	65	* simple to use
81		66
82	This module has both a simple functional interface as well as an	67	This module has both a simple functional interface as well as an
83	objetc oriented interface interface.	68	object oriented interface.
84		69
85	* reasonably versatile output formats	70	* reasonably versatile output formats
86		71
87	You can choose between the most compact guaranteed-single-line	72	You can choose between the most compact guaranteed-single-line
88	format possible (nice for simple line-based protocols), a pure-ascii	73	format possible (nice for simple line-based protocols), a pure-ASCII
89	format (for when your transport is not 8-bit clean, still supports	74	format (for when your transport is not 8-bit clean, still supports
90	the whole Unicode range), or a pretty-printed format (for when you	75	the whole Unicode range), or a pretty-printed format (for when you
91	want to read that stuff). Or you can combine those features in	76	want to read that stuff). Or you can combine those features in
92	whatever way you like.	77	whatever way you like.
93		78
…		…
101		86
102	This function call is functionally identical to:	87	This function call is functionally identical to:
103		88
104	$json_text = JSON::XS->new->utf8->encode ($perl_scalar)	89	$json_text = JSON::XS->new->utf8->encode ($perl_scalar)
105		90
106	except being faster.	91	Except being faster.
107		92
108	$perl_scalar = decode_json $json_text	93	$perl_scalar = decode_json $json_text
109	The opposite of "encode_json": expects an UTF-8 (binary) string and	94	The opposite of "encode_json": expects a UTF-8 (binary) string and
110	tries to parse that as an UTF-8 encoded JSON text, returning the	95	tries to parse that as a UTF-8 encoded JSON text, returning the
111	resulting reference. Croaks on error.	96	resulting reference. Croaks on error.
112		97
113	This function call is functionally identical to:	98	This function call is functionally identical to:
114		99
115	$perl_scalar = JSON::XS->new->utf8->decode ($json_text)	100	$perl_scalar = JSON::XS->new->utf8->decode ($json_text)
116		101
117	except being faster.	102	Except being faster.
118
119	$is_boolean = JSON::XS::is_bool $scalar
120	Returns true if the passed scalar represents either JSON::XS::true
121	or JSON::XS::false, two constants that act like 1 and 0,
122	respectively and are used to represent JSON "true" and "false"
123	values in Perl.
124
125	See MAPPING, below, for more information on how JSON values are
126	mapped to Perl.
127		103
128	A FEW NOTES ON UNICODE AND PERL	104	A FEW NOTES ON UNICODE AND PERL
129	Since this often leads to confusion, here are a few very clear words on	105	Since this often leads to confusion, here are a few very clear words on
130	how Unicode works in Perl, modulo bugs.	106	how Unicode works in Perl, modulo bugs.
131		107
…		…
152		128
153	If you didn't know about that flag, just the better, pretend it	129	If you didn't know about that flag, just the better, pretend it
154	doesn't exist.	130	doesn't exist.
155		131
156	4. A "Unicode String" is simply a string where each character can be	132	4. A "Unicode String" is simply a string where each character can be
157	validly interpreted as a Unicode codepoint.	133	validly interpreted as a Unicode code point.
158	If you have UTF-8 encoded data, it is no longer a Unicode string,	134	If you have UTF-8 encoded data, it is no longer a Unicode string,
159	but a Unicode string encoded in UTF-8, giving you a binary string.	135	but a Unicode string encoded in UTF-8, giving you a binary string.
160		136
161	5. A string containing "high" (> 255) character values is not a UTF-8	137	5. A string containing "high" (> 255) character values is not a UTF-8
162	string.	138	string.
…		…
168	The object oriented interface lets you configure your own encoding or	144	The object oriented interface lets you configure your own encoding or
169	decoding style, within the limits of supported formats.	145	decoding style, within the limits of supported formats.
170		146
171	$json = new JSON::XS	147	$json = new JSON::XS
172	Creates a new JSON::XS object that can be used to de/encode JSON	148	Creates a new JSON::XS object that can be used to de/encode JSON
173	strings. All boolean flags described below are by default	149	strings. All boolean flags described below are by default disabled
174	disabled.	150	(with the exception of "allow_nonref", which defaults to enabled
		151	since version 4.0).
175		152
176	The mutators for flags all return the JSON object again and thus	153	The mutators for flags all return the JSON object again and thus
177	calls can be chained:	154	calls can be chained:
178		155
179	my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]})	156	my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]})
…		…
235		212
236	$json = $json->utf8 ([$enable])	213	$json = $json->utf8 ([$enable])
237	$enabled = $json->get_utf8	214	$enabled = $json->get_utf8
238	If $enable is true (or missing), then the "encode" method will	215	If $enable is true (or missing), then the "encode" method will
239	encode the JSON result into UTF-8, as required by many protocols,	216	encode the JSON result into UTF-8, as required by many protocols,
240	while the "decode" method expects to be handled an UTF-8-encoded	217	while the "decode" method expects to be handed a UTF-8-encoded
241	string. Please note that UTF-8-encoded strings do not contain any	218	string. Please note that UTF-8-encoded strings do not contain any
242	characters outside the range 0..255, they are thus useful for	219	characters outside the range 0..255, they are thus useful for
243	bytewise/binary I/O. In future versions, enabling this option might	220	bytewise/binary I/O. In future versions, enabling this option might
244	enable autodetection of the UTF-16 and UTF-32 encoding families, as	221	enable autodetection of the UTF-16 and UTF-32 encoding families, as
245	described in RFC4627.	222	described in RFC4627.
…		…
324		301
325	$json = $json->relaxed ([$enable])	302	$json = $json->relaxed ([$enable])
326	$enabled = $json->get_relaxed	303	$enabled = $json->get_relaxed
327	If $enable is true (or missing), then "decode" will accept some	304	If $enable is true (or missing), then "decode" will accept some
328	extensions to normal JSON syntax (see below). "encode" will not be	305	extensions to normal JSON syntax (see below). "encode" will not be
329	affected in anyway. *Be aware that this option makes you accept	306	affected in any way. *Be aware that this option makes you accept
330	invalid JSON texts as if they were valid!*. I suggest only to use	307	invalid JSON texts as if they were valid!*. I suggest only to use
331	this option to parse application-specific files written by humans	308	this option to parse application-specific files written by humans
332	(configuration files, resource files etc.)	309	(configuration files, resource files etc.)
333		310
334	If $enable is false (the default), then "decode" will only accept	311	If $enable is false (the default), then "decode" will only accept
…		…
362	[	339	[
363	1, # this comment not allowed in JSON	340	1, # this comment not allowed in JSON
364	# neither this one...	341	# neither this one...
365	]	342	]
366		343
		344	* literal ASCII TAB characters in strings
		345
		346	Literal ASCII TAB characters are now allowed in strings (and
		347	treated as "\t").
		348
		349	[
		350	"Hello\tWorld",
		351	"Hello<TAB>World", # literal <TAB> would not normally be allowed
		352	]
		353
367	$json = $json->canonical ([$enable])	354	$json = $json->canonical ([$enable])
368	$enabled = $json->get_canonical	355	$enabled = $json->get_canonical
369	If $enable is true (or missing), then the "encode" method will	356	If $enable is true (or missing), then the "encode" method will
370	output JSON objects by sorting their keys. This is adding a	357	output JSON objects by sorting their keys. This is adding a
371	comparatively high overhead.	358	comparatively high overhead.
372		359
373	If $enable is false, then the "encode" method will output key-value	360	If $enable is false, then the "encode" method will output key-value
374	pairs in the order Perl stores them (which will likely change	361	pairs in the order Perl stores them (which will likely change
375	between runs of the same script).	362	between runs of the same script, and can change even within the same
		363	run from 5.18 onwards).
376		364
377	This option is useful if you want the same data structure to be	365	This option is useful if you want the same data structure to be
378	encoded as the same JSON text (given the same overall settings). If	366	encoded as the same JSON text (given the same overall settings). If
379	it is disabled, the same hash might be encoded differently even if	367	it is disabled, the same hash might be encoded differently even if
380	contains the same data, as key-value pairs have no inherent ordering	368	contains the same data, as key-value pairs have no inherent ordering
381	in Perl.	369	in Perl.
382		370
383	This setting has no effect when decoding JSON texts.	371	This setting has no effect when decoding JSON texts.
384		372
		373	This setting has currently no effect on tied hashes.
		374
385	$json = $json->allow_nonref ([$enable])	375	$json = $json->allow_nonref ([$enable])
386	$enabled = $json->get_allow_nonref	376	$enabled = $json->get_allow_nonref
		377	Unlike other boolean options, this opotion is enabled by default
		378	beginning with version 4.0. See "SECURITY CONSIDERATIONS" for the
		379	gory details.
		380
387	If $enable is true (or missing), then the "encode" method can	381	If $enable is true (or missing), then the "encode" method can
388	convert a non-reference into its corresponding string, number or	382	convert a non-reference into its corresponding string, number or
389	null JSON value, which is an extension to RFC4627. Likewise,	383	null JSON value, which is an extension to RFC4627. Likewise,
390	"decode" will accept those JSON values instead of croaking.	384	"decode" will accept those JSON values instead of croaking.
391		385
392	If $enable is false, then the "encode" method will croak if it isn't	386	If $enable is false, then the "encode" method will croak if it isn't
393	passed an arrayref or hashref, as JSON texts must either be an	387	passed an arrayref or hashref, as JSON texts must either be an
394	object or array. Likewise, "decode" will croak if given something	388	object or array. Likewise, "decode" will croak if given something
395	that is not a JSON object or array.	389	that is not a JSON object or array.
396		390
397	Example, encode a Perl scalar as JSON value with enabled	391	Example, encode a Perl scalar as JSON value without enabled
398	"allow_nonref", resulting in an invalid JSON text:	392	"allow_nonref", resulting in an error:
399		393
400	JSON::XS->new->allow_nonref->encode ("Hello, World!")	394	JSON::XS->new->allow_nonref (0)->encode ("Hello, World!")
401	=> "Hello, World!"	395	=> hash- or arrayref expected...
		396
		397	$json = $json->allow_unknown ([$enable])
		398	$enabled = $json->get_allow_unknown
		399	If $enable is true (or missing), then "encode" will not throw an
		400	exception when it encounters values it cannot represent in JSON (for
		401	example, filehandles) but instead will encode a JSON "null" value.
		402	Note that blessed objects are not included here and are handled
		403	separately by c<allow_nonref>.
		404
		405	If $enable is false (the default), then "encode" will throw an
		406	exception when it encounters anything it cannot encode as JSON.
		407
		408	This option does not affect "decode" in any way, and it is
		409	recommended to leave it off unless you know your communications
		410	partner.
402		411
403	$json = $json->allow_blessed ([$enable])	412	$json = $json->allow_blessed ([$enable])
404	$enabled = $json->get_allow_blessed	413	$enabled = $json->get_allow_blessed
		414	See "OBJECT SERIALISATION" for details.
		415
405	If $enable is true (or missing), then the "encode" method will not	416	If $enable is true (or missing), then the "encode" method will not
406	barf when it encounters a blessed reference. Instead, the value of	417	barf when it encounters a blessed reference that it cannot convert
407	the convert_blessed option will decide whether "null"	418	otherwise. Instead, a JSON "null" value is encoded instead of the
408	("convert_blessed" disabled or no "TO_JSON" method found) or a	419	object.
409	representation of the object ("convert_blessed" enabled and
410	"TO_JSON" method found) is being encoded. Has no effect on "decode".
411		420
412	If $enable is false (the default), then "encode" will throw an	421	If $enable is false (the default), then "encode" will throw an
413	exception when it encounters a blessed object.	422	exception when it encounters a blessed object that it cannot convert
		423	otherwise.
		424
		425	This setting has no effect on "decode".
414		426
415	$json = $json->convert_blessed ([$enable])	427	$json = $json->convert_blessed ([$enable])
416	$enabled = $json->get_convert_blessed	428	$enabled = $json->get_convert_blessed
		429	See "OBJECT SERIALISATION" for details.
		430
417	If $enable is true (or missing), then "encode", upon encountering a	431	If $enable is true (or missing), then "encode", upon encountering a
418	blessed object, will check for the availability of the "TO_JSON"	432	blessed object, will check for the availability of the "TO_JSON"
419	method on the object's class. If found, it will be called in scalar	433	method on the object's class. If found, it will be called in scalar
420	context and the resulting scalar will be encoded instead of the	434	context and the resulting scalar will be encoded instead of the
421	object. If no "TO_JSON" method is found, the value of	435	object.
422	"allow_blessed" will decide what to do.
423		436
424	The "TO_JSON" method may safely call die if it wants. If "TO_JSON"	437	The "TO_JSON" method may safely call die if it wants. If "TO_JSON"
425	returns other blessed objects, those will be handled in the same	438	returns other blessed objects, those will be handled in the same
426	way. "TO_JSON" must take care of not causing an endless recursion	439	way. "TO_JSON" must take care of not causing an endless recursion
427	cycle (== crash) in this case. The name of "TO_JSON" was chosen	440	cycle (== crash) in this case. The name of "TO_JSON" was chosen
428	because other methods called by the Perl core (== not by the user of	441	because other methods called by the Perl core (== not by the user of
429	the object) are usually in upper case letters and to avoid	442	the object) are usually in upper case letters and to avoid
430	collisions with any "to_json" function or method.	443	collisions with any "to_json" function or method.
431		444
432	This setting does not yet influence "decode" in any way, but in the	445	If $enable is false (the default), then "encode" will not consider
433	future, global hooks might get installed that influence "decode" and	446	this type of conversion.
434	are enabled by this setting.
435		447
436	If $enable is false, then the "allow_blessed" setting will decide	448	This setting has no effect on "decode".
437	what to do when a blessed object is found.	449
		450	$json = $json->allow_tags ([$enable])
		451	$enabled = $json->get_allow_tags
		452	See "OBJECT SERIALISATION" for details.
		453
		454	If $enable is true (or missing), then "encode", upon encountering a
		455	blessed object, will check for the availability of the "FREEZE"
		456	method on the object's class. If found, it will be used to serialise
		457	the object into a nonstandard tagged JSON value (that JSON decoders
		458	cannot decode).
		459
		460	It also causes "decode" to parse such tagged JSON values and
		461	deserialise them via a call to the "THAW" method.
		462
		463	If $enable is false (the default), then "encode" will not consider
		464	this type of conversion, and tagged JSON values will cause a parse
		465	error in "decode", as if tags were not part of the grammar.
		466
		467	$json->boolean_values ([$false, $true])
		468	($false, $true) = $json->get_boolean_values
		469	By default, JSON booleans will be decoded as overloaded
		470	$Types::Serialiser::false and $Types::Serialiser::true objects.
		471
		472	With this method you can specify your own boolean values for
		473	decoding - on decode, JSON "false" will be decoded as a copy of
		474	$false, and JSON "true" will be decoded as $true ("copy" here is the
		475	same thing as assigning a value to another variable, i.e. "$copy =
		476	$false").
		477
		478	Calling this method without any arguments will reset the booleans to
		479	their default values.
		480
		481	"get_boolean_values" will return both $false and $true values, or
		482	the empty list when they are set to the default.
438		483
439	$json = $json->filter_json_object ([$coderef->($hashref)])	484	$json = $json->filter_json_object ([$coderef->($hashref)])
440	When $coderef is specified, it will be called from "decode" each	485	When $coderef is specified, it will be called from "decode" each
441	time it decodes a JSON object. The only argument is a reference to	486	time it decodes a JSON object. The only argument is a reference to
442	the newly-created hash. If the code references returns a single	487	the newly-created hash. If the code reference returns a single
443	scalar (which need not be a reference), this value (i.e. a copy of	488	scalar (which need not be a reference), this value (or rather a copy
444	that scalar to avoid aliasing) is inserted into the deserialised	489	of it) is inserted into the deserialised data structure. If it
445	data structure. If it returns an empty list (NOTE: not "undef",	490	returns an empty list (NOTE: not "undef", which is a valid
446	which is a valid scalar), the original deserialised hash will be	491	scalar), the original deserialised hash will be inserted. This
447	inserted. This setting can slow down decoding considerably.	492	setting can slow down decoding considerably.
448		493
449	When $coderef is omitted or undefined, any existing callback will be	494	When $coderef is omitted or undefined, any existing callback will be
450	removed and "decode" will not change the deserialised hash in any	495	removed and "decode" will not change the deserialised hash in any
451	way.	496	way.
452		497
…		…
541	saving space.	586	saving space.
542		587
543	$json = $json->max_depth ([$maximum_nesting_depth])	588	$json = $json->max_depth ([$maximum_nesting_depth])
544	$max_depth = $json->get_max_depth	589	$max_depth = $json->get_max_depth
545	Sets the maximum nesting level (default 512) accepted while encoding	590	Sets the maximum nesting level (default 512) accepted while encoding
546	or decoding. If the JSON text or Perl data structure has an equal or	591	or decoding. If a higher nesting level is detected in JSON text or a
547	higher nesting level then this limit, then the encoder and decoder	592	Perl data structure, then the encoder and decoder will stop and
548	will stop and croak at that point.	593	croak at that point.
549		594
550	Nesting level is defined by number of hash- or arrayrefs that the	595	Nesting level is defined by number of hash- or arrayrefs that the
551	encoder needs to traverse to reach a given point or the number of	596	encoder needs to traverse to reach a given point or the number of
552	"{" or "[" characters without their matching closing parenthesis	597	"{" or "[" characters without their matching closing parenthesis
553	crossed to reach a given character in a string.	598	crossed to reach a given character in a string.
554		599
555	Setting the maximum depth to one disallows any nesting, so that	600	Setting the maximum depth to one disallows any nesting, so that
556	ensures that the object is only a single hash/object or array.	601	ensures that the object is only a single hash/object or array.
557		602
558	The argument to "max_depth" will be rounded up to the next highest
559	power of two. If no argument is given, the highest possible setting	603	If no argument is given, the highest possible setting will be used,
560	will be used, which is rarely useful.	604	which is rarely useful.
		605
		606	Note that nesting is implemented by recursion in C. The default
		607	value has been chosen to be as large as typical operating systems
		608	allow without crashing.
561		609
562	See SECURITY CONSIDERATIONS, below, for more info on why this is	610	See SECURITY CONSIDERATIONS, below, for more info on why this is
563	useful.	611	useful.
564		612
565	$json = $json->max_size ([$maximum_string_size])	613	$json = $json->max_size ([$maximum_string_size])
566	$max_size = $json->get_max_size	614	$max_size = $json->get_max_size
567	Set the maximum length a JSON text may have (in bytes) where	615	Set the maximum length a JSON text may have (in bytes) where
568	decoding is being attempted. The default is 0, meaning no limit.	616	decoding is being attempted. The default is 0, meaning no limit.
569	When "decode" is called on a string longer then this number of	617	When "decode" is called on a string that is longer then this many
570	characters it will not attempt to decode the string but throw an	618	bytes, it will not attempt to decode the string but throw an
571	exception. This setting has no effect on "encode" (yet).	619	exception. This setting has no effect on "encode" (yet).
572		620
573	The argument to "max_size" will be rounded up to the next highest
574	power of two (so may be more than requested). If no argument is
575	given, the limit check will be deactivated (same as when 0 is	621	If no argument is given, the limit check will be deactivated (same
576	specified).	622	as when 0 is specified).
577		623
578	See SECURITY CONSIDERATIONS, below, for more info on why this is	624	See SECURITY CONSIDERATIONS, below, for more info on why this is
579	useful.	625	useful.
580		626
581	$json_text = $json->encode ($perl_scalar)	627	$json_text = $json->encode ($perl_scalar)
582	Converts the given Perl data structure (a simple scalar or a	628	Converts the given Perl value or data structure to its JSON
583	reference to a hash or array) to its JSON representation. Simple	629	representation. Croaks on error.
584	scalars will be converted into JSON string or number sequences,
585	while references to arrays become JSON arrays and references to
586	hashes become JSON objects. Undefined Perl values (e.g. "undef")
587	become JSON "null" values. Neither "true" nor "false" values will be
588	generated.
589		630
590	$perl_scalar = $json->decode ($json_text)	631	$perl_scalar = $json->decode ($json_text)
591	The opposite of "encode": expects a JSON text and tries to parse it,	632	The opposite of "encode": expects a JSON text and tries to parse it,
592	returning the resulting simple scalar or reference. Croaks on error.	633	returning the resulting simple scalar or reference. Croaks on error.
593
594	JSON numbers and strings become simple Perl scalars. JSON arrays
595	become Perl arrayrefs and JSON objects become Perl hashrefs. "true"
596	becomes 1, "false" becomes 0 and "null" becomes "undef".
597		634
598	($perl_scalar, $characters) = $json->decode_prefix ($json_text)	635	($perl_scalar, $characters) = $json->decode_prefix ($json_text)
599	This works like the "decode" method, but instead of raising an	636	This works like the "decode" method, but instead of raising an
600	exception when there is trailing garbage after the first JSON	637	exception when there is trailing garbage after the first JSON
601	object, it will silently stop parsing there and return the number of	638	object, it will silently stop parsing there and return the number of
602	characters consumed so far.	639	characters consumed so far.
603		640
604	This is useful if your JSON texts are not delimited by an outer	641	This is useful if your JSON texts are not delimited by an outer
605	protocol (which is not the brightest thing to do in the first place)
606	and you need to know where the JSON text ends.	642	protocol and you need to know where the JSON text ends.
607		643
608	JSON::XS->new->decode_prefix ("[1] the tail")	644	JSON::XS->new->decode_prefix ("[1] the tail")
609	=> ([], 3)	645	=> ([1], 3)
610		646
611	INCREMENTAL PARSING	647	INCREMENTAL PARSING
612	[This section and the API it details is still EXPERIMENTAL]
613
614	In some cases, there is the need for incremental parsing of JSON texts.	648	In some cases, there is the need for incremental parsing of JSON texts.
615	While this module always has to keep both JSON text and resulting Perl	649	While this module always has to keep both JSON text and resulting Perl
616	data structure in memory at one time, it does allow you to parse a JSON	650	data structure in memory at one time, it does allow you to parse a JSON
617	stream incrementally. It does so by accumulating text until it has a	651	stream incrementally. It does so by accumulating text until it has a
618	full JSON object, which it then can decode. This process is similar to	652	full JSON object, which it then can decode. This process is similar to
619	using "decode_prefix" to see if a full JSON object is available, but is	653	using "decode_prefix" to see if a full JSON object is available, but is
620	much more efficient (JSON::XS will only attempt to parse the JSON text	654	much more efficient (and can be implemented with a minimum of method
621	once it is sure it has enough text to get a decisive result, using a	655	calls).
622	very simple but truly incremental parser).
623		656
624	The following two methods deal with this.	657	JSON::XS will only attempt to parse the JSON text once it is sure it has
		658	enough text to get a decisive result, using a very simple but truly
		659	incremental parser. This means that it sometimes won't stop as early as
		660	the full parser, for example, it doesn't detect mismatched parentheses.
		661	The only thing it guarantees is that it starts decoding as soon as a
		662	syntactically valid JSON text has been seen. This means you need to set
		663	resource limits (e.g. "max_size") to ensure the parser will stop parsing
		664	in the presence if syntax errors.
		665
		666	The following methods implement this incremental parser.
625		667
626	[void, scalar or list context] = $json->incr_parse ([$string])	668	[void, scalar or list context] = $json->incr_parse ([$string])
627	This is the central parsing function. It can both append new text	669	This is the central parsing function. It can both append new text
628	and extract objects from the stream accumulated so far (both of	670	and extract objects from the stream accumulated so far (both of
629	these functions are optional).	671	these functions are optional).
…		…
637		679
638	If the method is called in scalar context, then it will try to	680	If the method is called in scalar context, then it will try to
639	extract exactly one JSON object. If that is successful, it will	681	extract exactly one JSON object. If that is successful, it will
640	return this object, otherwise it will return "undef". If there is a	682	return this object, otherwise it will return "undef". If there is a
641	parse error, this method will croak just as "decode" would do (one	683	parse error, this method will croak just as "decode" would do (one
642	can then use "incr_skip" to skip the errornous part). This is the	684	can then use "incr_skip" to skip the erroneous part). This is the
643	most common way of using the method.	685	most common way of using the method.
644		686
645	And finally, in list context, it will try to extract as many objects	687	And finally, in list context, it will try to extract as many objects
646	from the stream as it can find and return them, or the empty list	688	from the stream as it can find and return them, or the empty list
647	otherwise. For this to work, there must be no separators between the	689	otherwise. For this to work, there must be no separators (other than
648	JSON objects or arrays, instead they must be concatenated	690	whitespace) between the JSON objects or arrays, instead they must be
649	back-to-back. If an error occurs, an exception will be raised as in	691	concatenated back-to-back. If an error occurs, an exception will be
650	the scalar context case. Note that in this case, any	692	raised as in the scalar context case. Note that in this case, any
651	previously-parsed JSON texts will be lost.	693	previously-parsed JSON texts will be lost.
		694
		695	Example: Parse some JSON arrays/objects in a given string and return
		696	them.
		697
		698	my @objs = JSON::XS->new->incr_parse ("[5][7][1,2]");
652		699
653	$lvalue_string = $json->incr_text	700	$lvalue_string = $json->incr_text
654	This method returns the currently stored JSON fragment as an lvalue,	701	This method returns the currently stored JSON fragment as an lvalue,
655	that is, you can manipulate it. This only works when a preceding	702	that is, you can manipulate it. This only works when a preceding
656	call to "incr_parse" in scalar context successfully returned an	703	call to "incr_parse" in scalar context successfully returned an
…		…
658	function (I mean it. although in simple tests it might actually	705	function (I mean it. although in simple tests it might actually
659	work, it will fail under real world conditions). As a special	706	work, it will fail under real world conditions). As a special
660	exception, you can also call this method before having parsed	707	exception, you can also call this method before having parsed
661	anything.	708	anything.
662		709
		710	That means you can only use this function to look at or manipulate
		711	text before or after complete JSON objects, not while the parser is
		712	in the middle of parsing a JSON object.
		713
663	This function is useful in two cases: a) finding the trailing text	714	This function is useful in two cases: a) finding the trailing text
664	after a JSON object or b) parsing multiple JSON objects separated by	715	after a JSON object or b) parsing multiple JSON objects separated by
665	non-JSON text (such as commas).	716	non-JSON text (such as commas).
666		717
667	$json->incr_skip	718	$json->incr_skip
668	This will reset the state of the incremental parser and will remove	719	This will reset the state of the incremental parser and will remove
669	the parsed text from the input buffer. This is useful after	720	the parsed text from the input buffer so far. This is useful after
670	"incr_parse" died, in which case the input buffer and incremental	721	"incr_parse" died, in which case the input buffer and incremental
671	parser state is left unchanged, to skip the text parsed so far and	722	parser state is left unchanged, to skip the text parsed so far and
672	to reset the parse state.	723	to reset the parse state.
673		724
		725	The difference to "incr_reset" is that only text until the parse
		726	error occurred is removed.
		727
		728	$json->incr_reset
		729	This completely resets the incremental parser, that is, after this
		730	call, it will be as if the parser had never parsed anything.
		731
		732	This is useful if you want to repeatedly parse JSON objects and want
		733	to ignore any trailing data, which means you have to reset the
		734	parser after each successful decode.
		735
674	LIMITATIONS	736	LIMITATIONS
675	All options that affect decoding are supported, except "allow_nonref".	737	The incremental parser is a non-exact parser: it works by gathering as
676	The reason for this is that it cannot be made to work sensibly: JSON	738	much text as possible that could be a valid JSON text, followed by
677	objects and arrays are self-delimited, i.e. you can concatenate them	739	trying to decode it.
678	back to back and still decode them perfectly. This does not hold true
679	for JSON numbers, however.
680		740
681	For example, is the string 1 a single JSON number, or is it simply the	741	That means it sometimes needs to read more data than strictly necessary
682	start of 12? Or is 12 a single JSON number, or the concatenation of 1	742	to diagnose an invalid JSON text. For example, after parsing the
683	and 2? In neither case you can tell, and this is why JSON::XS takes the	743	following fragment, the parser could stop with an error, as this
684	conservative route and disallows this case.	744	fragment cannot be the beginning of a valid JSON text:
		745
		746	[,
		747
		748	In reality, hopwever, the parser might continue to read data until a
		749	length limit is exceeded or it finds a closing bracket.
685		750
686	EXAMPLES	751	EXAMPLES
687	Some examples will make all this clearer. First, a simple example that	752	Some examples will make all this clearer. First, a simple example that
688	works similarly to "decode_prefix": We want to decode the JSON object at	753	works similarly to "decode_prefix": We want to decode the JSON object at
689	the start of a string and identify the portion after the JSON object:	754	the start of a string and identify the portion after the JSON object:
…		…
853	If the number consists of digits only, JSON::XS will try to	918	If the number consists of digits only, JSON::XS will try to
854	represent it as an integer value. If that fails, it will try to	919	represent it as an integer value. If that fails, it will try to
855	represent it as a numeric (floating point) value if that is possible	920	represent it as a numeric (floating point) value if that is possible
856	without loss of precision. Otherwise it will preserve the number as	921	without loss of precision. Otherwise it will preserve the number as
857	a string value (in which case you lose roundtripping ability, as the	922	a string value (in which case you lose roundtripping ability, as the
858	JSON number will be re-encoded toa JSON string).	923	JSON number will be re-encoded to a JSON string).
859		924
860	Numbers containing a fractional or exponential part will always be	925	Numbers containing a fractional or exponential part will always be
861	represented as numeric (floating point) values, possibly at a loss	926	represented as numeric (floating point) values, possibly at a loss
862	of precision (in which case you might lose perfect roundtripping	927	of precision (in which case you might lose perfect roundtripping
863	ability, but the JSON number will still be re-encoded as a JSON	928	ability, but the JSON number will still be re-encoded as a JSON
864	number).	929	number).
865		930
		931	Note that precision is not accuracy - binary floating point values
		932	cannot represent most decimal fractions exactly, and when converting
		933	from and to floating point, JSON::XS only guarantees precision up to
		934	but not including the least significant bit.
		935
866	true, false	936	true, false
867	These JSON atoms become "JSON::XS::true" and "JSON::XS::false",	937	These JSON atoms become "Types::Serialiser::true" and
868	respectively. They are overloaded to act almost exactly like the	938	"Types::Serialiser::false", respectively. They are overloaded to act
869	numbers 1 and 0. You can check whether a scalar is a JSON boolean by	939	almost exactly like the numbers 1 and 0. You can check whether a
870	using the "JSON::XS::is_bool" function.	940	scalar is a JSON boolean by using the "Types::Serialiser::is_bool"
		941	function (after "use Types::Serialier", of course).
871		942
872	null	943	null
873	A JSON null atom becomes "undef" in Perl.	944	A JSON null atom becomes "undef" in Perl.
		945
		946	shell-style comments ("# text")
		947	As a nonstandard extension to the JSON syntax that is enabled by the
		948	"relaxed" setting, shell-style comments are allowed. They can start
		949	anywhere outside strings and go till the end of the line.
		950
		951	tagged values ("(tag)value").
		952	Another nonstandard extension to the JSON syntax, enabled with the
		953	"allow_tags" setting, are tagged values. In this implementation, the
		954	tag must be a perl package/class name encoded as a JSON string,
		955	and the value must be a JSON array encoding optional constructor
		956	arguments.
		957
		958	See "OBJECT SERIALISATION", below, for details.
874		959
875	PERL -> JSON	960	PERL -> JSON
876	The mapping from Perl to JSON is slightly more difficult, as Perl is a	961	The mapping from Perl to JSON is slightly more difficult, as Perl is a
877	truly typeless language, so we can only guess which JSON type is meant	962	truly typeless language, so we can only guess which JSON type is meant
878	by a Perl value.	963	by a Perl value.
879		964
880	hash references	965	hash references
881	Perl hash references become JSON objects. As there is no inherent	966	Perl hash references become JSON objects. As there is no inherent
882	ordering in hash keys (or JSON objects), they will usually be	967	ordering in hash keys (or JSON objects), they will usually be
883	encoded in a pseudo-random order that can change between runs of the	968	encoded in a pseudo-random order. JSON::XS can optionally sort the
884	same program but stays generally the same within a single run of a	969	hash keys (determined by the canonical flag), so the same
885	program. JSON::XS can optionally sort the hash keys (determined by	970	datastructure will serialise to the same JSON text (given same
886	the canonical flag), so the same datastructure will serialise to	971	settings and version of JSON::XS), but this incurs a runtime
887	the same JSON text (given same settings and version of JSON::XS),	972	overhead and is only rarely useful, e.g. when you want to compare
888	but this incurs a runtime overhead and is only rarely useful, e.g.	973	some JSON text against another for equality.
889	when you want to compare some JSON text against another for
890	equality.
891		974
892	array references	975	array references
893	Perl array references become JSON arrays.	976	Perl array references become JSON arrays.
894		977
895	other references	978	other references
896	Other unblessed references are generally not allowed and will cause	979	Other unblessed references are generally not allowed and will cause
897	an exception to be thrown, except for references to the integers 0	980	an exception to be thrown, except for references to the integers 0
898	and 1, which get turned into "false" and "true" atoms in JSON. You	981	and 1, which get turned into "false" and "true" atoms in JSON.
899	can also use "JSON::XS::false" and "JSON::XS::true" to improve	982
		983	Since "JSON::XS" uses the boolean model from Types::Serialiser, you
		984	can also "use Types::Serialiser" and then use
		985	"Types::Serialiser::false" and "Types::Serialiser::true" to improve
900	readability.	986	readability.
901		987
		988	use Types::Serialiser;
902	encode_json [\0,JSON::XS::true] # yields [false,true]	989	encode_json [\0, Types::Serialiser::true] # yields [false,true]
903		990
904	JSON::XS::true, JSON::XS::false	991	Types::Serialiser::true, Types::Serialiser::false
905	These special values become JSON true and JSON false values,	992	These special values from the Types::Serialiser module become JSON
906	respectively. You can also use "\1" and "\0" directly if you want.	993	true and JSON false values, respectively. You can also use "\1" and
		994	"\0" directly if you want.
907		995
908	blessed objects	996	blessed objects
909	Blessed objects are not directly representable in JSON. See the	997	Blessed objects are not directly representable in JSON, but
910	"allow_blessed" and "convert_blessed" methods on various options on	998	"JSON::XS" allows various ways of handling objects. See "OBJECT
911	how to deal with this: basically, you can choose between throwing an	999	SERIALISATION", below, for details.
912	exception, encoding the reference as if it weren't blessed, or
913	provide your own serialiser method.
914		1000
915	simple scalars	1001	simple scalars
916	Simple Perl scalars (any scalar that is not a reference) are the	1002	Simple Perl scalars (any scalar that is not a reference) are the
917	most difficult objects to encode: JSON::XS will encode undefined	1003	most difficult objects to encode: JSON::XS will encode undefined
918	scalars as JSON "null" values, scalars that have last been used in a	1004	scalars as JSON "null" values, scalars that have last been used in a
…		…
946		1032
947	You can not currently force the type in other, less obscure, ways.	1033	You can not currently force the type in other, less obscure, ways.
948	Tell me if you need this capability (but don't forget to explain why	1034	Tell me if you need this capability (but don't forget to explain why
949	it's needed :).	1035	it's needed :).
950		1036
		1037	Note that numerical precision has the same meaning as under Perl (so
		1038	binary to decimal conversion follows the same rules as in Perl,
		1039	which can differ to other languages). Also, your perl interpreter
		1040	might expose extensions to the floating point numbers of your
		1041	platform, such as infinities or NaN's - these cannot be represented
		1042	in JSON, and it is an error to pass those in.
		1043
		1044	OBJECT SERIALISATION
		1045	As JSON cannot directly represent Perl objects, you have to choose
		1046	between a pure JSON representation (without the ability to deserialise
		1047	the object automatically again), and a nonstandard extension to the JSON
		1048	syntax, tagged values.
		1049
		1050	SERIALISATION
		1051	What happens when "JSON::XS" encounters a Perl object depends on the
		1052	"allow_blessed", "convert_blessed" and "allow_tags" settings, which are
		1053	used in this order:
		1054
		1055	1. "allow_tags" is enabled and the object has a "FREEZE" method.
		1056	In this case, "JSON::XS" uses the Types::Serialiser object
		1057	serialisation protocol to create a tagged JSON value, using a
		1058	nonstandard extension to the JSON syntax.
		1059
		1060	This works by invoking the "FREEZE" method on the object, with the
		1061	first argument being the object to serialise, and the second
		1062	argument being the constant string "JSON" to distinguish it from
		1063	other serialisers.
		1064
		1065	The "FREEZE" method can return any number of values (i.e. zero or
		1066	more). These values and the paclkage/classname of the object will
		1067	then be encoded as a tagged JSON value in the following format:
		1068
		1069	("classname")[FREEZE return values...]
		1070
		1071	e.g.:
		1072
		1073	("URI")["http://www.google.com/"]
		1074	("MyDate")[2013,10,29]
		1075	("ImageData::JPEG")["Z3...VlCg=="]
		1076
		1077	For example, the hypothetical "My::Object" "FREEZE" method might use
		1078	the objects "type" and "id" members to encode the object:
		1079
		1080	sub My::Object::FREEZE {
		1081	my ($self, $serialiser) = @_;
		1082
		1083	($self->{type}, $self->{id})
		1084	}
		1085
		1086	2. "convert_blessed" is enabled and the object has a "TO_JSON" method.
		1087	In this case, the "TO_JSON" method of the object is invoked in
		1088	scalar context. It must return a single scalar that can be directly
		1089	encoded into JSON. This scalar replaces the object in the JSON text.
		1090
		1091	For example, the following "TO_JSON" method will convert all URI
		1092	objects to JSON strings when serialised. The fatc that these values
		1093	originally were URI objects is lost.
		1094
		1095	sub URI::TO_JSON {
		1096	my ($uri) = @_;
		1097	$uri->as_string
		1098	}
		1099
		1100	3. "allow_blessed" is enabled.
		1101	The object will be serialised as a JSON null value.
		1102
		1103	4. none of the above
		1104	If none of the settings are enabled or the respective methods are
		1105	missing, "JSON::XS" throws an exception.
		1106
		1107	DESERIALISATION
		1108	For deserialisation there are only two cases to consider: either
		1109	nonstandard tagging was used, in which case "allow_tags" decides, or
		1110	objects cannot be automatically be deserialised, in which case you can
		1111	use postprocessing or the "filter_json_object" or
		1112	"filter_json_single_key_object" callbacks to get some real objects our
		1113	of your JSON.
		1114
		1115	This section only considers the tagged value case: I a tagged JSON
		1116	object is encountered during decoding and "allow_tags" is disabled, a
		1117	parse error will result (as if tagged values were not part of the
		1118	grammar).
		1119
		1120	If "allow_tags" is enabled, "JSON::XS" will look up the "THAW" method of
		1121	the package/classname used during serialisation (it will not attempt to
		1122	load the package as a Perl module). If there is no such method, the
		1123	decoding will fail with an error.
		1124
		1125	Otherwise, the "THAW" method is invoked with the classname as first
		1126	argument, the constant string "JSON" as second argument, and all the
		1127	values from the JSON array (the values originally returned by the
		1128	"FREEZE" method) as remaining arguments.
		1129
		1130	The method must then return the object. While technically you can return
		1131	any Perl scalar, you might have to enable the "enable_nonref" setting to
		1132	make that work in all cases, so better return an actual blessed
		1133	reference.
		1134
		1135	As an example, let's implement a "THAW" function that regenerates the
		1136	"My::Object" from the "FREEZE" example earlier:
		1137
		1138	sub My::Object::THAW {
		1139	my ($class, $serialiser, $type, $id) = @_;
		1140
		1141	$class->new (type => $type, id => $id)
		1142	}
		1143
951	ENCODING/CODESET FLAG NOTES	1144	ENCODING/CODESET FLAG NOTES
952	The interested reader might have seen a number of flags that signify	1145	The interested reader might have seen a number of flags that signify
953	encodings or codesets - "utf8", "latin1" and "ascii". There seems to be	1146	encodings or codesets - "utf8", "latin1" and "ascii". There seems to be
954	some confusion on what these do, so here is a short comparison:	1147	some confusion on what these do, so here is a short comparison:
955		1148
…		…
974		1167
975	"utf8" flag disabled	1168	"utf8" flag disabled
976	When "utf8" is disabled (the default), then "encode"/"decode"	1169	When "utf8" is disabled (the default), then "encode"/"decode"
977	generate and expect Unicode strings, that is, characters with high	1170	generate and expect Unicode strings, that is, characters with high
978	ordinal Unicode values (> 255) will be encoded as such characters,	1171	ordinal Unicode values (> 255) will be encoded as such characters,
979	and likewise such characters are decoded as-is, no canges to them	1172	and likewise such characters are decoded as-is, no changes to them
980	will be done, except "(re-)interpreting" them as Unicode codepoints	1173	will be done, except "(re-)interpreting" them as Unicode codepoints
981	or Unicode characters, respectively (to Perl, these are the same	1174	or Unicode characters, respectively (to Perl, these are the same
982	thing in strings unless you do funny/weird/dumb stuff).	1175	thing in strings unless you do funny/weird/dumb stuff).
983		1176
984	This is useful when you want to do the encoding yourself (e.g. when	1177	This is useful when you want to do the encoding yourself (e.g. when
…		…
994	will expect your input strings to be encoded as UTF-8, that is, no	1187	will expect your input strings to be encoded as UTF-8, that is, no
995	"character" of the input string must have any value > 255, as UTF-8	1188	"character" of the input string must have any value > 255, as UTF-8
996	does not allow that.	1189	does not allow that.
997		1190
998	The "utf8" flag therefore switches between two modes: disabled means	1191	The "utf8" flag therefore switches between two modes: disabled means
999	you will get a Unicode string in Perl, enabled means you get an	1192	you will get a Unicode string in Perl, enabled means you get a UTF-8
1000	UTF-8 encoded octet/binary string in Perl.	1193	encoded octet/binary string in Perl.
1001		1194
1002	"latin1" or "ascii" flags enabled	1195	"latin1" or "ascii" flags enabled
1003	With "latin1" (or "ascii") enabled, "encode" will escape characters	1196	With "latin1" (or "ascii") enabled, "encode" will escape characters
1004	with ordinal values > 255 (> 127 with "ascii") and encode the	1197	with ordinal values > 255 (> 127 with "ascii") and encode the
1005	remaining characters as specified by the "utf8" flag.	1198	remaining characters as specified by the "utf8" flag.
…		…
1041	structure back. This is useful when your channel for JSON transfer	1234	structure back. This is useful when your channel for JSON transfer
1042	is not 8-bit clean or the encoding might be mangled in between (e.g.	1235	is not 8-bit clean or the encoding might be mangled in between (e.g.
1043	in mail), and works because ASCII is a proper subset of most 8-bit	1236	in mail), and works because ASCII is a proper subset of most 8-bit
1044	and multibyte encodings in use in the world.	1237	and multibyte encodings in use in the world.
1045		1238
		1239	JSON and ECMAscript
		1240	JSON syntax is based on how literals are represented in javascript (the
		1241	not-standardised predecessor of ECMAscript) which is presumably why it
		1242	is called "JavaScript Object Notation".
		1243
		1244	However, JSON is not a subset (and also not a superset of course) of
		1245	ECMAscript (the standard) or javascript (whatever browsers actually
		1246	implement).
		1247
		1248	If you want to use javascript's "eval" function to "parse" JSON, you
		1249	might run into parse errors for valid JSON texts, or the resulting data
		1250	structure might not be queryable:
		1251
		1252	One of the problems is that U+2028 and U+2029 are valid characters
		1253	inside JSON strings, but are not allowed in ECMAscript string literals,
		1254	so the following Perl fragment will not output something that can be
		1255	guaranteed to be parsable by javascript's "eval":
		1256
		1257	use JSON::XS;
		1258
		1259	print encode_json [chr 0x2028];
		1260
		1261	The right fix for this is to use a proper JSON parser in your javascript
		1262	programs, and not rely on "eval" (see for example Douglas Crockford's
		1263	json2.js parser).
		1264
		1265	If this is not an option, you can, as a stop-gap measure, simply encode
		1266	to ASCII-only JSON:
		1267
		1268	use JSON::XS;
		1269
		1270	print JSON::XS->new->ascii->encode ([chr 0x2028]);
		1271
		1272	Note that this will enlarge the resulting JSON text quite a bit if you
		1273	have many non-ASCII characters. You might be tempted to run some regexes
		1274	to only escape U+2028 and U+2029, e.g.:
		1275
		1276	# DO NOT USE THIS!
		1277	my $json = JSON::XS->new->utf8->encode ([chr 0x2028]);
		1278	$json =~ s/\xe2\x80\xa8/\\u2028/g; # escape U+2028
		1279	$json =~ s/\xe2\x80\xa9/\\u2029/g; # escape U+2029
		1280	print $json;
		1281
		1282	Note that this is a bad idea: the above only works for U+2028 and
		1283	U+2029 and thus only for fully ECMAscript-compliant parsers. Many
		1284	existing javascript implementations, however, have issues with other
		1285	characters as well - using "eval" naively simply will cause problems.
		1286
		1287	Another problem is that some javascript implementations reserve some
		1288	property names for their own purposes (which probably makes them
		1289	non-ECMAscript-compliant). For example, Iceweasel reserves the
		1290	"__proto__" property name for its own purposes.
		1291
		1292	If that is a problem, you could parse try to filter the resulting JSON
		1293	output for these property strings, e.g.:
		1294
		1295	$json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
		1296
		1297	This works because "__proto__" is not valid outside of strings, so every
		1298	occurrence of ""__proto__"\s*:" must be a string used as property name.
		1299
		1300	If you know of other incompatibilities, please let me know.
		1301
1046	JSON and YAML	1302	JSON and YAML
1047	You often hear that JSON is a subset of YAML. This is, however, a mass	1303	You often hear that JSON is a subset of YAML. This is, however, a mass
1048	hysteria(*) and very far from the truth (as of the time of this	1304	hysteria(*) and very far from the truth (as of the time of this
1049	writing), so let me state it clearly: *in general, there is no way to	1305	writing), so let me state it clearly: *in general, there is no way to
1050	configure JSON::XS to output a data structure as valid YAML* that works	1306	configure JSON::XS to output a data structure as valid YAML* that works
…		…
1057	my $yaml = $to_yaml->encode ($ref) . "\n";	1313	my $yaml = $to_yaml->encode ($ref) . "\n";
1058		1314
1059	This will usually generate JSON texts that also parse as valid YAML.	1315	This will usually generate JSON texts that also parse as valid YAML.
1060	Please note that YAML has hardcoded limits on (simple) object key	1316	Please note that YAML has hardcoded limits on (simple) object key
1061	lengths that JSON doesn't have and also has different and incompatible	1317	lengths that JSON doesn't have and also has different and incompatible
1062	unicode handling, so you should make sure that your hash keys are	1318	unicode character escape syntax, so you should make sure that your hash
1063	noticeably shorter than the 1024 "stream characters" YAML allows and	1319	keys are noticeably shorter than the 1024 "stream characters" YAML
1064	that you do not have characters with codepoint values outside the	1320	allows and that you do not have characters with codepoint values outside
1065	Unicode BMP (basic multilingual page). YAML also does not allow "\/"	1321	the Unicode BMP (basic multilingual page). YAML also does not allow "\/"
1066	sequences in strings (which JSON::XS does not currently generate, but	1322	sequences in strings (which JSON::XS does not currently generate, but
1067	other JSON generators might).	1323	other JSON generators might).
1068		1324
1069	There might be other incompatibilities that I am not aware of (or the	1325	There might be other incompatibilities that I am not aware of (or the
1070	YAML specification has been changed yet again - it does so quite often).	1326	YAML specification has been changed yet again - it does so quite often).
…		…
1087	(which is not that difficult or long) and finally make YAML	1343	(which is not that difficult or long) and finally make YAML
1088	compatible to it, and educating users about the changes, instead of	1344	compatible to it, and educating users about the changes, instead of
1089	spreading lies about the real compatibility for many years and	1345	spreading lies about the real compatibility for many years and
1090	trying to silence people who point out that it isn't true.	1346	trying to silence people who point out that it isn't true.
1091		1347
		1348	Addendum/2009: the YAML 1.2 spec is still incompatible with JSON,
		1349	even though the incompatibilities have been documented (and are
		1350	known to Brian) for many years and the spec makes explicit claims
		1351	that YAML is a superset of JSON. It would be so easy to fix, but
		1352	apparently, bullying people and corrupting userdata is so much
		1353	easier.
		1354
1092	SPEED	1355	SPEED
1093	It seems that JSON::XS is surprisingly fast, as shown in the following	1356	It seems that JSON::XS is surprisingly fast, as shown in the following
1094	tables. They have been generated with the help of the "eg/bench" program	1357	tables. They have been generated with the help of the "eg/bench" program
1095	in the JSON::XS distribution, to make it easy to compare on your own	1358	in the JSON::XS distribution, to make it easy to compare on your own
1096	system.	1359	system.
1097		1360
1098	First comes a comparison between various modules using a very short	1361	First comes a comparison between various modules using a very short
1099	single-line JSON string (also available at	1362	single-line JSON string (also available at
1100	<http://dist.schmorp.de/misc/json/short.json>).	1363	<http://dist.schmorp.de/misc/json/short.json>).
1101		1364
1102	{"method": "handleMessage", "params": ["user1", "we were just talking"], \	1365	{"method": "handleMessage", "params": ["user1",
1103	"id": null, "array":[1,11,234,-5,1e5,1e7, true, false]}	1366	"we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7,
		1367	1, 0]}
1104		1368
1105	It shows the number of encodes/decodes per second (JSON::XS uses the	1369	It shows the number of encodes/decodes per second (JSON::XS uses the
1106	functional interface, while JSON::XS/2 uses the OO interface with	1370	functional interface, while JSON::XS/2 uses the OO interface with
1107	pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink).	1371	pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink.
1108	Higher is better:	1372	JSON::DWIW/DS uses the deserialise function, while JSON::DWIW::FJ uses
		1373	the from_json method). Higher is better:
1109		1374
1110	module \| encode \| decode \|	1375	module \| encode \| decode \|
1111	-----------\|------------\|------------\|	1376	--------------\|------------\|------------\|
1112	JSON 1.x \| 4990.842 \| 4088.813 \|	1377	JSON::DWIW/DS \| 86302.551 \| 102300.098 \|
1113	JSON::DWIW \| 51653.990 \| 71575.154 \|	1378	JSON::DWIW/FJ \| 86302.551 \| 75983.768 \|
1114	JSON::PC \| 65948.176 \| 74631.744 \|	1379	JSON::PP \| 15827.562 \| 6638.658 \|
1115	JSON::PP \| 8931.652 \| 3817.168 \|	1380	JSON::Syck \| 63358.066 \| 47662.545 \|
1116	JSON::Syck \| 24877.248 \| 27776.848 \|	1381	JSON::XS \| 511500.488 \| 511500.488 \|
1117	JSON::XS \| 388361.481 \| 227951.304 \|	1382	JSON::XS/2 \| 291271.111 \| 388361.481 \|
1118	JSON::XS/2 \| 227951.304 \| 218453.333 \|	1383	JSON::XS/3 \| 361577.931 \| 361577.931 \|
1119	JSON::XS/3 \| 338250.323 \| 218453.333 \|	1384	Storable \| 66788.280 \| 265462.278 \|
1120	Storable \| 16500.016 \| 135300.129 \|
1121	-----------+------------+------------+	1385	--------------+------------+------------+
1122		1386
1123	That is, JSON::XS is about five times faster than JSON::DWIW on	1387	That is, JSON::XS is almost six times faster than JSON::DWIW on
1124	encoding, about three times faster on decoding, and over forty times	1388	encoding, about five times faster on decoding, and over thirty to
1125	faster than JSON, even with pretty-printing and key sorting. It also	1389	seventy times faster than JSON's pure perl implementation. It also
1126	compares favourably to Storable for small amounts of data.	1390	compares favourably to Storable for small amounts of data.
1127		1391
1128	Using a longer test string (roughly 18KB, generated from Yahoo! Locals	1392	Using a longer test string (roughly 18KB, generated from Yahoo! Locals
1129	search API (<http://dist.schmorp.de/misc/json/long.json>).	1393	search API (<http://dist.schmorp.de/misc/json/long.json>).
1130		1394
1131	module \| encode \| decode \|	1395	module \| encode \| decode \|
1132	-----------\|------------\|------------\|	1396	--------------\|------------\|------------\|
1133	JSON 1.x \| 55.260 \| 34.971 \|	1397	JSON::DWIW/DS \| 1647.927 \| 2673.916 \|
1134	JSON::DWIW \| 825.228 \| 1082.513 \|	1398	JSON::DWIW/FJ \| 1630.249 \| 2596.128 \|
1135	JSON::PC \| 3571.444 \| 2394.829 \|
1136	JSON::PP \| 210.987 \| 32.574 \|	1399	JSON::PP \| 400.640 \| 62.311 \|
1137	JSON::Syck \| 552.551 \| 787.544 \|	1400	JSON::Syck \| 1481.040 \| 1524.869 \|
1138	JSON::XS \| 5780.463 \| 4854.519 \|	1401	JSON::XS \| 20661.596 \| 9541.183 \|
1139	JSON::XS/2 \| 3869.998 \| 4798.975 \|	1402	JSON::XS/2 \| 10683.403 \| 9416.938 \|
1140	JSON::XS/3 \| 5862.880 \| 4798.975 \|	1403	JSON::XS/3 \| 20661.596 \| 9400.054 \|
1141	Storable \| 4445.002 \| 5235.027 \|	1404	Storable \| 19765.806 \| 10000.725 \|
1142	-----------+------------+------------+	1405	--------------+------------+------------+
1143		1406
1144	Again, JSON::XS leads by far (except for Storable which non-surprisingly	1407	Again, JSON::XS leads by far (except for Storable which non-surprisingly
1145	decodes faster).	1408	decodes a bit faster).
1146		1409
1147	On large strings containing lots of high Unicode characters, some	1410	On large strings containing lots of high Unicode characters, some
1148	modules (such as JSON::PC) seem to decode faster than JSON::XS, but the	1411	modules (such as JSON::PC) seem to decode faster than JSON::XS, but the
1149	result will be broken due to missing (or wrong) Unicode handling. Others	1412	result will be broken due to missing (or wrong) Unicode handling. Others
1150	refuse to decode or encode properly, so it was impossible to prepare a	1413	refuse to decode or encode properly, so it was impossible to prepare a
…		…
1185	information you might want to make sure that exceptions thrown by	1448	information you might want to make sure that exceptions thrown by
1186	JSON::XS will not end up in front of untrusted eyes.	1449	JSON::XS will not end up in front of untrusted eyes.
1187		1450
1188	If you are using JSON::XS to return packets to consumption by JavaScript	1451	If you are using JSON::XS to return packets to consumption by JavaScript
1189	scripts in a browser you should have a look at	1452	scripts in a browser you should have a look at
1190	<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether	1453	<http://blog.archive.jpsykes.com/47/practical-csrf-and-json-security/>
1191	you are vulnerable to some common attack vectors (which really are	1454	to see whether you are vulnerable to some common attack vectors (which
1192	browser design bugs, but it is still you who will have to deal with it,	1455	really are browser design bugs, but it is still you who will have to
1193	as major browser developers care only for features, not about getting	1456	deal with it, as major browser developers care only for features, not
1194	security right).	1457	about getting security right).
1195		1458
		1459	"OLD" VS. "NEW" JSON (RFC4627 VS. RFC7159)
		1460	JSON originally required JSON texts to represent an array or object -
		1461	scalar values were explicitly not allowed. This has changed, and
		1462	versions of JSON::XS beginning with 4.0 reflect this by allowing scalar
		1463	values by default.
		1464
		1465	One reason why one might not want this is that this removes a
		1466	fundamental property of JSON texts, namely that they are self-delimited
		1467	and self-contained, or in other words, you could take any number of
		1468	"old" JSON texts and paste them together, and the result would be
		1469	unambiguously parseable:
		1470
		1471	[1,3]{"k":5}[][null] # four JSON texts, without doubt
		1472
		1473	By allowing scalars, this property is lost: in the following example, is
		1474	this one JSON text (the number 12) or two JSON texts (the numbers 1 and
		1475	2):
		1476
		1477	12 # could be 12, or 1 and 2
		1478
		1479	Another lost property of "old" JSON is that no lookahead is required to
		1480	know the end of a JSON text, i.e. the JSON text definitely ended at the
		1481	last "]" or "}" character, there was no need to read extra characters.
		1482
		1483	For example, a viable network protocol with "old" JSON was to simply
		1484	exchange JSON texts without delimiter. For "new" JSON, you have to use a
		1485	suitable delimiter (such as a newline) after every JSON text or ensure
		1486	you never encode/decode scalar values.
		1487
		1488	Most protocols do work by only transferring arrays or objects, and the
		1489	easiest way to avoid problems with the "new" JSON definition is to
		1490	explicitly disallow scalar values in your encoder and decoder:
		1491
		1492	$json_coder = JSON::XS->new->allow_nonref (0)
		1493
		1494	This is a somewhat unhappy situation, and the blame can fully be put on
		1495	JSON's inmventor, Douglas Crockford, who unilaterally changed the format
		1496	in 2006 without consulting the IETF, forcing the IETF to either fork the
		1497	format or go with it (as I was told, the IETF wasn't amused).
		1498
		1499	RELATIONSHIP WITH I-JSON
		1500	JSON is a somewhat sloppily-defined format - it carries around obvious
		1501	Javascript baggage, such as not really defining number range, probably
		1502	because Javascript only has one type of numbers: IEEE 64 bit floats
		1503	("binary64").
		1504
		1505	For this reaosn, RFC7493 defines "Internet JSON", which is a restricted
		1506	subset of JSON that is supposedly more interoperable on the internet.
		1507
		1508	While "JSON::XS" does not offer specific support for I-JSON, it of
		1509	course accepts valid I-JSON and by default implements some of the
		1510	limitations of I-JSON, such as parsing numbers as perl numbers, which
		1511	are usually a superset of binary64 numbers.
		1512
		1513	To generate I-JSON, follow these rules:
		1514
		1515	* always generate UTF-8
		1516
		1517	I-JSON must be encoded in UTF-8, the default for "encode_json".
		1518
		1519	* numbers should be within IEEE 754 binary64 range
		1520
		1521	Basically all existing perl installations use binary64 to represent
		1522	floating point numbers, so all you need to do is to avoid large
		1523	integers.
		1524
		1525	* objects must not have duplicate keys
		1526
		1527	This is trivially done, as "JSON::XS" does not allow duplicate keys.
		1528
		1529	* do not generate scalar JSON texts, use "->allow_nonref (0)"
		1530
		1531	I-JSON strongly requests you to only encode arrays and objects into
		1532	JSON.
		1533
		1534	* times should be strings in ISO 8601 format
		1535
		1536	There are a myriad of modules on CPAN dealing with ISO 8601 - search
		1537	for "ISO8601" on CPAN and use one.
		1538
		1539	* encode binary data as base64
		1540
		1541	While it's tempting to just dump binary data as a string (and let
		1542	"JSON::XS" do the escaping), for I-JSON, it's recommended to
		1543	encode binary data as base64.
		1544
		1545	There are some other considerations - read RFC7493 for the details if
		1546	interested.
		1547
		1548	INTEROPERABILITY WITH OTHER MODULES
		1549	"JSON::XS" uses the Types::Serialiser module to provide boolean
		1550	constants. That means that the JSON true and false values will be
		1551	comaptible to true and false values of other modules that do the same,
		1552	such as JSON::PP and CBOR::XS.
		1553
		1554	INTEROPERABILITY WITH OTHER JSON DECODERS
		1555	As long as you only serialise data that can be directly expressed in
		1556	JSON, "JSON::XS" is incapable of generating invalid JSON output (modulo
		1557	bugs, but "JSON::XS" has found more bugs in the official JSON testsuite
		1558	(1) than the official JSON testsuite has found in "JSON::XS" (0)).
		1559
		1560	When you have trouble decoding JSON generated by this module using other
		1561	decoders, then it is very likely that you have an encoding mismatch or
		1562	the other decoder is broken.
		1563
		1564	When decoding, "JSON::XS" is strict by default and will likely catch all
		1565	errors. There are currently two settings that change this: "relaxed"
		1566	makes "JSON::XS" accept (but not generate) some non-standard extensions,
		1567	and "allow_tags" will allow you to encode and decode Perl objects, at
		1568	the cost of not outputting valid JSON anymore.
		1569
		1570	TAGGED VALUE SYNTAX AND STANDARD JSON EN/DECODERS
		1571	When you use "allow_tags" to use the extended (and also nonstandard and
		1572	invalid) JSON syntax for serialised objects, and you still want to
		1573	decode the generated When you want to serialise objects, you can run a
		1574	regex to replace the tagged syntax by standard JSON arrays (it only
		1575	works for "normal" package names without comma, newlines or single
		1576	colons). First, the readable Perl version:
		1577
		1578	# if your FREEZE methods return no values, you need this replace first:
		1579	$json =~ s/$ \s* (" (?: [^\\":,]+\|\\.\|::)* ") \s* $ \s* \[\s*\]/[$1]/gx;
		1580
		1581	# this works for non-empty constructor arg lists:
		1582	$json =~ s/$ \s* (" (?: [^\\":,]+\|\\.\|::)* ") \s* $ \s* \[/[$1,/gx;
		1583
		1584	And here is a less readable version that is easy to adapt to other
		1585	languages:
		1586
		1587	$json =~ s/$\s("([^\\":,]+\|\\.\|::)")\s$\s\[/[$1,/g;
		1588
		1589	Here is an ECMAScript version (same regex):
		1590
		1591	json = json.replace (/$\s("([^\\":,]+\|\\.\|::)")\s$\s\[/g, "[$1,");
		1592
		1593	Since this syntax converts to standard JSON arrays, it might be hard to
		1594	distinguish serialised objects from normal arrays. You can prepend a
		1595	"magic number" as first array element to reduce chances of a collision:
		1596
		1597	$json =~ s/$\s("([^\\":,]+\|\\.\|::)")\s$\s\[/["XU1peReLzT4ggEllLanBYq4G9VzliwKF",$1,/g;
		1598
		1599	And after decoding the JSON text, you could walk the data structure
		1600	looking for arrays with a first element of
		1601	"XU1peReLzT4ggEllLanBYq4G9VzliwKF".
		1602
		1603	The same approach can be used to create the tagged format with another
		1604	encoder. First, you create an array with the magic string as first
		1605	member, the classname as second, and constructor arguments last, encode
		1606	it as part of your JSON structure, and then:
		1607
		1608	$json =~ s/\[\s"XU1peReLzT4ggEllLanBYq4G9VzliwKF"\s,\s("([^\\":,]+\|\\.\|::)")\s*,/($1)[/g;
		1609
		1610	Again, this has some limitations - the magic string must not be encoded
		1611	with character escapes, and the constructor arguments must be non-empty.
		1612
1196	THREADS	1613	(I-)THREADS
1197	This module is not guaranteed to be thread safe and there are no plans	1614	This module is not guaranteed to be ithread (or MULTIPLICITY-) safe
1198	to change this until Perl gets thread support (as opposed to the	1615	and there are no plans to change this. Note that perl's builtin
1199	horribly slow so-called "threads" which are simply slow and bloated	1616	so-called threads/ithreads are officially deprecated and should not be
1200	process simulations - use fork, it's much faster, cheaper, better).	1617	used.
1201		1618
1202	(It might actually work, but you have been warned).	1619	THE PERILS OF SETLOCALE
		1620	Sometimes people avoid the Perl locale support and directly call the
		1621	system's setlocale function with "LC_ALL".
		1622
		1623	This breaks both perl and modules such as JSON::XS, as stringification
		1624	of numbers no longer works correctly (e.g. "$x = 0.1; print "$x"+1"
		1625	might print 1, and JSON::XS might output illegal JSON as JSON::XS relies
		1626	on perl to stringify numbers).
		1627
		1628	The solution is simple: don't call "setlocale", or use it for only those
		1629	categories you need, such as "LC_MESSAGES" or "LC_CTYPE".
		1630
		1631	If you need "LC_NUMERIC", you should enable it only around the code that
		1632	actually needs it (avoiding stringification of numbers), and restore it
		1633	afterwards.
		1634
		1635	SOME HISTORY
		1636	At the time this module was created there already were a number of JSON
		1637	modules available on CPAN, so what was the reason to write yet another
		1638	JSON module? While it seems there are many JSON modules, none of them
		1639	correctly handled all corner cases, and in most cases their maintainers
		1640	are unresponsive, gone missing, or not listening to bug reports for
		1641	other reasons.
		1642
		1643	Beginning with version 2.0 of the JSON module, when both JSON and
		1644	JSON::XS are installed, then JSON will fall back on JSON::XS (this can
		1645	be overridden) with no overhead due to emulation (by inheriting
		1646	constructor and methods). If JSON::XS is not available, it will fall
		1647	back to the compatible JSON::PP module as backend, so using JSON instead
		1648	of JSON::XS gives you a portable JSON API that can be fast when you need
		1649	it and doesn't require a C compiler when that is a problem.
		1650
		1651	Somewhere around version 3, this module was forked into
		1652	"Cpanel::JSON::XS", because its maintainer had serious trouble
		1653	understanding JSON and insisted on a fork with many bugs "fixed" that
		1654	weren't actually bugs, while spreading FUD about this module without
		1655	actually giving any details on his accusations. You be the judge, but in
		1656	my personal opinion, if you want quality, you will stay away from
		1657	dangerous forks like that.
1203		1658
1204	BUGS	1659	BUGS
1205	While the goal of this module is to be correct, that unfortunately does	1660	While the goal of this module is to be correct, that unfortunately does
1206	not mean it's bug-free, only that I think its design is bug-free. It is	1661	not mean it's bug-free, only that I think its design is bug-free. If you
1207	still relatively early in its development. If you keep reporting bugs
1208	they will be fixed swiftly, though.	1662	keep reporting bugs they will be fixed swiftly, though.
1209		1663
1210	Please refrain from using rt.cpan.org or any other bug reporting	1664	Please refrain from using rt.cpan.org or any other bug reporting
1211	service. I put the contact address into my modules for a reason.	1665	service. I put the contact address into my modules for a reason.
1212		1666
1213	SEE ALSO	1667	SEE ALSO

Diff Legend

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

Comparing JSON-XS/README (file contents): Revision 1.24 by root, Thu Mar 27 06:37:35 2008 UTC vs. Revision 1.43 by root, Thu Nov 15 23:07:55 2018 UTC

Diff Legend

Comparing JSON-XS/README (file contents):
Revision 1.24 by root, Thu Mar 27 06:37:35 2008 UTC vs.
Revision 1.43 by root, Thu Nov 15 23:07:55 2018 UTC