… | |
… | |
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); |
22 | $perl_scalar = $coder->decode ($unicode_json_text); |
22 | $perl_scalar = $coder->decode ($unicode_json_text); |
23 | |
23 | |
|
|
24 | # Note that JSON version 2.0 and above will automatically use JSON::XS |
|
|
25 | # if available, at virtually no speed overhead either, so you should |
|
|
26 | # be able to just: |
|
|
27 | |
|
|
28 | use JSON; |
|
|
29 | |
|
|
30 | # and do the same things, except that you have a pure-perl fallback now. |
|
|
31 | |
24 | =head1 DESCRIPTION |
32 | =head1 DESCRIPTION |
25 | |
33 | |
26 | This module converts Perl data structures to JSON and vice versa. Its |
34 | This module converts Perl data structures to JSON and vice versa. Its |
27 | primary goal is to be I<correct> and its secondary goal is to be |
35 | primary goal is to be I<correct> and its secondary goal is to be |
28 | I<fast>. To reach the latter goal it was written in C. |
36 | I<fast>. To reach the latter goal it was written in C. |
|
|
37 | |
|
|
38 | Beginning with version 2.0 of the JSON module, when both JSON and |
|
|
39 | JSON::XS are installed, then JSON will fall back on JSON::XS (this can be |
|
|
40 | overriden) with no overhead due to emulation (by inheritign constructor |
|
|
41 | and methods). If JSON::XS is not available, it will fall back to the |
|
|
42 | compatible JSON::PP module as backend, so using JSON instead of JSON::XS |
|
|
43 | gives you a portable JSON API that can be fast when you need and doesn't |
|
|
44 | require a C compiler when that is a problem. |
29 | |
45 | |
30 | As this is the n-th-something JSON module on CPAN, what was the reason |
46 | As this is the n-th-something JSON module on CPAN, what was the reason |
31 | to write yet another JSON module? While it seems there are many JSON |
47 | to write yet another JSON module? While it seems there are many JSON |
32 | modules, none of them correctly handle all corner cases, and in most cases |
48 | modules, none of them correctly handle all corner cases, and in most cases |
33 | their maintainers are unresponsive, gone missing, or not listening to bug |
49 | their maintainers are unresponsive, gone missing, or not listening to bug |
… | |
… | |
84 | |
100 | |
85 | package JSON::XS; |
101 | package JSON::XS; |
86 | |
102 | |
87 | use strict; |
103 | use strict; |
88 | |
104 | |
89 | our $VERSION = '2.0'; |
105 | our $VERSION = '2.01'; |
90 | our @ISA = qw(Exporter); |
106 | our @ISA = qw(Exporter); |
91 | |
107 | |
92 | 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 | } |
93 | |
119 | |
94 | use Exporter; |
120 | use Exporter; |
95 | use XSLoader; |
121 | use XSLoader; |
96 | |
122 | |
97 | =head1 FUNCTIONAL INTERFACE |
123 | =head1 FUNCTIONAL INTERFACE |
… | |
… | |
99 | The following convenience methods are provided by this module. They are |
125 | The following convenience methods are provided by this module. They are |
100 | exported by default: |
126 | exported by default: |
101 | |
127 | |
102 | =over 4 |
128 | =over 4 |
103 | |
129 | |
104 | =item $json_text = to_json $perl_scalar |
130 | =item $json_text = encode_json $perl_scalar |
105 | |
131 | |
106 | 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 |
107 | (that is, the string contains octets only). Croaks on error. |
133 | (that is, the string contains octets only). Croaks on error. |
108 | |
134 | |
109 | This function call is functionally identical to: |
135 | This function call is functionally identical to: |
110 | |
136 | |
111 | $json_text = JSON::XS->new->utf8->encode ($perl_scalar) |
137 | $json_text = JSON::XS->new->utf8->encode ($perl_scalar) |
112 | |
138 | |
113 | except being faster. |
139 | except being faster. |
114 | |
140 | |
115 | =item $perl_scalar = from_json $json_text |
141 | =item $perl_scalar = decode_json $json_text |
116 | |
142 | |
117 | 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 |
118 | 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 |
119 | reference. Croaks on error. |
145 | reference. Croaks on error. |
120 | |
146 | |
121 | This function call is functionally identical to: |
147 | This function call is functionally identical to: |
122 | |
148 | |
… | |
… | |
427 | JSON::XS->new->allow_nonref->encode ("Hello, World!") |
453 | JSON::XS->new->allow_nonref->encode ("Hello, World!") |
428 | => "Hello, World!" |
454 | => "Hello, World!" |
429 | |
455 | |
430 | =item $json = $json->allow_blessed ([$enable]) |
456 | =item $json = $json->allow_blessed ([$enable]) |
431 | |
457 | |
432 | =item $enabled = $json->get_allow_bless |
458 | =item $enabled = $json->get_allow_blessed |
433 | |
459 | |
434 | If C<$enable> is true (or missing), then the C<encode> method will not |
460 | If C<$enable> is true (or missing), then the C<encode> method will not |
435 | barf when it encounters a blessed reference. Instead, the value of the |
461 | barf when it encounters a blessed reference. Instead, the value of the |
436 | B<convert_blessed> option will decide whether C<null> (C<convert_blessed> |
462 | B<convert_blessed> option will decide whether C<null> (C<convert_blessed> |
437 | disabled or no C<to_json> method found) or a representation of the |
463 | disabled or no C<TO_JSON> method found) or a representation of the |
438 | object (C<convert_blessed> enabled and C<to_json> method found) is being |
464 | object (C<convert_blessed> enabled and C<TO_JSON> method found) is being |
439 | encoded. Has no effect on C<decode>. |
465 | encoded. Has no effect on C<decode>. |
440 | |
466 | |
441 | If C<$enable> is false (the default), then C<encode> will throw an |
467 | If C<$enable> is false (the default), then C<encode> will throw an |
442 | exception when it encounters a blessed object. |
468 | exception when it encounters a blessed object. |
443 | |
469 | |
… | |
… | |
455 | 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> |
456 | returns other blessed objects, those will be handled in the same |
482 | returns other blessed objects, those will be handled in the same |
457 | 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 |
458 | (== 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 |
459 | 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 |
460 | 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> |
461 | function. |
487 | function or method. |
462 | |
488 | |
463 | 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 |
464 | 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 |
465 | enabled by this setting. |
491 | enabled by this setting. |
466 | |
492 | |
… | |
… | |
739 | Other unblessed references are generally not allowed and will cause an |
765 | Other unblessed references are generally not allowed and will cause an |
740 | 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 |
741 | 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 |
742 | 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. |
743 | |
769 | |
744 | to_json [\0,JSON::XS::true] # yields [false,true] |
770 | encode_json [\0,JSON::XS::true] # yields [false,true] |
745 | |
771 | |
746 | =item JSON::XS::true, JSON::XS::false |
772 | =item JSON::XS::true, JSON::XS::false |
747 | |
773 | |
748 | These special values become JSON true and JSON false values, |
774 | These special values become JSON true and JSON false values, |
749 | 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. |
750 | |
776 | |
751 | =item blessed objects |
777 | =item blessed objects |
752 | |
778 | |
753 | Blessed objects are not allowed. JSON::XS currently tries to encode their |
779 | Blessed objects are not directly representable in JSON. See the |
754 | underlying representation (hash- or arrayref), but this behaviour might |
780 | C<allow_blessed> and C<convert_blessed> methods on various options on |
755 | change in future versions. |
781 | how to deal with this: basically, you can choose between throwing an |
|
|
782 | exception, encoding the reference as if it weren't blessed, or provide |
|
|
783 | your own serialiser method. |
756 | |
784 | |
757 | =item simple scalars |
785 | =item simple scalars |
758 | |
786 | |
759 | Simple Perl scalars (any scalar that is not a reference) are the most |
787 | Simple Perl scalars (any scalar that is not a reference) are the most |
760 | difficult objects to encode: JSON::XS will encode undefined scalars as |
788 | difficult objects to encode: JSON::XS will encode undefined scalars as |
761 | JSON null value, scalars that have last been used in a string context |
789 | JSON C<null> values, scalars that have last been used in a string context |
762 | before encoding as JSON strings and anything else as number value: |
790 | before encoding as JSON strings, and anything else as number value: |
763 | |
791 | |
764 | # dump as number |
792 | # dump as number |
765 | to_json [2] # yields [2] |
793 | encode_json [2] # yields [2] |
766 | to_json [-3.0e17] # yields [-3e+17] |
794 | encode_json [-3.0e17] # yields [-3e+17] |
767 | my $value = 5; to_json [$value] # yields [5] |
795 | my $value = 5; encode_json [$value] # yields [5] |
768 | |
796 | |
769 | # used as string, so dump as string |
797 | # used as string, so dump as string |
770 | print $value; |
798 | print $value; |
771 | to_json [$value] # yields ["5"] |
799 | encode_json [$value] # yields ["5"] |
772 | |
800 | |
773 | # undef becomes null |
801 | # undef becomes null |
774 | to_json [undef] # yields [null] |
802 | encode_json [undef] # yields [null] |
775 | |
803 | |
776 | You can force the type to be a JSON string by stringifying it: |
804 | You can force the type to be a JSON string by stringifying it: |
777 | |
805 | |
778 | my $x = 3.1; # some variable containing a number |
806 | my $x = 3.1; # some variable containing a number |
779 | "$x"; # stringified |
807 | "$x"; # stringified |
… | |
… | |
785 | my $x = "3"; # some variable containing a string |
813 | my $x = "3"; # some variable containing a string |
786 | $x += 0; # numify it, ensuring it will be dumped as a number |
814 | $x += 0; # numify it, ensuring it will be dumped as a number |
787 | $x *= 1; # same thing, the choice is yours. |
815 | $x *= 1; # same thing, the choice is yours. |
788 | |
816 | |
789 | You can not currently force the type in other, less obscure, ways. Tell me |
817 | You can not currently force the type in other, less obscure, ways. Tell me |
790 | if you need this capability. |
818 | if you need this capability (but don't forget to explain why its needed |
|
|
819 | :). |
791 | |
820 | |
792 | =back |
821 | =back |
793 | |
822 | |
794 | |
823 | |
795 | =head1 COMPARISON |
824 | =head1 COMPARISON |
… | |
… | |
879 | =back |
908 | =back |
880 | |
909 | |
881 | |
910 | |
882 | =head2 JSON and YAML |
911 | =head2 JSON and YAML |
883 | |
912 | |
884 | You often hear that JSON is a subset (or a close subset) of YAML. This is, |
913 | You often hear that JSON is a subset of YAML. This is, however, a mass |
885 | however, a mass hysteria and very far from the truth. In general, there is |
914 | hysteria(*) and very far from the truth. In general, there is no way to |
886 | no way to configure JSON::XS to output a data structure as valid YAML. |
915 | configure JSON::XS to output a data structure as valid YAML that works for |
|
|
916 | all cases. |
887 | |
917 | |
888 | If you really must use JSON::XS to generate YAML, you should use this |
918 | If you really must use JSON::XS to generate YAML, you should use this |
889 | algorithm (subject to change in future versions): |
919 | algorithm (subject to change in future versions): |
890 | |
920 | |
891 | my $to_yaml = JSON::XS->new->utf8->space_after (1); |
921 | my $to_yaml = JSON::XS->new->utf8->space_after (1); |
892 | my $yaml = $to_yaml->encode ($ref) . "\n"; |
922 | my $yaml = $to_yaml->encode ($ref) . "\n"; |
893 | |
923 | |
894 | This will usually generate JSON texts that also parse as valid |
924 | This will I<usually> generate JSON texts that also parse as valid |
895 | YAML. Please note that YAML has hardcoded limits on (simple) object key |
925 | YAML. Please note that YAML has hardcoded limits on (simple) object key |
896 | lengths that JSON doesn't have, so you should make sure that your hash |
926 | lengths that JSON doesn't have and also has different and incompatible |
|
|
927 | unicode handling, so you should make sure that your hash keys are |
897 | keys are noticeably shorter than the 1024 characters YAML allows. |
928 | noticeably shorter than the 1024 "stream characters" YAML allows and that |
|
|
929 | you do not have codepoints with values outside the Unicode BMP (basic |
|
|
930 | multilingual page). YAML also does not allow C<\/> sequences in strings |
|
|
931 | (which JSON::XS does not I<currently> generate). |
898 | |
932 | |
899 | There might be other incompatibilities that I am not aware of. In general |
933 | There might be other incompatibilities that I am not aware of (or the YAML |
|
|
934 | specification has been changed yet again - it does so quite often). In |
900 | you should not try to generate YAML with a JSON generator or vice versa, |
935 | general you should not try to generate YAML with a JSON generator or vice |
901 | or try to parse JSON with a YAML parser or vice versa: chances are high |
936 | versa, or try to parse JSON with a YAML parser or vice versa: chances are |
902 | that you will run into severe interoperability problems. |
937 | high that you will run into severe interoperability problems when you |
|
|
938 | least expect it. |
|
|
939 | |
|
|
940 | =over 4 |
|
|
941 | |
|
|
942 | =item (*) |
|
|
943 | |
|
|
944 | This is spread actively by the YAML team, however. For many years now they |
|
|
945 | claim YAML were a superset of JSON, even when proven otherwise. |
|
|
946 | |
|
|
947 | Even the author of this manpage was at some point accused of providing |
|
|
948 | "incorrect" information, despite the evidence presented (claims ranged |
|
|
949 | from "your documentation contains inaccurate and negative statements about |
|
|
950 | YAML" (the only negative comment is this footnote, and it didn't exist |
|
|
951 | back then; the question on which claims were inaccurate was never answered |
|
|
952 | etc.) to "the YAML spec is not up-to-date" (the *real* and supposedly |
|
|
953 | JSON-compatible spec is apparently not currently publicly available) |
|
|
954 | to actual requests to replace this section by *incorrect* information, |
|
|
955 | suppressing information about the real problem). |
|
|
956 | |
|
|
957 | So whenever you are told that YAML was a superset of JSON, first check |
|
|
958 | wether it is really true (it might be when you check it, but it certainly |
|
|
959 | was not true when this was written). I would much prefer if the YAML team |
|
|
960 | would spent their time on actually making JSON compatibility a truth |
|
|
961 | (JSON, after all, has a very small and simple specification) instead of |
|
|
962 | trying to lobby/force people into reporting untruths. |
|
|
963 | |
|
|
964 | =back |
903 | |
965 | |
904 | |
966 | |
905 | =head2 SPEED |
967 | =head2 SPEED |
906 | |
968 | |
907 | It seems that JSON::XS is surprisingly fast, as shown in the following |
969 | It seems that JSON::XS is surprisingly fast, as shown in the following |
… | |
… | |
984 | |
1046 | |
985 | Third, JSON::XS recurses using the C stack when decoding objects and |
1047 | Third, JSON::XS recurses using the C stack when decoding objects and |
986 | arrays. The C stack is a limited resource: for instance, on my amd64 |
1048 | arrays. The C stack is a limited resource: for instance, on my amd64 |
987 | machine with 8MB of stack size I can decode around 180k nested arrays but |
1049 | machine with 8MB of stack size I can decode around 180k nested arrays but |
988 | only 14k nested JSON objects (due to perl itself recursing deeply on croak |
1050 | only 14k nested JSON objects (due to perl itself recursing deeply on croak |
989 | to free the temporary). If that is exceeded, the program crashes. to be |
1051 | to free the temporary). If that is exceeded, the program crashes. To be |
990 | conservative, the default nesting limit is set to 512. If your process |
1052 | conservative, the default nesting limit is set to 512. If your process |
991 | has a smaller stack, you should adjust this setting accordingly with the |
1053 | has a smaller stack, you should adjust this setting accordingly with the |
992 | C<max_depth> method. |
1054 | C<max_depth> method. |
993 | |
1055 | |
994 | And last but least, something else could bomb you that I forgot to think |
1056 | And last but least, something else could bomb you that I forgot to think |
… | |
… | |
998 | If you are using JSON::XS to return packets to consumption |
1060 | If you are using JSON::XS to return packets to consumption |
999 | by JavaScript scripts in a browser you should have a look at |
1061 | by JavaScript scripts in a browser you should have a look at |
1000 | L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether |
1062 | L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether |
1001 | you are vulnerable to some common attack vectors (which really are browser |
1063 | you are vulnerable to some common attack vectors (which really are browser |
1002 | design bugs, but it is still you who will have to deal with it, as major |
1064 | design bugs, but it is still you who will have to deal with it, as major |
1003 | browser developers care only for features, not about doing security |
1065 | browser developers care only for features, not about getting security |
1004 | right). |
1066 | right). |
1005 | |
1067 | |
1006 | |
1068 | |
1007 | =head1 THREADS |
1069 | =head1 THREADS |
1008 | |
1070 | |