|
|
1 | =encoding utf-8 |
|
|
2 | |
1 | =head1 NAME |
3 | =head1 NAME |
2 | |
4 | |
3 | JSON::XS - JSON serialising/deserialising, done correctly and fast |
5 | JSON::XS - JSON serialising/deserialising, done correctly and fast |
|
|
6 | |
|
|
7 | JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ |
|
|
8 | (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html) |
4 | |
9 | |
5 | =head1 SYNOPSIS |
10 | =head1 SYNOPSIS |
6 | |
11 | |
7 | use JSON::XS; |
12 | use JSON::XS; |
8 | |
13 | |
… | |
… | |
81 | |
86 | |
82 | package JSON::XS; |
87 | package JSON::XS; |
83 | |
88 | |
84 | use strict; |
89 | use strict; |
85 | |
90 | |
86 | our $VERSION = '1.4'; |
91 | our $VERSION = '1.5'; |
87 | our @ISA = qw(Exporter); |
92 | our @ISA = qw(Exporter); |
88 | |
93 | |
89 | our @EXPORT = qw(to_json from_json); |
94 | our @EXPORT = qw(to_json from_json); |
90 | |
95 | |
91 | use Exporter; |
96 | use Exporter; |
… | |
… | |
277 | This setting has no effect when decoding JSON texts. |
282 | This setting has no effect when decoding JSON texts. |
278 | |
283 | |
279 | Example, space_before and indent disabled, space_after enabled: |
284 | Example, space_before and indent disabled, space_after enabled: |
280 | |
285 | |
281 | {"key": "value"} |
286 | {"key": "value"} |
|
|
287 | |
|
|
288 | =item $json = $json->relaxed ([$enable]) |
|
|
289 | |
|
|
290 | If C<$enable> is true (or missing), then C<decode> will accept some |
|
|
291 | extensions to normal JSON syntax (see below). C<encode> will not be |
|
|
292 | affected in anyway. I<Be aware that this option makes you accept invalid |
|
|
293 | JSON texts as if they were valid!>. I suggest only to use this option to |
|
|
294 | parse application-specific files written by humans (configuration files, |
|
|
295 | resource files etc.) |
|
|
296 | |
|
|
297 | If C<$enable> is false (the default), then C<decode> will only accept |
|
|
298 | valid JSON texts. |
|
|
299 | |
|
|
300 | Currently accepted extensions are: |
|
|
301 | |
|
|
302 | =over 4 |
|
|
303 | |
|
|
304 | =item * list items can have an end-comma |
|
|
305 | |
|
|
306 | JSON I<separates> array elements and key-value pairs with commas. This |
|
|
307 | can be annoying if you write JSON texts manually and want to be able to |
|
|
308 | quickly append elements, so this extension accepts comma at the end of |
|
|
309 | such items not just between them: |
|
|
310 | |
|
|
311 | [ |
|
|
312 | 1, |
|
|
313 | 2, <- this comma not normally allowed |
|
|
314 | ] |
|
|
315 | { |
|
|
316 | "k1": "v1", |
|
|
317 | "k2": "v2", <- this comma not normally allowed |
|
|
318 | } |
|
|
319 | |
|
|
320 | =item * shell-style '#'-comments |
|
|
321 | |
|
|
322 | Whenever JSON allows whitespace, shell-style comments are additionally |
|
|
323 | allowed. They are terminated by the first carriage-return or line-feed |
|
|
324 | character, after which more white-space and comments are allowed. |
|
|
325 | |
|
|
326 | [ |
|
|
327 | 1, # this comment not allowed in JSON |
|
|
328 | # neither this one... |
|
|
329 | ] |
|
|
330 | |
|
|
331 | =back |
282 | |
332 | |
283 | =item $json = $json->canonical ([$enable]) |
333 | =item $json = $json->canonical ([$enable]) |
284 | |
334 | |
285 | If C<$enable> is true (or missing), then the C<encode> method will output JSON objects |
335 | If C<$enable> is true (or missing), then the C<encode> method will output JSON objects |
286 | by sorting their keys. This is adding a comparatively high overhead. |
336 | by sorting their keys. This is adding a comparatively high overhead. |
… | |
… | |
553 | are represented by the same codepoints in the Perl string, so no manual |
603 | are represented by the same codepoints in the Perl string, so no manual |
554 | decoding is necessary. |
604 | decoding is necessary. |
555 | |
605 | |
556 | =item number |
606 | =item number |
557 | |
607 | |
558 | A JSON number becomes either an integer or numeric (floating point) |
608 | A JSON number becomes either an integer, numeric (floating point) or |
559 | scalar in perl, depending on its range and any fractional parts. On the |
609 | string scalar in perl, depending on its range and any fractional parts. On |
560 | Perl level, there is no difference between those as Perl handles all the |
610 | the Perl level, there is no difference between those as Perl handles all |
561 | conversion details, but an integer may take slightly less memory and might |
611 | the conversion details, but an integer may take slightly less memory and |
562 | represent more values exactly than (floating point) numbers. |
612 | might represent more values exactly than (floating point) numbers. |
|
|
613 | |
|
|
614 | If the number consists of digits only, JSON::XS will try to represent |
|
|
615 | it as an integer value. If that fails, it will try to represent it as |
|
|
616 | a numeric (floating point) value if that is possible without loss of |
|
|
617 | precision. Otherwise it will preserve the number as a string value. |
|
|
618 | |
|
|
619 | Numbers containing a fractional or exponential part will always be |
|
|
620 | represented as numeric (floating point) values, possibly at a loss of |
|
|
621 | precision. |
|
|
622 | |
|
|
623 | This might create round-tripping problems as numbers might become strings, |
|
|
624 | but as Perl is typeless there is no other way to do it. |
563 | |
625 | |
564 | =item true, false |
626 | =item true, false |
565 | |
627 | |
566 | These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>, |
628 | These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>, |
567 | respectively. They are overloaded to act almost exactly like the numbers |
629 | respectively. They are overloaded to act almost exactly like the numbers |
… | |
… | |
609 | to_json [\0,JSON::XS::true] # yields [false,true] |
671 | to_json [\0,JSON::XS::true] # yields [false,true] |
610 | |
672 | |
611 | =item JSON::XS::true, JSON::XS::false |
673 | =item JSON::XS::true, JSON::XS::false |
612 | |
674 | |
613 | These special values become JSON true and JSON false values, |
675 | These special values become JSON true and JSON false values, |
614 | respectively. You cna alos use C<\1> and C<\0> directly if you want. |
676 | respectively. You can also use C<\1> and C<\0> directly if you want. |
615 | |
677 | |
616 | =item blessed objects |
678 | =item blessed objects |
617 | |
679 | |
618 | Blessed objects are not allowed. JSON::XS currently tries to encode their |
680 | Blessed objects are not allowed. JSON::XS currently tries to encode their |
619 | underlying representation (hash- or arrayref), but this behaviour might |
681 | underlying representation (hash- or arrayref), but this behaviour might |