… | |
… | |
10 | use JSON::XS; |
10 | use JSON::XS; |
11 | |
11 | |
12 | # exported functions, they croak on error |
12 | # exported functions, they croak on error |
13 | # and expect/generate UTF-8 |
13 | # and expect/generate UTF-8 |
14 | |
14 | |
15 | $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; |
15 | $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; |
16 | $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; |
16 | $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; |
17 | |
17 | |
18 | # OO-interface |
18 | # OO-interface |
19 | |
19 | |
20 | $coder = JSON::XS->new->ascii->pretty->allow_nonref; |
20 | $coder = JSON::XS->new->ascii->pretty->allow_nonref; |
21 | $pretty_printed_unencoded = $coder->encode ($perl_scalar); |
21 | $pretty_printed_unencoded = $coder->encode ($perl_scalar); |
… | |
… | |
100 | |
100 | |
101 | package JSON::XS; |
101 | package JSON::XS; |
102 | |
102 | |
103 | use strict; |
103 | use strict; |
104 | |
104 | |
105 | our $VERSION = '2.0'; |
105 | our $VERSION = '2.01'; |
106 | our @ISA = qw(Exporter); |
106 | our @ISA = qw(Exporter); |
107 | |
107 | |
108 | our @EXPORT = qw(to_json from_json); |
108 | our @EXPORT = qw(encode_json decode_json to_json from_json); |
|
|
109 | |
|
|
110 | sub to_json($) { |
|
|
111 | require Carp; |
|
|
112 | Carp::croak ("JSON::XS::to_json has been renamed to encode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call"); |
|
|
113 | } |
|
|
114 | |
|
|
115 | sub from_json($) { |
|
|
116 | require Carp; |
|
|
117 | Carp::croak ("JSON::XS::from_json has been renamed to decode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call"); |
|
|
118 | } |
109 | |
119 | |
110 | use Exporter; |
120 | use Exporter; |
111 | use XSLoader; |
121 | use XSLoader; |
112 | |
122 | |
113 | =head1 FUNCTIONAL INTERFACE |
123 | =head1 FUNCTIONAL INTERFACE |
… | |
… | |
115 | The following convenience methods are provided by this module. They are |
125 | The following convenience methods are provided by this module. They are |
116 | exported by default: |
126 | exported by default: |
117 | |
127 | |
118 | =over 4 |
128 | =over 4 |
119 | |
129 | |
120 | =item $json_text = to_json $perl_scalar |
130 | =item $json_text = encode_json $perl_scalar |
121 | |
131 | |
122 | Converts the given Perl data structure to a UTF-8 encoded, binary string |
132 | Converts the given Perl data structure to a UTF-8 encoded, binary string |
123 | (that is, the string contains octets only). Croaks on error. |
133 | (that is, the string contains octets only). Croaks on error. |
124 | |
134 | |
125 | This function call is functionally identical to: |
135 | This function call is functionally identical to: |
126 | |
136 | |
127 | $json_text = JSON::XS->new->utf8->encode ($perl_scalar) |
137 | $json_text = JSON::XS->new->utf8->encode ($perl_scalar) |
128 | |
138 | |
129 | except being faster. |
139 | except being faster. |
130 | |
140 | |
131 | =item $perl_scalar = from_json $json_text |
141 | =item $perl_scalar = decode_json $json_text |
132 | |
142 | |
133 | The opposite of C<to_json>: expects an UTF-8 (binary) string and tries |
143 | The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries |
134 | to parse that as an UTF-8 encoded JSON text, returning the resulting |
144 | to parse that as an UTF-8 encoded JSON text, returning the resulting |
135 | reference. Croaks on error. |
145 | reference. Croaks on error. |
136 | |
146 | |
137 | This function call is functionally identical to: |
147 | This function call is functionally identical to: |
138 | |
148 | |
… | |
… | |
471 | The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON> |
481 | The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON> |
472 | returns other blessed objects, those will be handled in the same |
482 | returns other blessed objects, those will be handled in the same |
473 | way. C<TO_JSON> must take care of not causing an endless recursion cycle |
483 | way. C<TO_JSON> must take care of not causing an endless recursion cycle |
474 | (== crash) in this case. The name of C<TO_JSON> was chosen because other |
484 | (== crash) in this case. The name of C<TO_JSON> was chosen because other |
475 | methods called by the Perl core (== not by the user of the object) are |
485 | methods called by the Perl core (== not by the user of the object) are |
476 | usually in upper case letters and to avoid collisions with the C<to_json> |
486 | usually in upper case letters and to avoid collisions with any C<to_json> |
477 | function. |
487 | function or method. |
478 | |
488 | |
479 | This setting does not yet influence C<decode> in any way, but in the |
489 | This setting does not yet influence C<decode> in any way, but in the |
480 | future, global hooks might get installed that influence C<decode> and are |
490 | future, global hooks might get installed that influence C<decode> and are |
481 | enabled by this setting. |
491 | enabled by this setting. |
482 | |
492 | |
… | |
… | |
755 | Other unblessed references are generally not allowed and will cause an |
765 | Other unblessed references are generally not allowed and will cause an |
756 | exception to be thrown, except for references to the integers C<0> and |
766 | exception to be thrown, except for references to the integers C<0> and |
757 | C<1>, which get turned into C<false> and C<true> atoms in JSON. You can |
767 | C<1>, which get turned into C<false> and C<true> atoms in JSON. You can |
758 | also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability. |
768 | also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability. |
759 | |
769 | |
760 | to_json [\0,JSON::XS::true] # yields [false,true] |
770 | encode_json [\0,JSON::XS::true] # yields [false,true] |
761 | |
771 | |
762 | =item JSON::XS::true, JSON::XS::false |
772 | =item JSON::XS::true, JSON::XS::false |
763 | |
773 | |
764 | These special values become JSON true and JSON false values, |
774 | These special values become JSON true and JSON false values, |
765 | respectively. You can also use C<\1> and C<\0> directly if you want. |
775 | respectively. You can also use C<\1> and C<\0> directly if you want. |
… | |
… | |
776 | difficult objects to encode: JSON::XS will encode undefined scalars as |
786 | difficult objects to encode: JSON::XS will encode undefined scalars as |
777 | JSON null value, scalars that have last been used in a string context |
787 | JSON null value, scalars that have last been used in a string context |
778 | before encoding as JSON strings and anything else as number value: |
788 | before encoding as JSON strings and anything else as number value: |
779 | |
789 | |
780 | # dump as number |
790 | # dump as number |
781 | to_json [2] # yields [2] |
791 | encode_json [2] # yields [2] |
782 | to_json [-3.0e17] # yields [-3e+17] |
792 | encode_json [-3.0e17] # yields [-3e+17] |
783 | my $value = 5; to_json [$value] # yields [5] |
793 | my $value = 5; encode_json [$value] # yields [5] |
784 | |
794 | |
785 | # used as string, so dump as string |
795 | # used as string, so dump as string |
786 | print $value; |
796 | print $value; |
787 | to_json [$value] # yields ["5"] |
797 | encode_json [$value] # yields ["5"] |
788 | |
798 | |
789 | # undef becomes null |
799 | # undef becomes null |
790 | to_json [undef] # yields [null] |
800 | encode_json [undef] # yields [null] |
791 | |
801 | |
792 | You can force the type to be a JSON string by stringifying it: |
802 | You can force the type to be a JSON string by stringifying it: |
793 | |
803 | |
794 | my $x = 3.1; # some variable containing a number |
804 | my $x = 3.1; # some variable containing a number |
795 | "$x"; # stringified |
805 | "$x"; # stringified |
… | |
… | |
895 | =back |
905 | =back |
896 | |
906 | |
897 | |
907 | |
898 | =head2 JSON and YAML |
908 | =head2 JSON and YAML |
899 | |
909 | |
900 | You often hear that JSON is a subset (or a close subset) of YAML. This is, |
910 | You often hear that JSON is a subset of YAML. This is, however, a mass |
901 | however, a mass hysteria and very far from the truth. In general, there is |
911 | hysteria and very far from the truth. In general, there is no way to |
902 | no way to configure JSON::XS to output a data structure as valid YAML. |
912 | configure JSON::XS to output a data structure as valid YAML that works for |
|
|
913 | all cases. |
903 | |
914 | |
904 | If you really must use JSON::XS to generate YAML, you should use this |
915 | If you really must use JSON::XS to generate YAML, you should use this |
905 | algorithm (subject to change in future versions): |
916 | algorithm (subject to change in future versions): |
906 | |
917 | |
907 | my $to_yaml = JSON::XS->new->utf8->space_after (1); |
918 | my $to_yaml = JSON::XS->new->utf8->space_after (1); |
908 | my $yaml = $to_yaml->encode ($ref) . "\n"; |
919 | my $yaml = $to_yaml->encode ($ref) . "\n"; |
909 | |
920 | |
910 | This will usually generate JSON texts that also parse as valid |
921 | This will usually generate JSON texts that also parse as valid |
911 | YAML. Please note that YAML has hardcoded limits on (simple) object key |
922 | YAML. Please note that YAML has hardcoded limits on (simple) object key |
912 | lengths that JSON doesn't have, so you should make sure that your hash |
923 | lengths that JSON doesn't have and also has different and incompatible |
|
|
924 | unicode handling, so you should make sure that your hash keys are |
913 | keys are noticeably shorter than the 1024 characters YAML allows. |
925 | noticeably shorter than the 1024 "stream characters" YAML allows and that |
|
|
926 | you do not have codepoints with values outside the Unicode BMP (basic |
|
|
927 | multilingual page). YAML also does not allow C<\/> sequences in strings |
|
|
928 | (which JSON::XS does not I<currently> generate). |
914 | |
929 | |
915 | There might be other incompatibilities that I am not aware of. In general |
930 | There might be other incompatibilities that I am not aware of. In general |
916 | you should not try to generate YAML with a JSON generator or vice versa, |
931 | you should not try to generate YAML with a JSON generator or vice versa, |
917 | or try to parse JSON with a YAML parser or vice versa: chances are high |
932 | or try to parse JSON with a YAML parser or vice versa: chances are high |
918 | that you will run into severe interoperability problems. |
933 | that you will run into severe interoperability problems when you least |
|
|
934 | expect it. |
919 | |
935 | |
920 | |
936 | |
921 | =head2 SPEED |
937 | =head2 SPEED |
922 | |
938 | |
923 | It seems that JSON::XS is surprisingly fast, as shown in the following |
939 | It seems that JSON::XS is surprisingly fast, as shown in the following |
… | |
… | |
1000 | |
1016 | |
1001 | Third, JSON::XS recurses using the C stack when decoding objects and |
1017 | Third, JSON::XS recurses using the C stack when decoding objects and |
1002 | arrays. The C stack is a limited resource: for instance, on my amd64 |
1018 | arrays. The C stack is a limited resource: for instance, on my amd64 |
1003 | machine with 8MB of stack size I can decode around 180k nested arrays but |
1019 | machine with 8MB of stack size I can decode around 180k nested arrays but |
1004 | only 14k nested JSON objects (due to perl itself recursing deeply on croak |
1020 | only 14k nested JSON objects (due to perl itself recursing deeply on croak |
1005 | to free the temporary). If that is exceeded, the program crashes. to be |
1021 | to free the temporary). If that is exceeded, the program crashes. To be |
1006 | conservative, the default nesting limit is set to 512. If your process |
1022 | conservative, the default nesting limit is set to 512. If your process |
1007 | has a smaller stack, you should adjust this setting accordingly with the |
1023 | has a smaller stack, you should adjust this setting accordingly with the |
1008 | C<max_depth> method. |
1024 | C<max_depth> method. |
1009 | |
1025 | |
1010 | And last but least, something else could bomb you that I forgot to think |
1026 | And last but least, something else could bomb you that I forgot to think |
… | |
… | |
1014 | If you are using JSON::XS to return packets to consumption |
1030 | If you are using JSON::XS to return packets to consumption |
1015 | by JavaScript scripts in a browser you should have a look at |
1031 | by JavaScript scripts in a browser you should have a look at |
1016 | L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether |
1032 | L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether |
1017 | you are vulnerable to some common attack vectors (which really are browser |
1033 | you are vulnerable to some common attack vectors (which really are browser |
1018 | design bugs, but it is still you who will have to deal with it, as major |
1034 | design bugs, but it is still you who will have to deal with it, as major |
1019 | browser developers care only for features, not about doing security |
1035 | browser developers care only for features, not about getting security |
1020 | right). |
1036 | right). |
1021 | |
1037 | |
1022 | |
1038 | |
1023 | =head1 THREADS |
1039 | =head1 THREADS |
1024 | |
1040 | |