|
|
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 | |
9 | # exported functions, they croak on error |
14 | # exported functions, they croak on error |
10 | # and expect/generate UTF-8 |
15 | # and expect/generate UTF-8 |
11 | |
16 | |
12 | $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; |
17 | $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; |
13 | $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; |
18 | $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; |
14 | |
|
|
15 | # objToJson and jsonToObj aliases to to_json and from_json |
|
|
16 | # are exported for compatibility to the JSON module, |
|
|
17 | # but should not be used in new code. |
|
|
18 | |
19 | |
19 | # OO-interface |
20 | # OO-interface |
20 | |
21 | |
21 | $coder = JSON::XS->new->ascii->pretty->allow_nonref; |
22 | $coder = JSON::XS->new->ascii->pretty->allow_nonref; |
22 | $pretty_printed_unencoded = $coder->encode ($perl_scalar); |
23 | $pretty_printed_unencoded = $coder->encode ($perl_scalar); |
… | |
… | |
85 | |
86 | |
86 | package JSON::XS; |
87 | package JSON::XS; |
87 | |
88 | |
88 | use strict; |
89 | use strict; |
89 | |
90 | |
90 | our $VERSION = '1.4'; |
91 | our $VERSION = '1.5'; |
91 | our @ISA = qw(Exporter); |
92 | our @ISA = qw(Exporter); |
92 | |
93 | |
93 | our @EXPORT = qw(to_json from_json objToJson jsonToObj); |
94 | our @EXPORT = qw(to_json from_json); |
94 | |
95 | |
95 | use Exporter; |
96 | use Exporter; |
96 | use XSLoader; |
97 | use XSLoader; |
97 | |
98 | |
98 | =head1 FUNCTIONAL INTERFACE |
99 | =head1 FUNCTIONAL INTERFACE |
… | |
… | |
282 | |
283 | |
283 | Example, space_before and indent disabled, space_after enabled: |
284 | Example, space_before and indent disabled, space_after enabled: |
284 | |
285 | |
285 | {"key": "value"} |
286 | {"key": "value"} |
286 | |
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 |
|
|
332 | |
287 | =item $json = $json->canonical ([$enable]) |
333 | =item $json = $json->canonical ([$enable]) |
288 | |
334 | |
289 | 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 |
290 | by sorting their keys. This is adding a comparatively high overhead. |
336 | by sorting their keys. This is adding a comparatively high overhead. |
291 | |
337 | |
… | |
… | |
351 | future, global hooks might get installed that influence C<decode> and are |
397 | future, global hooks might get installed that influence C<decode> and are |
352 | enabled by this setting. |
398 | enabled by this setting. |
353 | |
399 | |
354 | If C<$enable> is false, then the C<allow_blessed> setting will decide what |
400 | If C<$enable> is false, then the C<allow_blessed> setting will decide what |
355 | to do when a blessed object is found. |
401 | to do when a blessed object is found. |
|
|
402 | |
|
|
403 | =item $json = $json->filter_json_object ([$coderef->($hashref)]) |
|
|
404 | |
|
|
405 | When C<$coderef> is specified, it will be called from C<decode> each |
|
|
406 | time it decodes a JSON object. The only argument is a reference to the |
|
|
407 | newly-created hash. If the code references returns a single scalar (which |
|
|
408 | need not be a reference), this value (i.e. a copy of that scalar to avoid |
|
|
409 | aliasing) is inserted into the deserialised data structure. If it returns |
|
|
410 | an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the |
|
|
411 | original deserialised hash will be inserted. This setting can slow down |
|
|
412 | decoding considerably. |
|
|
413 | |
|
|
414 | When C<$coderef> is omitted or undefined, any existing callback will |
|
|
415 | be removed and C<decode> will not change the deserialised hash in any |
|
|
416 | way. |
|
|
417 | |
|
|
418 | Example, convert all JSON objects into the integer 5: |
|
|
419 | |
|
|
420 | my $js = JSON::XS->new->filter_json_object (sub { 5 }); |
|
|
421 | # returns [5] |
|
|
422 | $js->decode ('[{}]') |
|
|
423 | # throw an exception because allow_nonref is not enabled |
|
|
424 | # so a lone 5 is not allowed. |
|
|
425 | $js->decode ('{"a":1, "b":2}'); |
|
|
426 | |
|
|
427 | =item $json = $json->filter_json_single_key_object ($key [=> $coderef->($value)]) |
|
|
428 | |
|
|
429 | Works remotely similar to C<filter_json_object>, but is only called for |
|
|
430 | JSON objects having a single key named C<$key>. |
|
|
431 | |
|
|
432 | This C<$coderef> is called before the one specified via |
|
|
433 | C<filter_json_object>, if any. It gets passed the single value in the JSON |
|
|
434 | object. If it returns a single value, it will be inserted into the data |
|
|
435 | structure. If it returns nothing (not even C<undef> but the empty list), |
|
|
436 | the callback from C<filter_json_object> will be called next, as if no |
|
|
437 | single-key callback were specified. |
|
|
438 | |
|
|
439 | If C<$coderef> is omitted or undefined, the corresponding callback will be |
|
|
440 | disabled. There can only ever be one callback for a given key. |
|
|
441 | |
|
|
442 | As this callback gets called less often then the C<filter_json_object> |
|
|
443 | one, decoding speed will not usually suffer as much. Therefore, single-key |
|
|
444 | objects make excellent targets to serialise Perl objects into, especially |
|
|
445 | as single-key JSON objects are as close to the type-tagged value concept |
|
|
446 | as JSON gets (its basically an ID/VALUE tuple). Of course, JSON does not |
|
|
447 | support this in any way, so you need to make sure your data never looks |
|
|
448 | like a serialised Perl hash. |
|
|
449 | |
|
|
450 | Typical names for the single object key are C<__class_whatever__>, or |
|
|
451 | C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even |
|
|
452 | things like C<__class_md5sum(classname)__>, to reduce the risk of clashing |
|
|
453 | with real hashes. |
|
|
454 | |
|
|
455 | Example, decode JSON objects of the form C<< { "__widget__" => <id> } >> |
|
|
456 | into the corresponding C<< $WIDGET{<id>} >> object: |
|
|
457 | |
|
|
458 | # return whatever is in $WIDGET{5}: |
|
|
459 | JSON::XS |
|
|
460 | ->new |
|
|
461 | ->filter_json_single_key_object (__widget__ => sub { |
|
|
462 | $WIDGET{ $_[0] } |
|
|
463 | }) |
|
|
464 | ->decode ('{"__widget__": 5') |
|
|
465 | |
|
|
466 | # this can be used with a TO_JSON method in some "widget" class |
|
|
467 | # for serialisation to json: |
|
|
468 | sub WidgetBase::TO_JSON { |
|
|
469 | my ($self) = @_; |
|
|
470 | |
|
|
471 | unless ($self->{id}) { |
|
|
472 | $self->{id} = ..get..some..id..; |
|
|
473 | $WIDGET{$self->{id}} = $self; |
|
|
474 | } |
|
|
475 | |
|
|
476 | { __widget__ => $self->{id} } |
|
|
477 | } |
356 | |
478 | |
357 | =item $json = $json->shrink ([$enable]) |
479 | =item $json = $json->shrink ([$enable]) |
358 | |
480 | |
359 | Perl usually over-allocates memory a bit when allocating space for |
481 | Perl usually over-allocates memory a bit when allocating space for |
360 | strings. This flag optionally resizes strings generated by either |
482 | strings. This flag optionally resizes strings generated by either |
… | |
… | |
481 | 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 |
482 | decoding is necessary. |
604 | decoding is necessary. |
483 | |
605 | |
484 | =item number |
606 | =item number |
485 | |
607 | |
486 | A JSON number becomes either an integer or numeric (floating point) |
608 | A JSON number becomes either an integer, numeric (floating point) or |
487 | 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 |
488 | 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 |
489 | 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 |
490 | 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. |
491 | |
625 | |
492 | =item true, false |
626 | =item true, false |
493 | |
627 | |
494 | 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>, |
495 | respectively. They are overloaded to act almost exactly like the numbers |
629 | respectively. They are overloaded to act almost exactly like the numbers |
… | |
… | |
537 | to_json [\0,JSON::XS::true] # yields [false,true] |
671 | to_json [\0,JSON::XS::true] # yields [false,true] |
538 | |
672 | |
539 | =item JSON::XS::true, JSON::XS::false |
673 | =item JSON::XS::true, JSON::XS::false |
540 | |
674 | |
541 | These special values become JSON true and JSON false values, |
675 | These special values become JSON true and JSON false values, |
542 | 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. |
543 | |
677 | |
544 | =item blessed objects |
678 | =item blessed objects |
545 | |
679 | |
546 | 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 |
547 | underlying representation (hash- or arrayref), but this behaviour might |
681 | underlying representation (hash- or arrayref), but this behaviour might |