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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.1 by root, Thu Mar 22 16:40:16 2007 UTC vs.
Revision 1.2 by root, Thu Mar 22 17:28:50 2007 UTC

…		…
6		6
7	use JSON::XS;	7	use JSON::XS;
8		8
9	=head1 DESCRIPTION	9	=head1 DESCRIPTION
10		10
		11	This module converts Perl data structures to JSON and vice versa. Its
		12	primary goal is to be I<correct> and its secondary goal is to be
		13	I<fast>. To reach the latter goal it was written in C.
		14
		15	As this is the n-th-something JSON module on CPAN, what was the reason
		16	to write yet another JSON module? While it seems there are many JSON
		17	modules, none of them correctly handle all corner cases, and in most cases
		18	their maintainers are unresponsive, gone missing, or not listening to bug
		19	reports for other reasons.
		20
		21	See COMPARISON, below, for a comparison to some other JSON modules.
		22
		23	=head2 FEATURES
		24
11	=over 4	25	=over 4
		26
		27	=item * correct handling of unicode issues
		28
		29	This module knows how to handle Unicode, and even documents how it does so.
		30
		31	=item * round-trip integrity
		32
		33	When you serialise a perl data structure using only datatypes supported
		34	by JSON, the deserialised data structure is identical on the Perl level.
		35	(e.g. the string "2.0" doesn't suddenly become "2").
		36
		37	=item * strict checking of JSON correctness
		38
		39	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).
		41
		42	=item * fast
		43
		44	compared to other JSON modules, this module compares favourably.
		45
		46	=item * simple to use
		47
		48	This module has both a simple functional interface as well as an OO
		49	interface.
		50
		51	=item * reasonably versatile output formats
		52
		53	You can choose between the most compact format possible, a pure-ascii
		54	format, or a pretty-printed format. Or you can combine those features in
		55	whatever way you like.
		56
		57	=back
12		58
13	=cut	59	=cut
14		60
15	package JSON::XS;	61	package JSON::XS;
16		62
17	BEGIN {	63	BEGIN {
18	$VERSION = '0.1';	64	$VERSION = '0.1';
19	@ISA = qw(Exporter);	65	@ISA = qw(Exporter);
20		66
		67	@EXPORT = qw(to_json from_json);
21	require Exporter;	68	require Exporter;
22		69
23	require XSLoader;	70	require XSLoader;
24	XSLoader::load JSON::XS::, $VERSION;	71	XSLoader::load JSON::XS::, $VERSION;
25	}	72	}
26		73
27	=item	74	=head1 FUNCTIONAL INTERFACE
		75
		76	The following convinience methods are provided by this module. They are
		77	exported by default:
		78
		79	=over 4
		80
		81	=item $json_string = to_json $perl_scalar
		82
		83	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
		85	octets only). Croaks on error.
		86
		87	This function call is functionally identical to C<< JSON::XS->new->utf8
		88	(1)->encode ($perl_scalar) >>.
		89
		90	=item $perl_scalar = from_json $json_string
		91
		92	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
		94	scalar or reference. Croaks on error.
		95
		96	This function call is functionally identical to C<< JSON::XS->new->utf8
		97	(1)->decode ($json_string) >>.
		98
		99	=back
		100
		101	=head1 OBJECT-ORIENTED INTERFACE
		102
		103	The object oriented interface lets you configure your own encoding or
		104	decoding style, within the limits of supported formats.
		105
		106	=over 4
		107
		108	=item $json = new JSON::XS
		109
		110	Creates a new JSON::XS object that can be used to de/encode JSON
		111	strings. All boolean flags described below are by default I<disabled>.
		112
		113	The mutators for flags all return the JSON object again and thus calls can
		114	be chained:
		115
		116	my $json = JSON::XS->new->utf8(1)->pretty(1)->encode ({a => [1,2]})
		117	=> {"a" : [1, 2]}
		118
		119	=item $json = $json->ascii ($enable)
		120
		121	If C<$enable> is true, then the C<encode> method will not generate
		122	characters outside the code range C<0..127>. Any unicode characters
		123	outside that range will be escaped using either a single \uXXXX (BMP
		124	characters) or a double \uHHHH\uLLLLL escape sequence, as per RFC4627.
		125
		126	If C<$enable> is false, then the C<encode> method will not escape Unicode
		127	characters unless necessary.
		128
		129	=item $json = $json->utf8 ($enable)
		130
		131	If C<$enable> is true, then the C<encode> method will encode the JSON
		132	string into UTF-8, as required by many protocols, while the C<decode>
		133	method expects to be handled an UTF-8-encoded string. Please note that
		134	UTF-8-encoded strings do not contain any characters outside the range
		135	C<0..255>, they are thus useful for bytewise/binary I/O.
		136
		137	If C<$enable> is false, then the C<encode> method will return the JSON
		138	string as a (non-encoded) unicode string, while C<decode> expects thus a
		139	unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
		140	to be done yourself, e.g. using the Encode module.
		141
		142	=item $json = $json->pretty ($enabla)
		143
		144	This enables (or disables) all of the C<indent>, C<space_before> and
		145	C<space_after> (and in the future possibly more) settings in one call to
		146	generate the most readable (or most compact) form possible.
		147
		148	=item $json = $json->indent ($enable)
		149
		150	If C<$enable> is true, then the C<encode> method will use a multiline
		151	format as output, putting every array member or object/hash key-value pair
		152	into its own line, identing them properly.
		153
		154	If C<$enable> is false, no newlines or indenting will be produced, and the
		155	resulting JSON strings is guarenteed not to contain any C<newlines>.
		156
		157	This setting has no effect when decoding JSON strings.
		158
		159	=item $json = $json->space_before ($enable)
		160
		161	If C<$enable> is true, then the C<encode> method will add an extra
		162	optional space before the C<:> separating keys from values in JSON objects.
		163
		164	If C<$enable> is false, then the C<encode> method will not add any extra
		165	space at those places.
		166
		167	This setting has no effect when decoding JSON strings. You will also most
		168	likely combine this setting with C<space_after>.
		169
		170	=item $json = $json->space_after ($enable)
		171
		172	If C<$enable> is true, then the C<encode> method will add an extra
		173	optional space after the C<:> separating keys from values in JSON objects
		174	and extra whitespace after the C<,> separating key-value pairs and array
		175	members.
		176
		177	If C<$enable> is false, then the C<encode> method will not add any extra
		178	space at those places.
		179
		180	This setting has no effect when decoding JSON strings.
		181
		182	=item $json = $json->canonical ($enable)
		183
		184	If C<$enable> is true, then the C<encode> method will output JSON objects
		185	by sorting their keys. This is adding a comparatively high overhead.
		186
		187	If C<$enable> is false, then the C<encode> method will output key-value
		188	pairs in the order Perl stores them (which will likely change between runs
		189	of the same script).
		190
		191	This option is useful if you want the same data structure to be encoded as
		192	the same JSON string (given the same overall settings). If it is disabled,
		193	the same hash migh be encoded differently even if contains the same data,
		194	as key-value pairs have no inherent ordering in Perl.
		195
		196	This setting has no effect when decoding JSON strings.
		197
		198	=item $json_string = $json->encode ($perl_scalar)
		199
		200	Converts the given Perl data structure (a simple scalar or a reference
		201	to a hash or array) to its JSON representation. Simple scalars will be
		202	converted into JSON string or number sequences, while references to arrays
		203	become JSON arrays and references to hashes become JSON objects. Undefined
		204	Perl values (e.g. C<undef>) become JSON C<null> values. Neither C<true>
		205	nor C<false> values will be generated.
		206
		207	=item $perl_scalar = $json->decode ($json_string)
		208
		209	The opposite of C<encode>: expects a JSON string and tries to parse it,
		210	returning the resulting simple scalar or reference. Croaks on error.
		211
		212	JSON numbers and strings become simple Perl scalars. JSON arrays become
		213	Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
		214	C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
		215
		216	=back
28		217
29	=cut	218	=cut
30		219
31	use JSON::DWIW;
32	use Benchmark;
33
34	use utf8;
35	#my $json = '{"ü":1,"a":[1,{"3":4},2],"b":5,"üü":2}';
36	my $json = '{"test":9555555555555555555,"hu" : -1e+5, "arr" : [ 1,2,3,4,5]}';
37
38	my $js = JSON::XS->new;
39	warn $js->indent (0);
40	warn $js->canonical (0);
41	warn $js->ascii (0);
42	warn $js->space_after (0);
43	use Data::Dumper;
44	warn Dumper $js->decode ($json);
45	warn Dumper $js->encode ($js->decode ($json));
46	#my $x = {"üü" => 2, "ü" => 1, "a" => [1,{3,4},2], b => 5};
47
48	#my $js2 = JSON::DWIW->new;
49	#
50	#timethese 200000, {
51	# a => sub { $js->encode ($x) },
52	# b => sub { $js2->to_json ($x) },
53	#};
54
55	1;	220	1;
56
57	=back
58		221
59	=head1 AUTHOR	222	=head1 AUTHOR
60		223
61	Marc Lehmann <schmorp@schmorp.de>	224	Marc Lehmann <schmorp@schmorp.de>
62	http://home.schmorp.de/	225	http://home.schmorp.de/

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.1 by root, Thu Mar 22 16:40:16 2007 UTC vs. Revision 1.2 by root, Thu Mar 22 17:28:50 2007 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.1 by root, Thu Mar 22 16:40:16 2007 UTC vs.
Revision 1.2 by root, Thu Mar 22 17:28:50 2007 UTC