… | |
… | |
9 | use JSON::XS; |
9 | use JSON::XS; |
10 | |
10 | |
11 | # exported functions, they croak on error |
11 | # exported functions, they croak on error |
12 | # and expect/generate UTF-8 |
12 | # and expect/generate UTF-8 |
13 | |
13 | |
14 | $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; |
14 | $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; |
15 | $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; |
15 | $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; |
16 | |
16 | |
17 | # OO-interface |
17 | # OO-interface |
18 | |
18 | |
19 | $coder = JSON::XS->new->ascii->pretty->allow_nonref; |
19 | $coder = JSON::XS->new->ascii->pretty->allow_nonref; |
20 | $pretty_printed_unencoded = $coder->encode ($perl_scalar); |
20 | $pretty_printed_unencoded = $coder->encode ($perl_scalar); |
… | |
… | |
86 | |
86 | |
87 | FUNCTIONAL INTERFACE |
87 | FUNCTIONAL INTERFACE |
88 | The following convenience methods are provided by this module. They are |
88 | The following convenience methods are provided by this module. They are |
89 | exported by default: |
89 | exported by default: |
90 | |
90 | |
91 | $json_text = to_json $perl_scalar |
91 | $json_text = encode_json $perl_scalar |
92 | Converts the given Perl data structure to a UTF-8 encoded, binary |
92 | Converts the given Perl data structure to a UTF-8 encoded, binary |
93 | string (that is, the string contains octets only). Croaks on error. |
93 | string (that is, the string contains octets only). Croaks on error. |
94 | |
94 | |
95 | This function call is functionally identical to: |
95 | This function call is functionally identical to: |
96 | |
96 | |
97 | $json_text = JSON::XS->new->utf8->encode ($perl_scalar) |
97 | $json_text = JSON::XS->new->utf8->encode ($perl_scalar) |
98 | |
98 | |
99 | except being faster. |
99 | except being faster. |
100 | |
100 | |
101 | $perl_scalar = from_json $json_text |
101 | $perl_scalar = decode_json $json_text |
102 | The opposite of "to_json": expects an UTF-8 (binary) string and |
102 | The opposite of "encode_json": expects an UTF-8 (binary) string and |
103 | tries to parse that as an UTF-8 encoded JSON text, returning the |
103 | tries to parse that as an UTF-8 encoded JSON text, returning the |
104 | resulting reference. Croaks on error. |
104 | resulting reference. Croaks on error. |
105 | |
105 | |
106 | This function call is functionally identical to: |
106 | This function call is functionally identical to: |
107 | |
107 | |
… | |
… | |
407 | returns other blessed objects, those will be handled in the same |
407 | returns other blessed objects, those will be handled in the same |
408 | way. "TO_JSON" must take care of not causing an endless recursion |
408 | way. "TO_JSON" must take care of not causing an endless recursion |
409 | cycle (== crash) in this case. The name of "TO_JSON" was chosen |
409 | cycle (== crash) in this case. The name of "TO_JSON" was chosen |
410 | because other methods called by the Perl core (== not by the user of |
410 | because other methods called by the Perl core (== not by the user of |
411 | the object) are usually in upper case letters and to avoid |
411 | the object) are usually in upper case letters and to avoid |
412 | collisions with the "to_json" function. |
412 | collisions with any "to_json" function or method. |
413 | |
413 | |
414 | This setting does not yet influence "decode" in any way, but in the |
414 | This setting does not yet influence "decode" in any way, but in the |
415 | future, global hooks might get installed that influence "decode" and |
415 | future, global hooks might get installed that influence "decode" and |
416 | are enabled by this setting. |
416 | are enabled by this setting. |
417 | |
417 | |
… | |
… | |
669 | an exception to be thrown, except for references to the integers 0 |
669 | an exception to be thrown, except for references to the integers 0 |
670 | and 1, which get turned into "false" and "true" atoms in JSON. You |
670 | and 1, which get turned into "false" and "true" atoms in JSON. You |
671 | can also use "JSON::XS::false" and "JSON::XS::true" to improve |
671 | can also use "JSON::XS::false" and "JSON::XS::true" to improve |
672 | readability. |
672 | readability. |
673 | |
673 | |
674 | to_json [\0,JSON::XS::true] # yields [false,true] |
674 | encode_json [\0,JSON::XS::true] # yields [false,true] |
675 | |
675 | |
676 | JSON::XS::true, JSON::XS::false |
676 | JSON::XS::true, JSON::XS::false |
677 | These special values become JSON true and JSON false values, |
677 | These special values become JSON true and JSON false values, |
678 | respectively. You can also use "\1" and "\0" directly if you want. |
678 | respectively. You can also use "\1" and "\0" directly if you want. |
679 | |
679 | |
… | |
… | |
688 | scalars as JSON null value, scalars that have last been used in a |
688 | scalars as JSON null value, scalars that have last been used in a |
689 | string context before encoding as JSON strings and anything else as |
689 | string context before encoding as JSON strings and anything else as |
690 | number value: |
690 | number value: |
691 | |
691 | |
692 | # dump as number |
692 | # dump as number |
693 | to_json [2] # yields [2] |
693 | encode_json [2] # yields [2] |
694 | to_json [-3.0e17] # yields [-3e+17] |
694 | encode_json [-3.0e17] # yields [-3e+17] |
695 | my $value = 5; to_json [$value] # yields [5] |
695 | my $value = 5; encode_json [$value] # yields [5] |
696 | |
696 | |
697 | # used as string, so dump as string |
697 | # used as string, so dump as string |
698 | print $value; |
698 | print $value; |
699 | to_json [$value] # yields ["5"] |
699 | encode_json [$value] # yields ["5"] |
700 | |
700 | |
701 | # undef becomes null |
701 | # undef becomes null |
702 | to_json [undef] # yields [null] |
702 | encode_json [undef] # yields [null] |
703 | |
703 | |
704 | You can force the type to be a JSON string by stringifying it: |
704 | You can force the type to be a JSON string by stringifying it: |
705 | |
705 | |
706 | my $x = 3.1; # some variable containing a number |
706 | my $x = 3.1; # some variable containing a number |
707 | "$x"; # stringified |
707 | "$x"; # stringified |