ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/JSON-XS/XS.pm
(Generate patch)

Comparing JSON-XS/XS.pm (file contents):
Revision 1.4 by root, Thu Mar 22 21:13:58 2007 UTC vs.
Revision 1.11 by root, Fri Mar 23 17:48:59 2007 UTC

… …
18their maintainers are unresponsive, gone missing, or not listening to bug 18their maintainers are unresponsive, gone missing, or not listening to bug
19reports for other reasons. 19reports for other reasons.
20 20
21See COMPARISON, below, for a comparison to some other JSON modules. 21See COMPARISON, below, for a comparison to some other JSON modules.
22 22
23See MAPPING, below, on how JSON::XS maps perl values to JSON values and
24vice 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
29This module knows how to handle Unicode, and even documents how it does so. 32This module knows how to handle Unicode, and even documents how and when
33it does so.
30 34
31=item * round-trip integrity 35=item * round-trip integrity
32 36
33When you serialise a perl data structure using only datatypes supported 37When you serialise a perl data structure using only datatypes supported
34by JSON, the deserialised data structure is identical on the Perl level. 38by 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
39There is no guessing, no generating of illegal JSON strings by default, 43There is no guessing, no generating of illegal JSON strings by default,
40and only JSON is accepted as input (the latter is a security feature). 44and only JSON is accepted as input by default (the latter is a security
45feature).
41 46
42=item * fast 47=item * fast
43 48
44compared to other JSON modules, this module compares favourably. 49Compared to other JSON modules, this module compares favourably in terms
50of speed, too.
45 51
46=item * simple to use 52=item * simple to use
47 53
48This module has both a simple functional interface as well as an OO 54This module has both a simple functional interface as well as an OO
49interface. 55interface.
50 56
51=item * reasonably versatile output formats 57=item * reasonably versatile output formats
52 58
53You can choose between the most compact format possible, a pure-ascii 59You can choose between the most compact guarenteed single-line format
54format, or a pretty-printed format. Or you can combine those features in 60possible (nice for simple line-based protocols), a pure-ascii format (for
61when your transport is not 8-bit clean), or a pretty-printed format (for
62when you want to read that stuff). Or you can combine those features in
55whatever way you like. 63whatever way you like.
56 64
57=back 65=back
58 66
59=cut 67=cut
60 68
61package JSON::XS; 69package JSON::XS;
62 70
63BEGIN { 71BEGIN {
64 $VERSION = '0.1'; 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
83Converts the given Perl data structure (a simple scalar or a reference to 91Converts the given Perl data structure (a simple scalar or a reference to
84a hash or array) to a UTF-8 encoded, binary string (that is, the string contains 92a hash or array) to a UTF-8 encoded, binary string (that is, the string contains
85octets only). Croaks on error. 93octets only). Croaks on error.
86 94
87This function call is functionally identical to C<< JSON::XS->new->utf8 95This 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
92The opposite of C<to_json>: expects an UTF-8 (binary) string and tries to 99The opposite of C<to_json>: expects an UTF-8 (binary) string and tries to
93parse that as an UTF-8 encoded JSON string, returning the resulting simple 100parse that as an UTF-8 encoded JSON string, returning the resulting simple
94scalar or reference. Croaks on error. 101scalar or reference. Croaks on error.
95 102
96This function call is functionally identical to C<< JSON::XS->new->utf8 103This 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
… …
114be chained: 120be chained:
115 121
116 my $json = JSON::XS->new->utf8(1)->space_after(1)->encode ({a => [1,2]}) 122 my $json = JSON::XS->new->utf8(1)->space_after(1)->encode ({a => [1,2]})
117 => {"a": [1, 2]} 123 => {"a": [1, 2]}
118 124
119=item $json = $json->ascii ($enable) 125=item $json = $json->ascii ([$enable])
120 126
121If C<$enable> is true, then the C<encode> method will not generate 127If C<$enable> is true (or missing), then the C<encode> method will
122characters outside the code range C<0..127>. Any unicode characters 128not generate characters outside the code range C<0..127>. Any unicode
123outside that range will be escaped using either a single \uXXXX (BMP 129characters outside that range will be escaped using either a single
124characters) or a double \uHHHH\uLLLLL escape sequence, as per RFC4627. 130\uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, as per
131RFC4627.
125 132
126If C<$enable> is false, then the C<encode> method will not escape Unicode 133If C<$enable> is false, then the C<encode> method will not escape Unicode
127characters unless necessary. 134characters unless necessary.
128 135
129 JSON::XS->new->ascii (1)->encode (chr 0x10401) 136 JSON::XS->new->ascii (1)->encode (chr 0x10401)
130 => \ud801\udc01 137 => \ud801\udc01
131 138
132=item $json = $json->utf8 ($enable) 139=item $json = $json->utf8 ([$enable])
133 140
134If C<$enable> is true, then the C<encode> method will encode the JSON 141If C<$enable> is true (or missing), then the C<encode> method will encode
135string into UTF-8, as required by many protocols, while the C<decode> 142the JSON string into UTF-8, as required by many protocols, while the
136method expects to be handled an UTF-8-encoded string. Please note that 143C<decode> method expects to be handled an UTF-8-encoded string. Please
137UTF-8-encoded strings do not contain any characters outside the range 144note that UTF-8-encoded strings do not contain any characters outside the
138C<0..255>, they are thus useful for bytewise/binary I/O. 145range C<0..255>, they are thus useful for bytewise/binary I/O.
139 146
140If C<$enable> is false, then the C<encode> method will return the JSON 147If C<$enable> is false, then the C<encode> method will return the JSON
141string as a (non-encoded) unicode string, while C<decode> expects thus a 148string as a (non-encoded) unicode string, while C<decode> expects thus a
142unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs 149unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
143to be done yourself, e.g. using the Encode module. 150to be done yourself, e.g. using the Encode module.
144 151
145=item $json = $json->pretty ($enable) 152=item $json = $json->pretty ([$enable])
146 153
147This enables (or disables) all of the C<indent>, C<space_before> and 154This enables (or disables) all of the C<indent>, C<space_before> and
148C<space_after> (and in the future possibly more) flags in one call to 155C<space_after> (and in the future possibly more) flags in one call to
149generate the most readable (or most compact) form possible. 156generate the most readable (or most compact) form possible.
150 157
… …
155 1, 162 1,
156 2 163 2
157 ] 164 ]
158 } 165 }
159 166
160=item $json = $json->indent ($enable) 167=item $json = $json->indent ([$enable])
161 168
162If C<$enable> is true, then the C<encode> method will use a multiline 169If C<$enable> is true (or missing), then the C<encode> method will use a multiline
163format as output, putting every array member or object/hash key-value pair 170format as output, putting every array member or object/hash key-value pair
164into its own line, identing them properly. 171into its own line, identing them properly.
165 172
166If C<$enable> is false, no newlines or indenting will be produced, and the 173If C<$enable> is false, no newlines or indenting will be produced, and the
167resulting JSON strings is guarenteed not to contain any C<newlines>. 174resulting JSON strings is guarenteed not to contain any C<newlines>.
168 175
169This setting has no effect when decoding JSON strings. 176This setting has no effect when decoding JSON strings.
170 177
171=item $json = $json->space_before ($enable) 178=item $json = $json->space_before ([$enable])
172 179
173If C<$enable> is true, then the C<encode> method will add an extra 180If C<$enable> is true (or missing), then the C<encode> method will add an extra
174optional space before the C<:> separating keys from values in JSON objects. 181optional space before the C<:> separating keys from values in JSON objects.
175 182
176If C<$enable> is false, then the C<encode> method will not add any extra 183If C<$enable> is false, then the C<encode> method will not add any extra
177space at those places. 184space at those places.
178 185
179This setting has no effect when decoding JSON strings. You will also most 186This setting has no effect when decoding JSON strings. You will also most
180likely combine this setting with C<space_after>. 187likely combine this setting with C<space_after>.
181 188
182=item $json = $json->space_after ($enable) 189=item $json = $json->space_after ([$enable])
183 190
184If C<$enable> is true, then the C<encode> method will add an extra 191If C<$enable> is true (or missing), then the C<encode> method will add an extra
185optional space after the C<:> separating keys from values in JSON objects 192optional space after the C<:> separating keys from values in JSON objects
186and extra whitespace after the C<,> separating key-value pairs and array 193and extra whitespace after the C<,> separating key-value pairs and array
187members. 194members.
188 195
189If C<$enable> is false, then the C<encode> method will not add any extra 196If C<$enable> is false, then the C<encode> method will not add any extra
190space at those places. 197space at those places.
191 198
192This setting has no effect when decoding JSON strings. 199This setting has no effect when decoding JSON strings.
193 200
194=item $json = $json->canonical ($enable) 201=item $json = $json->canonical ([$enable])
195 202
196If C<$enable> is true, then the C<encode> method will output JSON objects 203If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
197by sorting their keys. This is adding a comparatively high overhead. 204by sorting their keys. This is adding a comparatively high overhead.
198 205
199If C<$enable> is false, then the C<encode> method will output key-value 206If C<$enable> is false, then the C<encode> method will output key-value
200pairs in the order Perl stores them (which will likely change between runs 207pairs in the order Perl stores them (which will likely change between runs
201of the same script). 208of the same script).
… …
205the same hash migh be encoded differently even if contains the same data, 212the same hash migh be encoded differently even if contains the same data,
206as key-value pairs have no inherent ordering in Perl. 213as key-value pairs have no inherent ordering in Perl.
207 214
208This setting has no effect when decoding JSON strings. 215This setting has no effect when decoding JSON strings.
209 216
210=item $json = $json->allow_nonref ($enable) 217=item $json = $json->allow_nonref ([$enable])
211 218
212If C<$enable> is true, then the C<encode> method can convert a 219If C<$enable> is true (or missing), then the C<encode> method can convert a
213non-reference into its corresponding string, number or null JSON value, 220non-reference into its corresponding string, number or null JSON value,
214which is an extension to RFC4627. Likewise, C<decode> will accept those JSON 221which is an extension to RFC4627. Likewise, C<decode> will accept those JSON
215values instead of croaking. 222values instead of croaking.
216 223
217If C<$enable> is false, then the C<encode> method will croak if it isn't 224If C<$enable> is false, then the C<encode> method will croak if it isn't
218passed an arrayref or hashref, as JSON strings must either be an object 225passed an arrayref or hashref, as JSON strings must either be an object
219or array. Likewise, C<decode> will croak if given something that is not a 226or array. Likewise, C<decode> will croak if given something that is not a
220JSON object or array. 227JSON object or array.
228
229=item $json = $json->shrink ([$enable])
230
231Perl usually over-allocates memory a bit when allocating space for
232strings. This flag optionally resizes strings generated by either
233C<encode> or C<decode> to their minimum size possible. This can save
234memory when your JSON strings are either very very long or you have many
235short strings. It will also try to downgrade any strings to octet-form
236if possible: perl stores strings internally either in an encoding called
237UTF-X or in octet-form. The latter cannot store everything but uses less
238space in general.
239
240If C<$enable> is true (or missing), the string returned by C<encode> will be shrunk-to-fit,
241while all strings generated by C<decode> will also be shrunk-to-fit.
242
243If C<$enable> is false, then the normal perl allocation algorithms are used.
244If you work with your data, then this is likely to be faster.
245
246In the future, this setting might control other things, such as converting
247strings that look like integers or floats into integers or floats
248internally (there is no difference on the Perl level), saving space.
221 249
222=item $json_string = $json->encode ($perl_scalar) 250=item $json_string = $json->encode ($perl_scalar)
223 251
224Converts the given Perl data structure (a simple scalar or a reference 252Converts the given Perl data structure (a simple scalar or a reference
225to a hash or array) to its JSON representation. Simple scalars will be 253to a hash or array) to its JSON representation. Simple scalars will be
… …
237Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes 265Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
238C<1>, C<false> becomes C<0> and C<null> becomes C<undef>. 266C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
239 267
240=back 268=back
241 269
270=head1 MAPPING
271
272This section describes how JSON::XS maps Perl values to JSON values and
273vice versa. These mappings are designed to "do the right thing" in most
274circumstances automatically, preserving round-tripping characteristics
275(what you put in comes out as something equivalent).
276
277For the more enlightened: note that in the following descriptions,
278lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl>
279refers to the abstract Perl language itself.
280
281=head2 JSON -> PERL
282
283=over 4
284
285=item object
286
287A JSON object becomes a reference to a hash in Perl. No ordering of object
288keys is preserved.
289
290=item array
291
292A JSON array becomes a reference to an array in Perl.
293
294=item string
295
296A JSON string becomes a string scalar in Perl - Unicode codepoints in JSON
297are represented by the same codepoints in the Perl string, so no manual
298decoding is necessary.
299
300=item number
301
302A JSON number becomes either an integer or numeric (floating point)
303scalar in perl, depending on its range and any fractional parts. On the
304Perl level, there is no difference between those as Perl handles all the
305conversion details, but an integer may take slightly less memory and might
306represent more values exactly than (floating point) numbers.
307
308=item true, false
309
310These JSON atoms become C<0>, C<1>, respectively. Information is lost in
311this process. Future versions might represent those values differently,
312but they will be guarenteed to act like these integers would normally in
313Perl.
314
315=item null
316
317A JSON null atom becomes C<undef> in Perl.
318
319=back
320
321=head2 PERL -> JSON
322
323The mapping from Perl to JSON is slightly more difficult, as Perl is a
324truly typeless language, so we can only guess which JSON type is meant by
325a Perl value.
326
327=over 4
328
329=item hash references
330
331Perl hash references become JSON objects. As there is no inherent ordering
332in hash keys, they will usually be encoded in a pseudo-random order that
333can change between runs of the same program but stays generally the same
334within the single run of a program. JSON::XS can optionally sort the hash
335keys (determined by the I<canonical> flag), so the same datastructure
336will serialise to the same JSON text (given same settings and version of
337JSON::XS), but this incurs a runtime overhead.
338
339=item array references
340
341Perl array references become JSON arrays.
342
343=item blessed objects
344
345Blessed objects are not allowed. JSON::XS currently tries to encode their
346underlying representation (hash- or arrayref), but this behaviour might
347change in future versions.
348
349=item simple scalars
350
351Simple Perl scalars (any scalar that is not a reference) are the most
352difficult objects to encode: JSON::XS will encode undefined scalars as
353JSON null value, scalars that have last been used in a string context
354before 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
368You 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
375You 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
381You can not currently output JSON booleans or force the type in other,
382less obscure, ways. Tell me if you need this capability.
383
384=item circular data structures
385
386Those will be encoded until memory or stackspace runs out.
387
388=back
389
242=head1 COMPARISON 390=head1 COMPARISON
243 391
244As already mentioned, this module was created because none of the existing 392As already mentioned, this module was created because none of the existing
245JSON modules could be made to work correctly. First I will describe the 393JSON modules could be made to work correctly. First I will describe the
246problems (or pleasures) I encountered with various existing JSON modules, 394problems (or pleasures) I encountered with various existing JSON modules,
247followed by some benchmark values. JSON::XS was designed not to suffer 395followed by some benchmark values. JSON::XS was designed not to suffer
248from any of these problems or limitations. 396from any of these problems or limitations.
249 397
250=over 4 398=over 4
251 399
252=item JSON 400=item JSON 1.07
253 401
254Slow (but very portable, as it is written in pure Perl). 402Slow (but very portable, as it is written in pure Perl).
255 403
256Undocumented/buggy Unicode handling (how JSON handles unicode values is 404Undocumented/buggy Unicode handling (how JSON handles unicode values is
257undocumented. One can get far by feeding it unicode strings and doing 405undocumented. One can get far by feeding it unicode strings and doing
… …
259 407
260No roundtripping (strings get clobbered if they look like numbers, e.g. 408No roundtripping (strings get clobbered if they look like numbers, e.g.
261the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will 409the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will
262decode into the number 2. 410decode into the number 2.
263 411
264=item JSON::PC 412=item JSON::PC 0.01
265 413
266Very fast. 414Very fast.
267 415
268Undocumented/buggy Unicode handling. 416Undocumented/buggy Unicode handling.
269 417
… …
276which is not a valid JSON string. 424which is not a valid JSON string.
277 425
278Unmaintained (maintainer unresponsive for many months, bugs are not 426Unmaintained (maintainer unresponsive for many months, bugs are not
279getting fixed). 427getting fixed).
280 428
281=item JSON::Syck 429=item JSON::Syck 0.21
282 430
283Very buggy (often crashes). 431Very buggy (often crashes).
284 432
285Very inflexible (no human-readable format supported, format pretty much 433Very inflexible (no human-readable format supported, format pretty much
286undocumented. I need at least a format for easy reading by humans and a 434undocumented. I need at least a format for easy reading by humans and a
… …
305JSON. One bank might parse a given non-JSON request and deduct money, 453JSON. One bank might parse a given non-JSON request and deduct money,
306while the other might reject the transaction with a syntax error. While a 454while the other might reject the transaction with a syntax error. While a
307good protocol will at least recover, that is extra unnecessary work and 455good protocol will at least recover, that is extra unnecessary work and
308the transaction will still not succeed). 456the transaction will still not succeed).
309 457
310=item JSON::DWIW 458=item JSON::DWIW 0.04
311 459
312Very fast. Very natural. Very nice. 460Very fast. Very natural. Very nice.
313 461
314Undocumented unicode handling (but the best of the pack. Unicode escapes 462Undocumented unicode handling (but the best of the pack. Unicode escapes
315still don't get parsed properly). 463still don't get parsed properly).
… …
367every other module in the decoding case. 515every other module in the decoding case.
368 516
369Last example is an almost 8MB large hash with many large binary values 517Last example is an almost 8MB large hash with many large binary values
370(PNG files), resulting in a lot of escaping: 518(PNG files), resulting in a lot of escaping:
371 519
520=head1 RESOURCE LIMITS
521
522JSON::XS does not impose any limits on the size of JSON texts or Perl
523values they represent - if your machine cna handle it, JSON::XS will
524encode or decode it. Future versions might optionally impose structure
525depth and memory use resource limits.
526
372=head1 BUGS 527=head1 BUGS
373 528
374While the goal of this module is to be correct, that unfortunately does 529While the goal of this module is to be correct, that unfortunately does
375not mean its bug-free, only that I think its design is bug-free. It is 530not mean its bug-free, only that I think its design is bug-free. It is
376still very young and not well-tested. If you keep reporting bugs they will 531still very young and not well-tested. If you keep reporting bugs they will

Diff Legend

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