ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/JSON-XS/XS.pm
(Generate patch)

Comparing JSON-XS/XS.pm (file contents):
Revision 1.77 by root, Tue Dec 4 10:37:42 2007 UTC vs.
Revision 1.80 by root, Sat Dec 29 17:22:39 2007 UTC

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

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines