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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.7 by root, Fri Mar 23 15:10:55 2007 UTC vs.
Revision 1.11 by root, Fri Mar 23 17:48:59 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
60		68
61	package JSON::XS;	69	package JSON::XS;
62		70
63	BEGIN {	71	BEGIN {
64	$VERSION = '0.2';	72	$VERSION = '0.3';
65	@ISA = qw(Exporter);	73	@ISA = qw(Exporter);
66		74
67	@EXPORT = qw(to_json from_json);	75	@EXPORT = qw(to_json from_json);
68	require Exporter;	76	require Exporter;
69		77
…		…
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
…		…
224		230
225	Perl usually over-allocates memory a bit when allocating space for	231	Perl usually over-allocates memory a bit when allocating space for
226	strings. This flag optionally resizes strings generated by either	232	strings. This flag optionally resizes strings generated by either
227	C<encode> or C<decode> to their minimum size possible. This can save	233	C<encode> or C<decode> to their minimum size possible. This can save
228	memory when your JSON strings are either very very long or you have many	234	memory when your JSON strings are either very very long or you have many
229	short strings.	235	short strings. It will also try to downgrade any strings to octet-form
		236	if possible: perl stores strings internally either in an encoding called
		237	UTF-X or in octet-form. The latter cannot store everything but uses less
		238	space in general.
230		239
231	If C<$enable> is true (or missing), the string returned by C<encode> will be shrunk-to-fit,	240	If C<$enable> is true (or missing), the string returned by C<encode> will be shrunk-to-fit,
232	while all strings generated by C<decode> will also be shrunk-to-fit.	241	while all strings generated by C<decode> will also be shrunk-to-fit.
233		242
234	If C<$enable> is false, then the normal perl allocation algorithms are used.	243	If C<$enable> is false, then the normal perl allocation algorithms are used.
…		…
253	returning the resulting simple scalar or reference. Croaks on error.	262	returning the resulting simple scalar or reference. Croaks on error.
254		263
255	JSON numbers and strings become simple Perl scalars. JSON arrays become	264	JSON numbers and strings become simple Perl scalars. JSON arrays become
256	Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes	265	Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
257	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.
		383
		384	=item circular data structures
		385
		386	Those will be encoded until memory or stackspace runs out.
258		387
259	=back	388	=back
260		389
261	=head1 COMPARISON	390	=head1 COMPARISON
262		391
…		…
386	every other module in the decoding case.	515	every other module in the decoding case.
387		516
388	Last example is an almost 8MB large hash with many large binary values	517	Last example is an almost 8MB large hash with many large binary values
389	(PNG files), resulting in a lot of escaping:	518	(PNG files), resulting in a lot of escaping:
390		519
		520	=head1 RESOURCE LIMITS
		521
		522	JSON::XS does not impose any limits on the size of JSON texts or Perl
		523	values they represent - if your machine cna handle it, JSON::XS will
		524	encode or decode it. Future versions might optionally impose structure
		525	depth and memory use resource limits.
		526
391	=head1 BUGS	527	=head1 BUGS
392		528
393	While the goal of this module is to be correct, that unfortunately does	529	While the goal of this module is to be correct, that unfortunately does
394	not mean its bug-free, only that I think its design is bug-free. It is	530	not mean its bug-free, only that I think its design is bug-free. It is
395	still very young and not well-tested. If you keep reporting bugs they will	531	still very young and not well-tested. If you keep reporting bugs they will

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.7 by root, Fri Mar 23 15:10:55 2007 UTC vs. Revision 1.11 by root, Fri Mar 23 17:48:59 2007 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.7 by root, Fri Mar 23 15:10:55 2007 UTC vs.
Revision 1.11 by root, Fri Mar 23 17:48:59 2007 UTC