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

Comparing JSON-XS/README (file contents):
Revision 1.1 by root, Thu Mar 22 16:40:16 2007 UTC vs.
Revision 1.5 by root, Sat Mar 24 01:15:22 2007 UTC

1	NAME	1	NAME
2	Convert::Scalar - convert between different representations of perl	2	JSON::XS - JSON serialising/deserialising, done correctly and fast
3	scalars
4		3
5	SYNOPSIS	4	SYNOPSIS
6	use Convert::Scalar;	5	use JSON::XS;
		6
		7	# exported functions, croak on error
		8
		9	$utf8_encoded_json_text = to_json $perl_hash_or_arrayref;
		10	$perl_hash_or_arrayref = from_json $utf8_encoded_json_text;
		11
		12	# oo-interface
		13
		14	$coder = JSON::XS->new->ascii->pretty->allow_nonref;
		15	$pretty_printed_unencoded = $coder->encode ($perl_scalar);
		16	$perl_scalar = $coder->decode ($unicode_json_text);
7		17
8	DESCRIPTION	18	DESCRIPTION
9	This module exports various internal perl methods that change the	19	This module converts Perl data structures to JSON and vice versa. Its
10	internal representation or state of a perl scalar. All of these work	20	primary goal is to be correct and its secondary goal is to be fast.
11	in-place, that is, they modify their scalar argument. No functions are	21	To reach the latter goal it was written in C.
		22
		23	As this is the n-th-something JSON module on CPAN, what was the reason
		24	to write yet another JSON module? While it seems there are many JSON
		25	modules, none of them correctly handle all corner cases, and in most
		26	cases their maintainers are unresponsive, gone missing, or not listening
		27	to bug reports for other reasons.
		28
		29	See COMPARISON, below, for a comparison to some other JSON modules.
		30
		31	See MAPPING, below, on how JSON::XS maps perl values to JSON values and
		32	vice versa.
		33
		34	FEATURES
		35	* correct handling of unicode issues
		36	This module knows how to handle Unicode, and even documents how and
		37	when it does so.
		38
		39	* round-trip integrity
		40	When you serialise a perl data structure using only datatypes
		41	supported by JSON, the deserialised data structure is identical on
		42	the Perl level. (e.g. the string "2.0" doesn't suddenly become "2").
		43
		44	* strict checking of JSON correctness
		45	There is no guessing, no generating of illegal JSON strings by
		46	default, and only JSON is accepted as input by default (the latter
		47	is a security feature).
		48
		49	* fast
		50	Compared to other JSON modules, this module compares favourably in
		51	terms of speed, too.
		52
		53	* simple to use
		54	This module has both a simple functional interface as well as an OO
		55	interface.
		56
		57	* reasonably versatile output formats
		58	You can choose between the most compact guarenteed single-line
		59	format possible (nice for simple line-based protocols), a pure-ascii
		60	format (for when your transport is not 8-bit clean), or a
		61	pretty-printed format (for when you want to read that stuff). Or you
		62	can combine those features in whatever way you like.
		63
		64	FUNCTIONAL INTERFACE
		65	The following convinience methods are provided by this module. They are
12	exported by default.	66	exported by default:
13		67
14	The following export tags exist:	68	$json_string = to_json $perl_scalar
		69	Converts the given Perl data structure (a simple scalar or a
		70	reference to a hash or array) to a UTF-8 encoded, binary string
		71	(that is, the string contains octets only). Croaks on error.
15		72
16	:utf8 all functions with utf8 in their name	73	This function call is functionally identical to
17	:taint all functions with taint in their name	74	"JSON::XS->new->utf8->encode ($perl_scalar)".
18	:refcnt all functions with refcnt in their name
19	:ok all *ok-functions.
20		75
21	utf8 scalar[, mode]	76	$perl_scalar = from_json $json_string
22	Returns true when the given scalar is marked as utf8, false	77	The opposite of "to_json": expects an UTF-8 (binary) string and
23	otherwise. If the optional mode argument is given, also forces the	78	tries to parse that as an UTF-8 encoded JSON string, returning the
24	interpretation of the string to utf8 (mode true) or plain bytes	79	resulting simple scalar or reference. Croaks on error.
25	(mode false). The actual (byte-) content is not changed. The return
26	value always reflects the state before any modification is done.
27		80
28	This function is useful when you "import" utf8-data into perl, or	81	This function call is functionally identical to
29	when some external function (e.g. storing/retrieving from a	82	"JSON::XS->new->utf8->decode ($json_string)".
30	database) removes the utf8-flag.
31		83
32	utf8_on scalar	84	OBJECT-ORIENTED INTERFACE
33	Similar to "utf8 scalar, 1", but additionally returns the scalar	85	The object oriented interface lets you configure your own encoding or
34	(the argument is still modified in-place).	86	decoding style, within the limits of supported formats.
35		87
36	utf8_off scalar	88	$json = new JSON::XS
37	Similar to "utf8 scalar, 0", but additionally returns the scalar	89	Creates a new JSON::XS object that can be used to de/encode JSON
38	(the argument is still modified in-place).	90	strings. All boolean flags described below are by default
		91	disabled.
39		92
40	utf8_valid scalar [Perl 5.7]	93	The mutators for flags all return the JSON object again and thus
41	Returns true if the bytes inside the scalar form a valid utf8	94	calls can be chained:
42	string, false otherwise (the check is independent of the actual
43	encoding perl thinks the string is in).
44		95
45	utf8_upgrade scalar	96	my $json = JSON::XS->new->utf8(1)->space_after(1)->encode ({a => [1,2]})
46	Convert the string content of the scalar in-place to its	97	=> {"a": [1, 2]}
47	UTF8-encoded form (and also returns it).
48		98
49	utf8_downgrade scalar[, fail_ok=0]	99	$json = $json->ascii ([$enable])
50	Attempt to convert the string content of the scalar from	100	If $enable is true (or missing), then the "encode" method will not
51	UTF8-encoded to ISO-8859-1. This may not be possible if the string	101	generate characters outside the code range 0..127. Any unicode
52	contains characters that cannot be represented in a single byte; if	102	characters outside that range will be escaped using either a single
53	this is the case, it leaves the scalar unchanged and either returns	103	\uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence,
54	false or, if "fail_ok" is not true (the default), croaks.	104	as per RFC4627.
55		105
56	utf8_encode scalar	106	If $enable is false, then the "encode" method will not escape
57	Convert the string value of the scalar to UTF8-encoded, but then	107	Unicode characters unless necessary.
58	turn off the "SvUTF8" flag so that it looks like bytes to perl
59	again. (Might be removed in future versions).
60		108
61	utf8_length scalar	109	JSON::XS->new->ascii (1)->encode (chr 0x10401)
62	Returns the number of characters in the string, counting wide UTF8	110	=> \ud801\udc01
63	characters as a single character, independent of wether the scalar
64	is marked as containing bytes or mulitbyte characters.
65		111
66	unmagic scalar, type	112	$json = $json->utf8 ([$enable])
67	Remove the specified magic from the scalar (DANGEROUS!).	113	If $enable is true (or missing), then the "encode" method will
		114	encode the JSON string into UTF-8, as required by many protocols,
		115	while the "decode" method expects to be handled an UTF-8-encoded
		116	string. Please note that UTF-8-encoded strings do not contain any
		117	characters outside the range 0..255, they are thus useful for
		118	bytewise/binary I/O.
68		119
69	weaken scalar	120	If $enable is false, then the "encode" method will return the JSON
70	Weaken a reference. (See also WeakRef).	121	string as a (non-encoded) unicode string, while "decode" expects
		122	thus a unicode string. Any decoding or encoding (e.g. to UTF-8 or
		123	UTF-16) needs to be done yourself, e.g. using the Encode module.
71		124
72	taint scalar	125	Example, output UTF-16-encoded JSON:
73	Taint the scalar.
74		126
75	tainted scalar	127	$json = $json->pretty ([$enable])
76	returns true when the scalar is tainted, false otherwise.	128	This enables (or disables) all of the "indent", "space_before" and
		129	"space_after" (and in the future possibly more) flags in one call to
		130	generate the most readable (or most compact) form possible.
77		131
78	untaint scalar	132	Example, pretty-print some simple structure:
79	Remove the tainted flag from the specified scalar.
80		133
81	grow scalar, newlen	134	my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]})
82	Sets the memory area used for the scalar to the given length, if the	135	=>
83	current length is less than the new value. This does not affect the	136	{
84	contents of the scalar, but is only useful to "pre-allocate" memory	137	"a" : [
85	space if you know the scalar will grow. The return value is the	138	1,
86	modified scalar (the scalar is modified in-place).	139	2
		140	]
		141	}
87		142
88	refcnt scalar[, newrefcnt]	143	$json = $json->indent ([$enable])
89	Returns the current reference count of the given scalar and	144	If $enable is true (or missing), then the "encode" method will use a
90	optionally sets it to the given reference count.	145	multiline format as output, putting every array member or
		146	object/hash key-value pair into its own line, identing them
		147	properly.
91		148
92	refcnt_inc scalar	149	If $enable is false, no newlines or indenting will be produced, and
93	Increments the reference count of the given scalar inplace.	150	the resulting JSON strings is guarenteed not to contain any
		151	"newlines".
94		152
95	refcnt_dec scalar	153	This setting has no effect when decoding JSON strings.
96	Decrements the reference count of the given scalar inplace. Use
97	"weaken" instead if you understand what this function is fore.
98	Better yet: don't use this module in this case.
99		154
100	refcnt_rv scalar[, newrefcnt]	155	$json = $json->space_before ([$enable])
101	Works like "refcnt", but dereferences the given reference first.	156	If $enable is true (or missing), then the "encode" method will add
102	This is useful to find the reference count of arrays or hashes,	157	an extra optional space before the ":" separating keys from values
103	which cnanot be passed directly. Remember that taking a reference of	158	in JSON objects.
104	some object increases it's reference count, so the reference count
105	used by the *_rv-functions tend to be one higher.
106		159
107	refcnt_inc_rv scalar	160	If $enable is false, then the "encode" method will not add any extra
108	Works like "refcnt_inc", but dereferences the given reference first.	161	space at those places.
109		162
110	refcnt_dec_rv scalar	163	This setting has no effect when decoding JSON strings. You will also
111	Works like "refcnt_dec", but dereferences the given reference first.	164	most likely combine this setting with "space_after".
112		165
113	ok scalar	166	Example, space_before enabled, space_after and indent disabled:
114	uok scalar	167
115	rok scalar	168	{"key" :"value"}
		169
		170	$json = $json->space_after ([$enable])
		171	If $enable is true (or missing), then the "encode" method will add
		172	an extra optional space after the ":" separating keys from values in
		173	JSON objects and extra whitespace after the "," separating key-value
		174	pairs and array members.
		175
		176	If $enable is false, then the "encode" method will not add any extra
		177	space at those places.
		178
		179	This setting has no effect when decoding JSON strings.
		180
		181	Example, space_before and indent disabled, space_after enabled:
		182
		183	{"key": "value"}
		184
		185	$json = $json->canonical ([$enable])
		186	If $enable is true (or missing), then the "encode" method will
		187	output JSON objects by sorting their keys. This is adding a
		188	comparatively high overhead.
		189
		190	If $enable is false, then the "encode" method will output key-value
		191	pairs in the order Perl stores them (which will likely change
		192	between runs of the same script).
		193
		194	This option is useful if you want the same data structure to be
		195	encoded as the same JSON string (given the same overall settings).
		196	If it is disabled, the same hash migh be encoded differently even if
		197	contains the same data, as key-value pairs have no inherent ordering
		198	in Perl.
		199
		200	This setting has no effect when decoding JSON strings.
		201
		202	$json = $json->allow_nonref ([$enable])
		203	If $enable is true (or missing), then the "encode" method can
		204	convert a non-reference into its corresponding string, number or
		205	null JSON value, which is an extension to RFC4627. Likewise,
		206	"decode" will accept those JSON values instead of croaking.
		207
		208	If $enable is false, then the "encode" method will croak if it isn't
		209	passed an arrayref or hashref, as JSON strings must either be an
		210	object or array. Likewise, "decode" will croak if given something
		211	that is not a JSON object or array.
		212
		213	Example, encode a Perl scalar as JSON value with enabled
		214	"allow_nonref", resulting in an invalid JSON text:
		215
		216	JSON::XS->new->allow_nonref->encode ("Hello, World!")
		217	=> "Hello, World!"
		218
		219	$json = $json->shrink ([$enable])
		220	Perl usually over-allocates memory a bit when allocating space for
		221	strings. This flag optionally resizes strings generated by either
		222	"encode" or "decode" to their minimum size possible. This can save
		223	memory when your JSON strings are either very very long or you have
		224	many short strings. It will also try to downgrade any strings to
		225	octet-form if possible: perl stores strings internally either in an
		226	encoding called UTF-X or in octet-form. The latter cannot store
		227	everything but uses less space in general.
		228
		229	If $enable is true (or missing), the string returned by "encode"
		230	will be shrunk-to-fit, while all strings generated by "decode" will
		231	also be shrunk-to-fit.
		232
		233	If $enable is false, then the normal perl allocation algorithms are
		234	used. If you work with your data, then this is likely to be faster.
		235
		236	In the future, this setting might control other things, such as
		237	converting strings that look like integers or floats into integers
		238	or floats internally (there is no difference on the Perl level),
		239	saving space.
		240
		241	$json_string = $json->encode ($perl_scalar)
		242	Converts the given Perl data structure (a simple scalar or a
		243	reference to a hash or array) to its JSON representation. Simple
		244	scalars will be converted into JSON string or number sequences,
		245	while references to arrays become JSON arrays and references to
		246	hashes become JSON objects. Undefined Perl values (e.g. "undef")
		247	become JSON "null" values. Neither "true" nor "false" values will be
		248	generated.
		249
		250	$perl_scalar = $json->decode ($json_string)
		251	The opposite of "encode": expects a JSON string and tries to parse
		252	it, returning the resulting simple scalar or reference. Croaks on
		253	error.
		254
		255	JSON numbers and strings become simple Perl scalars. JSON arrays
		256	become Perl arrayrefs and JSON objects become Perl hashrefs. "true"
		257	becomes 1, "false" becomes 0 and "null" becomes "undef".
		258
		259	MAPPING
		260	This section describes how JSON::XS maps Perl values to JSON values and
		261	vice versa. These mappings are designed to "do the right thing" in most
		262	circumstances automatically, preserving round-tripping characteristics
		263	(what you put in comes out as something equivalent).
		264
		265	For the more enlightened: note that in the following descriptions,
		266	lowercase perl refers to the Perl interpreter, while uppcercase Perl
		267	refers to the abstract Perl language itself.
		268
		269	JSON -> PERL
		270	object
		271	A JSON object becomes a reference to a hash in Perl. No ordering of
		272	object keys is preserved (JSON does not preserver object key
		273	ordering itself).
		274
		275	array
		276	A JSON array becomes a reference to an array in Perl.
		277
		278	string
		279	A JSON string becomes a string scalar in Perl - Unicode codepoints
		280	in JSON are represented by the same codepoints in the Perl string,
		281	so no manual decoding is necessary.
		282
		283	number
		284	A JSON number becomes either an integer or numeric (floating point)
		285	scalar in perl, depending on its range and any fractional parts. On
		286	the Perl level, there is no difference between those as Perl handles
		287	all the conversion details, but an integer may take slightly less
		288	memory and might represent more values exactly than (floating point)
		289	numbers.
		290
		291	true, false
		292	These JSON atoms become 0, 1, respectively. Information is lost in
		293	this process. Future versions might represent those values
		294	differently, but they will be guarenteed to act like these integers
		295	would normally in Perl.
		296
		297	null
		298	A JSON null atom becomes "undef" in Perl.
		299
		300	PERL -> JSON
		301	The mapping from Perl to JSON is slightly more difficult, as Perl is a
		302	truly typeless language, so we can only guess which JSON type is meant
		303	by a Perl value.
		304
		305	hash references
		306	Perl hash references become JSON objects. As there is no inherent
		307	ordering in hash keys, they will usually be encoded in a
		308	pseudo-random order that can change between runs of the same program
		309	but stays generally the same within a single run of a program.
		310	JSON::XS can optionally sort the hash keys (determined by the
		311	canonical flag), so the same datastructure will serialise to the
		312	same JSON text (given same settings and version of JSON::XS), but
		313	this incurs a runtime overhead.
		314
		315	array references
		316	Perl array references become JSON arrays.
		317
		318	blessed objects
		319	Blessed objects are not allowed. JSON::XS currently tries to encode
		320	their underlying representation (hash- or arrayref), but this
		321	behaviour might change in future versions.
		322
116	pok scalar	323	simple scalars
117	nok scalar	324	Simple Perl scalars (any scalar that is not a reference) are the
118	niok scalar	325	most difficult objects to encode: JSON::XS will encode undefined
119	Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given	326	scalars as JSON null value, scalars that have last been used in a
120	scalar, respectively.	327	string context before encoding as JSON strings and anything else as
		328	number value:
121		329
122	CANDIDATES FOR FUTURE RELEASES	330	# dump as number
123	The following API functions (perlapi) are considered for future	331	to_json [2] # yields [2]
124	inclusion in this module If you want them, write me.	332	to_json [-3.0e17] # yields [-3e+17]
		333	my $value = 5; to_json [$value] # yields [5]
125		334
126	sv_upgrade	335	# used as string, so dump as string
127	sv_pvn_force	336	print $value;
128	sv_pvutf8n_force	337	to_json [$value] # yields ["5"]
129	the sv2xx family	338
		339	# undef becomes null
		340	to_json [undef] # yields [null]
		341
		342	You can force the type to be a string by stringifying it:
		343
		344	my $x = 3.1; # some variable containing a number
		345	"$x"; # stringified
		346	$x .= ""; # another, more awkward way to stringify
		347	print $x; # perl does it for you, too, quite often
		348
		349	You can force the type to be a number by numifying it:
		350
		351	my $x = "3"; # some variable containing a string
		352	$x += 0; # numify it, ensuring it will be dumped as a number
		353	$x *= 1; # same thing, the choise is yours.
		354
		355	You can not currently output JSON booleans or force the type in
		356	other, less obscure, ways. Tell me if you need this capability.
		357
		358	circular data structures
		359	Those will be encoded until memory or stackspace runs out.
		360
		361	COMPARISON
		362	As already mentioned, this module was created because none of the
		363	existing JSON modules could be made to work correctly. First I will
		364	describe the problems (or pleasures) I encountered with various existing
		365	JSON modules, followed by some benchmark values. JSON::XS was designed
		366	not to suffer from any of these problems or limitations.
		367
		368	JSON 1.07
		369	Slow (but very portable, as it is written in pure Perl).
		370
		371	Undocumented/buggy Unicode handling (how JSON handles unicode values
		372	is undocumented. One can get far by feeding it unicode strings and
		373	doing en-/decoding oneself, but unicode escapes are not working
		374	properly).
		375
		376	No roundtripping (strings get clobbered if they look like numbers,
		377	e.g. the string 2.0 will encode to 2.0 instead of "2.0", and that
		378	will decode into the number 2.
		379
		380	JSON::PC 0.01
		381	Very fast.
		382
		383	Undocumented/buggy Unicode handling.
		384
		385	No roundtripping.
		386
		387	Has problems handling many Perl values (e.g. regex results and other
		388	magic values will make it croak).
		389
		390	Does not even generate valid JSON ("{1,2}" gets converted to "{1:2}"
		391	which is not a valid JSON string.
		392
		393	Unmaintained (maintainer unresponsive for many months, bugs are not
		394	getting fixed).
		395
		396	JSON::Syck 0.21
		397	Very buggy (often crashes).
		398
		399	Very inflexible (no human-readable format supported, format pretty
		400	much undocumented. I need at least a format for easy reading by
		401	humans and a single-line compact format for use in a protocol, and
		402	preferably a way to generate ASCII-only JSON strings).
		403
		404	Completely broken (and confusingly documented) Unicode handling
		405	(unicode escapes are not working properly, you need to set
		406	ImplicitUnicode to different values on en- and decoding to get
		407	symmetric behaviour).
		408
		409	No roundtripping (simple cases work, but this depends on wether the
		410	scalar value was used in a numeric context or not).
		411
		412	Dumping hashes may skip hash values depending on iterator state.
		413
		414	Unmaintained (maintainer unresponsive for many months, bugs are not
		415	getting fixed).
		416
		417	Does not check input for validity (i.e. will accept non-JSON input
		418	and return "something" instead of raising an exception. This is a
		419	security issue: imagine two banks transfering money between each
		420	other using JSON. One bank might parse a given non-JSON request and
		421	deduct money, while the other might reject the transaction with a
		422	syntax error. While a good protocol will at least recover, that is
		423	extra unnecessary work and the transaction will still not succeed).
		424
		425	JSON::DWIW 0.04
		426	Very fast. Very natural. Very nice.
		427
		428	Undocumented unicode handling (but the best of the pack. Unicode
		429	escapes still don't get parsed properly).
		430
		431	Very inflexible.
		432
		433	No roundtripping.
		434
		435	Does not generate valid JSON (key strings are often unquoted, empty
		436	keys result in nothing being output)
		437
		438	Does not check input for validity.
		439
		440	SPEED
		441	It seems that JSON::XS is surprisingly fast, as shown in the following
		442	tables. They have been generated with the help of the "eg/bench" program
		443	in the JSON::XS distribution, to make it easy to compare on your own
		444	system.
		445
		446	First comes a comparison between various modules using a very short JSON
		447	string (83 bytes), showing the number of encodes/decodes per second
		448	(JSON::XS is the functional interface, while JSON::XS/2 is the OO
		449	interface with pretty-printing and hashkey sorting enabled). Higher is
		450	better:
		451
		452	module \| encode \| decode \|
		453	-----------\|------------\|------------\|
		454	JSON \| 14006 \| 6820 \|
		455	JSON::DWIW \| 200937 \| 120386 \|
		456	JSON::PC \| 85065 \| 129366 \|
		457	JSON::Syck \| 59898 \| 44232 \|
		458	JSON::XS \| 1171478 \| 342435 \|
		459	JSON::XS/2 \| 730760 \| 328714 \|
		460	-----------+------------+------------+
		461
		462	That is, JSON::XS is 6 times faster than than JSON::DWIW and about 80
		463	times faster than JSON, even with pretty-printing and key sorting.
		464
		465	Using a longer test string (roughly 18KB, generated from Yahoo! Locals
		466	search API (http://nanoref.com/yahooapis/mgPdGg):
		467
		468	module \| encode \| decode \|
		469	-----------\|------------\|------------\|
		470	JSON \| 673 \| 38 \|
		471	JSON::DWIW \| 5271 \| 770 \|
		472	JSON::PC \| 9901 \| 2491 \|
		473	JSON::Syck \| 2360 \| 786 \|
		474	JSON::XS \| 37398 \| 3202 \|
		475	JSON::XS/2 \| 13765 \| 3153 \|
		476	-----------+------------+------------+
		477
		478	Again, JSON::XS leads by far in the encoding case, while still beating
		479	every other module in the decoding case.
		480
		481	On large strings containing lots of unicode characters, some modules
		482	(such as JSON::PC) decode faster than JSON::XS, but the result will be
		483	broken due to missing unicode handling. Others refuse to decode or
		484	encode properly, so it was impossible to prepare a fair comparison table
		485	for that case.
		486
		487	RESOURCE LIMITS
		488	JSON::XS does not impose any limits on the size of JSON texts or Perl
		489	values they represent - if your machine can handle it, JSON::XS will
		490	encode or decode it. Future versions might optionally impose structure
		491	depth and memory use resource limits.
		492
		493	BUGS
		494	While the goal of this module is to be correct, that unfortunately does
		495	not mean its bug-free, only that I think its design is bug-free. It is
		496	still very young and not well-tested. If you keep reporting bugs they
		497	will be fixed swiftly, though.
130		498
131	AUTHOR	499	AUTHOR
132	Marc Lehmann <schmorp@schmorp.de>	500	Marc Lehmann <schmorp@schmorp.de>
133	http://home.schmorp.de/	501	http://home.schmorp.de/
134		502

Diff Legend

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

Comparing JSON-XS/README (file contents): Revision 1.1 by root, Thu Mar 22 16:40:16 2007 UTC vs. Revision 1.5 by root, Sat Mar 24 01:15:22 2007 UTC

Diff Legend

Comparing JSON-XS/README (file contents):
Revision 1.1 by root, Thu Mar 22 16:40:16 2007 UTC vs.
Revision 1.5 by root, Sat Mar 24 01:15:22 2007 UTC