… | |
… | |
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 | |
… | |
… | |
256 | returning the resulting simple scalar or reference. Croaks on error. |
262 | returning the resulting simple scalar or reference. Croaks on error. |
257 | |
263 | |
258 | JSON numbers and strings become simple Perl scalars. JSON arrays become |
264 | JSON numbers and strings become simple Perl scalars. JSON arrays become |
259 | Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes |
265 | Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes |
260 | 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. |
261 | |
383 | |
262 | =back |
384 | =back |
263 | |
385 | |
264 | =head1 COMPARISON |
386 | =head1 COMPARISON |
265 | |
387 | |