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 |
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 |
=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 |
58 |
|
59 |
=cut |
60 |
|
61 |
package JSON::XS; |
62 |
|
63 |
BEGIN { |
64 |
$VERSION = '0.1'; |
65 |
@ISA = qw(Exporter); |
66 |
|
67 |
@EXPORT = qw(to_json from_json); |
68 |
require Exporter; |
69 |
|
70 |
require XSLoader; |
71 |
XSLoader::load JSON::XS::, $VERSION; |
72 |
} |
73 |
|
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 |
217 |
|
218 |
=cut |
219 |
|
220 |
1; |
221 |
|
222 |
=head1 AUTHOR |
223 |
|
224 |
Marc Lehmann <schmorp@schmorp.de> |
225 |
http://home.schmorp.de/ |
226 |
|
227 |
=cut |
228 |
|