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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.9 by root, Fri Mar 23 16:00:19 2007 UTC vs.
Revision 1.10 by root, Fri Mar 23 17:40:29 2007 UTC

…		…
18	their maintainers are unresponsive, gone missing, or not listening to bug	18	their maintainers are unresponsive, gone missing, or not listening to bug
19	reports for other reasons.	19	reports for other reasons.
20		20
21	See COMPARISON, below, for a comparison to some other JSON modules.	21	See COMPARISON, below, for a comparison to some other JSON modules.
22		22
		23	See MAPPING, below, on how JSON::XS maps perl values to JSON values and
		24	vice versa.
		25
23	=head2 FEATURES	26	=head2 FEATURES
24		27
25	=over 4	28	=over 4
26		29
27	=item * correct handling of unicode issues	30	=item * correct handling of unicode issues
28		31
29	This module knows how to handle Unicode, and even documents how it does so.	32	This module knows how to handle Unicode, and even documents how and when
		33	it does so.
30		34
31	=item * round-trip integrity	35	=item * round-trip integrity
32		36
33	When you serialise a perl data structure using only datatypes supported	37	When you serialise a perl data structure using only datatypes supported
34	by JSON, the deserialised data structure is identical on the Perl level.	38	by JSON, the deserialised data structure is identical on the Perl level.
35	(e.g. the string "2.0" doesn't suddenly become "2").	39	(e.g. the string "2.0" doesn't suddenly become "2").
36		40
37	=item * strict checking of JSON correctness	41	=item * strict checking of JSON correctness
38		42
39	There is no guessing, no generating of illegal JSON strings by default,	43	There is no guessing, no generating of illegal JSON strings by default,
40	and only JSON is accepted as input (the latter is a security feature).	44	and only JSON is accepted as input by default (the latter is a security
		45	feature).
41		46
42	=item * fast	47	=item * fast
43		48
44	compared to other JSON modules, this module compares favourably.	49	Compared to other JSON modules, this module compares favourably in terms
		50	of speed, too.
45		51
46	=item * simple to use	52	=item * simple to use
47		53
48	This module has both a simple functional interface as well as an OO	54	This module has both a simple functional interface as well as an OO
49	interface.	55	interface.
50		56
51	=item * reasonably versatile output formats	57	=item * reasonably versatile output formats
52		58
53	You can choose between the most compact format possible, a pure-ascii	59	You can choose between the most compact guarenteed single-line format
54	format, or a pretty-printed format. Or you can combine those features in	60	possible (nice for simple line-based protocols), a pure-ascii format (for
		61	when your transport is not 8-bit clean), or a pretty-printed format (for
		62	when you want to read that stuff). Or you can combine those features in
55	whatever way you like.	63	whatever way you like.
56		64
57	=back	65	=back
58		66
59	=cut	67	=cut
…		…
82		90
83	Converts the given Perl data structure (a simple scalar or a reference to	91	Converts the given Perl data structure (a simple scalar or a reference to
84	a hash or array) to a UTF-8 encoded, binary string (that is, the string contains	92	a hash or array) to a UTF-8 encoded, binary string (that is, the string contains
85	octets only). Croaks on error.	93	octets only). Croaks on error.
86		94
87	This function call is functionally identical to C<< JSON::XS->new->utf8	95	This function call is functionally identical to C<< JSON::XS->new->utf8->encode ($perl_scalar) >>.
88	(1)->encode ($perl_scalar) >>.
89		96
90	=item $perl_scalar = from_json $json_string	97	=item $perl_scalar = from_json $json_string
91		98
92	The opposite of C<to_json>: expects an UTF-8 (binary) string and tries to	99	The opposite of C<to_json>: expects an UTF-8 (binary) string and tries to
93	parse that as an UTF-8 encoded JSON string, returning the resulting simple	100	parse that as an UTF-8 encoded JSON string, returning the resulting simple
94	scalar or reference. Croaks on error.	101	scalar or reference. Croaks on error.
95		102
96	This function call is functionally identical to C<< JSON::XS->new->utf8	103	This function call is functionally identical to C<< JSON::XS->new->utf8->decode ($json_string) >>.
97	(1)->decode ($json_string) >>.
98		104
99	=back	105	=back
100		106
101	=head1 OBJECT-ORIENTED INTERFACE	107	=head1 OBJECT-ORIENTED INTERFACE
102		108
…		…
256	returning the resulting simple scalar or reference. Croaks on error.	262	returning the resulting simple scalar or reference. Croaks on error.
257		263
258	JSON numbers and strings become simple Perl scalars. JSON arrays become	264	JSON numbers and strings become simple Perl scalars. JSON arrays become
259	Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes	265	Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
260	C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.	266	C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
		267
		268	=back
		269
		270	=head1 MAPPING
		271
		272	This section describes how JSON::XS maps Perl values to JSON values and
		273	vice versa. These mappings are designed to "do the right thing" in most
		274	circumstances automatically, preserving round-tripping characteristics
		275	(what you put in comes out as something equivalent).
		276
		277	For the more enlightened: note that in the following descriptions,
		278	lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl>
		279	refers to the abstract Perl language itself.
		280
		281	=head2 JSON -> PERL
		282
		283	=over 4
		284
		285	=item object
		286
		287	A JSON object becomes a reference to a hash in Perl. No ordering of object
		288	keys is preserved.
		289
		290	=item array
		291
		292	A JSON array becomes a reference to an array in Perl.
		293
		294	=item string
		295
		296	A JSON string becomes a string scalar in Perl - Unicode codepoints in JSON
		297	are represented by the same codepoints in the Perl string, so no manual
		298	decoding is necessary.
		299
		300	=item number
		301
		302	A JSON number becomes either an integer or numeric (floating point)
		303	scalar in perl, depending on its range and any fractional parts. On the
		304	Perl level, there is no difference between those as Perl handles all the
		305	conversion details, but an integer may take slightly less memory and might
		306	represent more values exactly than (floating point) numbers.
		307
		308	=item true, false
		309
		310	These JSON atoms become C<0>, C<1>, respectively. Information is lost in
		311	this process. Future versions might represent those values differently,
		312	but they will be guarenteed to act like these integers would normally in
		313	Perl.
		314
		315	=item null
		316
		317	A JSON null atom becomes C<undef> in Perl.
		318
		319	=back
		320
		321	=head2 PERL -> JSON
		322
		323	The mapping from Perl to JSON is slightly more difficult, as Perl is a
		324	truly typeless language, so we can only guess which JSON type is meant by
		325	a Perl value.
		326
		327	=over 4
		328
		329	=item hash references
		330
		331	Perl hash references become JSON objects. As there is no inherent ordering
		332	in hash keys, they will usually be encoded in a pseudo-random order that
		333	can change between runs of the same program but stays generally the same
		334	within the single run of a program. JSON::XS can optionally sort the hash
		335	keys (determined by the I<canonical> flag), so the same datastructure
		336	will serialise to the same JSON text (given same settings and version of
		337	JSON::XS), but this incurs a runtime overhead.
		338
		339	=item array references
		340
		341	Perl array references become JSON arrays.
		342
		343	=item blessed objects
		344
		345	Blessed objects are not allowed. JSON::XS currently tries to encode their
		346	underlying representation (hash- or arrayref), but this behaviour might
		347	change in future versions.
		348
		349	=item simple scalars
		350
		351	Simple Perl scalars (any scalar that is not a reference) are the most
		352	difficult objects to encode: JSON::XS will encode undefined scalars as
		353	JSON null value, scalars that have last been used in a string context
		354	before encoding as JSON strings and anything else as number value:
		355
		356	# dump as number
		357	to_json [2] # yields [2]
		358	to_json [-3.0e17] # yields [-3e+17]
		359	my $value = 5; to_json [$value] # yields [5]
		360
		361	# used as string, so dump as string
		362	print $value;
		363	to_json [$value] # yields ["5"]
		364
		365	# undef becomes null
		366	to_json [undef] # yields [null]
		367
		368	You can force the type to be a string by stringifying it:
		369
		370	my $x = 3.1; # some variable containing a number
		371	"$x"; # stringified
		372	$x .= ""; # another, more awkward way to stringify
		373	print $x; # perl does it for you, too, quite often
		374
		375	You can force the type to be a number by numifying it:
		376
		377	my $x = "3"; # some variable containing a string
		378	$x += 0; # numify it, ensuring it will be dumped as a number
		379	$x *= 1; # same thing, the choise is yours.
		380
		381	You can not currently output JSON booleans or force the type in other,
		382	less obscure, ways. Tell me if you need this capability.
261		383
262	=back	384	=back
263		385
264	=head1 COMPARISON	386	=head1 COMPARISON
265		387

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.9 by root, Fri Mar 23 16:00:19 2007 UTC vs. Revision 1.10 by root, Fri Mar 23 17:40:29 2007 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.9 by root, Fri Mar 23 16:00:19 2007 UTC vs.
Revision 1.10 by root, Fri Mar 23 17:40:29 2007 UTC