[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.4 by root, Fri Mar 23 18:33:50 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.
		273
		274	array
		275	A JSON array becomes a reference to an array in Perl.
		276
		277	string
		278	A JSON string becomes a string scalar in Perl - Unicode codepoints
		279	in JSON are represented by the same codepoints in the Perl string,
		280	so no manual decoding is necessary.
		281
		282	number
		283	A JSON number becomes either an integer or numeric (floating point)
		284	scalar in perl, depending on its range and any fractional parts. On
		285	the Perl level, there is no difference between those as Perl handles
		286	all the conversion details, but an integer may take slightly less
		287	memory and might represent more values exactly than (floating point)
		288	numbers.
		289
		290	true, false
		291	These JSON atoms become 0, 1, respectively. Information is lost in
		292	this process. Future versions might represent those values
		293	differently, but they will be guarenteed to act like these integers
		294	would normally in Perl.
		295
		296	null
		297	A JSON null atom becomes "undef" in Perl.
		298
		299	PERL -> JSON
		300	The mapping from Perl to JSON is slightly more difficult, as Perl is a
		301	truly typeless language, so we can only guess which JSON type is meant
		302	by a Perl value.
		303
		304	hash references
		305	Perl hash references become JSON objects. As there is no inherent
		306	ordering in hash keys, they will usually be encoded in a
		307	pseudo-random order that can change between runs of the same program
		308	but stays generally the same within the single run of a program.
		309	JSON::XS can optionally sort the hash keys (determined by the
		310	canonical flag), so the same datastructure will serialise to the
		311	same JSON text (given same settings and version of JSON::XS), but
		312	this incurs a runtime overhead.
		313
		314	array references
		315	Perl array references become JSON arrays.
		316
		317	blessed objects
		318	Blessed objects are not allowed. JSON::XS currently tries to encode
		319	their underlying representation (hash- or arrayref), but this
		320	behaviour might change in future versions.
		321
116	pok scalar	322	simple scalars
117	nok scalar	323	Simple Perl scalars (any scalar that is not a reference) are the
118	niok scalar	324	most difficult objects to encode: JSON::XS will encode undefined
119	Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given	325	scalars as JSON null value, scalars that have last been used in a
120	scalar, respectively.	326	string context before encoding as JSON strings and anything else as
		327	number value:
121		328
122	CANDIDATES FOR FUTURE RELEASES	329	# dump as number
123	The following API functions (perlapi) are considered for future	330	to_json [2] # yields [2]
124	inclusion in this module If you want them, write me.	331	to_json [-3.0e17] # yields [-3e+17]
		332	my $value = 5; to_json [$value] # yields [5]
125		333
126	sv_upgrade	334	# used as string, so dump as string
127	sv_pvn_force	335	print $value;
128	sv_pvutf8n_force	336	to_json [$value] # yields ["5"]
129	the sv2xx family	337
		338	# undef becomes null
		339	to_json [undef] # yields [null]
		340
		341	You can force the type to be a string by stringifying it:
		342
		343	my $x = 3.1; # some variable containing a number
		344	"$x"; # stringified
		345	$x .= ""; # another, more awkward way to stringify
		346	print $x; # perl does it for you, too, quite often
		347
		348	You can force the type to be a number by numifying it:
		349
		350	my $x = "3"; # some variable containing a string
		351	$x += 0; # numify it, ensuring it will be dumped as a number
		352	$x *= 1; # same thing, the choise is yours.
		353
		354	You can not currently output JSON booleans or force the type in
		355	other, less obscure, ways. Tell me if you need this capability.
		356
		357	circular data structures
		358	Those will be encoded until memory or stackspace runs out.
		359
		360	COMPARISON
		361	As already mentioned, this module was created because none of the
		362	existing JSON modules could be made to work correctly. First I will
		363	describe the problems (or pleasures) I encountered with various existing
		364	JSON modules, followed by some benchmark values. JSON::XS was designed
		365	not to suffer from any of these problems or limitations.
		366
		367	JSON 1.07
		368	Slow (but very portable, as it is written in pure Perl).
		369
		370	Undocumented/buggy Unicode handling (how JSON handles unicode values
		371	is undocumented. One can get far by feeding it unicode strings and
		372	doing en-/decoding oneself, but unicode escapes are not working
		373	properly).
		374
		375	No roundtripping (strings get clobbered if they look like numbers,
		376	e.g. the string 2.0 will encode to 2.0 instead of "2.0", and that
		377	will decode into the number 2.
		378
		379	JSON::PC 0.01
		380	Very fast.
		381
		382	Undocumented/buggy Unicode handling.
		383
		384	No roundtripping.
		385
		386	Has problems handling many Perl values (e.g. regex results and other
		387	magic values will make it croak).
		388
		389	Does not even generate valid JSON ("{1,2}" gets converted to "{1:2}"
		390	which is not a valid JSON string.
		391
		392	Unmaintained (maintainer unresponsive for many months, bugs are not
		393	getting fixed).
		394
		395	JSON::Syck 0.21
		396	Very buggy (often crashes).
		397
		398	Very inflexible (no human-readable format supported, format pretty
		399	much undocumented. I need at least a format for easy reading by
		400	humans and a single-line compact format for use in a protocol, and
		401	preferably a way to generate ASCII-only JSON strings).
		402
		403	Completely broken (and confusingly documented) Unicode handling
		404	(unicode escapes are not working properly, you need to set
		405	ImplicitUnicode to different values on en- and decoding to get
		406	symmetric behaviour).
		407
		408	No roundtripping (simple cases work, but this depends on wether the
		409	scalar value was used in a numeric context or not).
		410
		411	Dumping hashes may skip hash values depending on iterator state.
		412
		413	Unmaintained (maintainer unresponsive for many months, bugs are not
		414	getting fixed).
		415
		416	Does not check input for validity (i.e. will accept non-JSON input
		417	and return "something" instead of raising an exception. This is a
		418	security issue: imagine two banks transfering money between each
		419	other using JSON. One bank might parse a given non-JSON request and
		420	deduct money, while the other might reject the transaction with a
		421	syntax error. While a good protocol will at least recover, that is
		422	extra unnecessary work and the transaction will still not succeed).
		423
		424	JSON::DWIW 0.04
		425	Very fast. Very natural. Very nice.
		426
		427	Undocumented unicode handling (but the best of the pack. Unicode
		428	escapes still don't get parsed properly).
		429
		430	Very inflexible.
		431
		432	No roundtripping.
		433
		434	Does not generate valid JSON (key strings are often unquoted, empty
		435	keys result in nothing being output)
		436
		437	Does not check input for validity.
		438
		439	SPEED
		440	It seems that JSON::XS is surprisingly fast, as shown in the following
		441	tables. They have been generated with the help of the "eg/bench" program
		442	in the JSON::XS distribution, to make it easy to compare on your own
		443	system.
		444
		445	First is a comparison between various modules using a very simple JSON
		446	string, showing the number of encodes/decodes per second (JSON::XS is
		447	the functional interface, while JSON::XS/2 is the OO interface with
		448	pretty-printing and hashkey sorting enabled).
		449
		450	module \| encode \| decode \|
		451	-----------\|------------\|------------\|
		452	JSON \| 14006 \| 6820 \|
		453	JSON::DWIW \| 200937 \| 120386 \|
		454	JSON::PC \| 85065 \| 129366 \|
		455	JSON::Syck \| 59898 \| 44232 \|
		456	JSON::XS \| 1171478 \| 342435 \|
		457	JSON::XS/2 \| 730760 \| 328714 \|
		458	-----------+------------+------------+
		459
		460	That is, JSON::XS is 6 times faster than than JSON::DWIW and about 80
		461	times faster than JSON, even with pretty-printing and key sorting.
		462
		463	Using a longer test string (roughly 8KB, generated from Yahoo! Locals
		464	search API (http://nanoref.com/yahooapis/mgPdGg):
		465
		466	module \| encode \| decode \|
		467	-----------\|------------\|------------\|
		468	JSON \| 673 \| 38 \|
		469	JSON::DWIW \| 5271 \| 770 \|
		470	JSON::PC \| 9901 \| 2491 \|
		471	JSON::Syck \| 2360 \| 786 \|
		472	JSON::XS \| 37398 \| 3202 \|
		473	JSON::XS/2 \| 13765 \| 3153 \|
		474	-----------+------------+------------+
		475
		476	Again, JSON::XS leads by far in the encoding case, while still beating
		477	every other module in the decoding case.
		478
		479	RESOURCE LIMITS
		480	JSON::XS does not impose any limits on the size of JSON texts or Perl
		481	values they represent - if your machine can handle it, JSON::XS will
		482	encode or decode it. Future versions might optionally impose structure
		483	depth and memory use resource limits.
		484
		485	BUGS
		486	While the goal of this module is to be correct, that unfortunately does
		487	not mean its bug-free, only that I think its design is bug-free. It is
		488	still very young and not well-tested. If you keep reporting bugs they
		489	will be fixed swiftly, though.
130		490
131	AUTHOR	491	AUTHOR
132	Marc Lehmann <schmorp@schmorp.de>	492	Marc Lehmann <schmorp@schmorp.de>
133	http://home.schmorp.de/	493	http://home.schmorp.de/
134		494

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.4 by root, Fri Mar 23 18:33:50 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.4 by root, Fri Mar 23 18:33:50 2007 UTC