JSON-XS/XS.pm

=head1 NAME

JSON::XS - JSON serialising/deserialising, done correctly and fast

=head1 SYNOPSIS

 use JSON::XS;

=head1 DESCRIPTION

This module converts Perl data structures to JSON and vice versa. Its
primary goal is to be I<correct> and its secondary goal is to be
I<fast>. To reach the latter goal it was written in C.

As this is the n-th-something JSON module on CPAN, what was the reason
to write yet another JSON module? While it seems there are many JSON
modules, none of them correctly handle all corner cases, and in most cases
their maintainers are unresponsive, gone missing, or not listening to bug
reports for other reasons.

See COMPARISON, below, for a comparison to some other JSON modules.

=head2 FEATURES

=over 4

=item * correct handling of unicode issues

This module knows how to handle Unicode, and even documents how it does so.

=item * round-trip integrity

When you serialise a perl data structure using only datatypes supported
by JSON, the deserialised data structure is identical on the Perl level.
(e.g. the string "2.0" doesn't suddenly become "2").

=item * strict checking of JSON correctness

There is no guessing, no generating of illegal JSON strings by default,
and only JSON is accepted as input (the latter is a security feature).

=item * fast

compared to other JSON modules, this module compares favourably.

=item * simple to use

This module has both a simple functional interface as well as an OO
interface.

=item * reasonably versatile output formats

You can choose between the most compact format possible, a pure-ascii
format, or a pretty-printed format. Or you can combine those features in
whatever way you like.

=back

=cut

package JSON::XS;

BEGIN {
   $VERSION = '0.1';
   @ISA = qw(Exporter);

   @EXPORT = qw(to_json from_json);
   require Exporter;

   require XSLoader;
   XSLoader::load JSON::XS::, $VERSION;
}

=head1 FUNCTIONAL INTERFACE

The following convinience methods are provided by this module. They are
exported by default:

=over 4

=item $json_string = to_json $perl_scalar

Converts the given Perl data structure (a simple scalar or a reference to
a hash or array) to a UTF-8 encoded, binary string (that is, the string contains
octets only). Croaks on error.

This function call is functionally identical to C<< JSON::XS->new->utf8
(1)->encode ($perl_scalar) >>.

=item $perl_scalar = from_json $json_string

The opposite of C<to_json>: expects an UTF-8 (binary) string and tries to
parse that as an UTF-8 encoded JSON string, returning the resulting simple
scalar or reference. Croaks on error.

This function call is functionally identical to C<< JSON::XS->new->utf8
(1)->decode ($json_string) >>.

=back

=head1 OBJECT-ORIENTED INTERFACE

The object oriented interface lets you configure your own encoding or
decoding style, within the limits of supported formats.

=over 4

=item $json = new JSON::XS

Creates a new JSON::XS object that can be used to de/encode JSON
strings. All boolean flags described below are by default I<disabled>.

The mutators for flags all return the JSON object again and thus calls can
be chained:

   my $json = JSON::XS->new->utf8(1)->pretty(1)->encode ({a => [1,2]})
   => {"a" : [1, 2]}

=item $json = $json->ascii ($enable)

If C<$enable> is true, then the C<encode> method will not generate
characters outside the code range C<0..127>. Any unicode characters
outside that range will be escaped using either a single \uXXXX (BMP
characters) or a double \uHHHH\uLLLLL escape sequence, as per RFC4627.

If C<$enable> is false, then the C<encode> method will not escape Unicode
characters unless necessary.

=item $json = $json->utf8 ($enable)

If C<$enable> is true, then the C<encode> method will encode the JSON
string into UTF-8, as required by many protocols, while the C<decode>
method expects to be handled an UTF-8-encoded string.  Please note that
UTF-8-encoded strings do not contain any characters outside the range
C<0..255>, they are thus useful for bytewise/binary I/O.

If C<$enable> is false, then the C<encode> method will return the JSON
string as a (non-encoded) unicode string, while C<decode> expects thus a
unicode string.  Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
to be done yourself, e.g. using the Encode module.

=item $json = $json->pretty ($enabla)

This enables (or disables) all of the C<indent>, C<space_before> and
C<space_after> (and in the future possibly more) settings in one call to
generate the most readable (or most compact) form possible.

=item $json = $json->indent ($enable)

If C<$enable> is true, then the C<encode> method will use a multiline
format as output, putting every array member or object/hash key-value pair
into its own line, identing them properly.

If C<$enable> is false, no newlines or indenting will be produced, and the
resulting JSON strings is guarenteed not to contain any C<newlines>.

This setting has no effect when decoding JSON strings.

=item $json = $json->space_before ($enable)

If C<$enable> is true, then the C<encode> method will add an extra
optional space before the C<:> separating keys from values in JSON objects.

If C<$enable> is false, then the C<encode> method will not add any extra
space at those places.

This setting has no effect when decoding JSON strings. You will also most
likely combine this setting with C<space_after>.

=item $json = $json->space_after ($enable)

If C<$enable> is true, then the C<encode> method will add an extra
optional space after the C<:> separating keys from values in JSON objects
and extra whitespace after the C<,> separating key-value pairs and array
members.

If C<$enable> is false, then the C<encode> method will not add any extra
space at those places.

This setting has no effect when decoding JSON strings.

=item $json = $json->canonical ($enable)

If C<$enable> is true, then the C<encode> method will output JSON objects
by sorting their keys. This is adding a comparatively high overhead.

If C<$enable> is false, then the C<encode> method will output key-value
pairs in the order Perl stores them (which will likely change between runs
of the same script).

This option is useful if you want the same data structure to be encoded as
the same JSON string (given the same overall settings). If it is disabled,
the same hash migh be encoded differently even if contains the same data,
as key-value pairs have no inherent ordering in Perl.

This setting has no effect when decoding JSON strings.

=item $json_string = $json->encode ($perl_scalar)

Converts the given Perl data structure (a simple scalar or a reference
to a hash or array) to its JSON representation. Simple scalars will be
converted into JSON string or number sequences, while references to arrays
become JSON arrays and references to hashes become JSON objects. Undefined
Perl values (e.g. C<undef>) become JSON C<null> values. Neither C<true>
nor C<false> values will be generated.

=item $perl_scalar = $json->decode ($json_string)

The opposite of C<encode>: expects a JSON string and tries to parse it,
returning the resulting simple scalar or reference. Croaks on error.

JSON numbers and strings become simple Perl scalars. JSON arrays become
Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.

=back

=cut

1;

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

Revision:	1.2
Committed:	Thu Mar 22 17:28:50 2007 UTC (17 years, 2 months ago) by root
Branch:	MAIN
Changes since 1.1:	+188 -25 lines
Log Message:	added preliminary documentation
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3			JSON::XS - JSON serialising/deserialising, done correctly and fast
4
5			=head1 SYNOPSIS
6
7			use JSON::XS;
8
9			=head1 DESCRIPTION
10
11	root	1.2	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
25	root	1.1	=over 4
26
27	root	1.2	=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
58
59	root	1.1	=cut
60
61			package JSON::XS;
62
63			BEGIN {
64			$VERSION = '0.1';
65			@ISA = qw(Exporter);
66
67	root	1.2	@EXPORT = qw(to_json from_json);
68	root	1.1	require Exporter;
69
70			require XSLoader;
71			XSLoader::load JSON::XS::, $VERSION;
72			}
73
74	root	1.2	=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	root	1.1
113	root	1.2	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	root	1.1
207	root	1.2	=item $perl_scalar = $json->decode ($json_string)
208	root	1.1
209	root	1.2	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	root	1.1
212	root	1.2	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	root	1.1
216			=back
217
218	root	1.2	=cut
219
220			1;
221
222	root	1.1	=head1 AUTHOR
223
224			Marc Lehmann <schmorp@schmorp.de>
225			http://home.schmorp.de/
226
227			=cut
228