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.75 by root, Thu Nov 29 13:35:35 2007 UTC vs.
Revision 1.78 by root, Wed Dec 5 10:59:28 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);
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
26This module converts Perl data structures to JSON and vice versa. Its 34This module converts Perl data structures to JSON and vice versa. Its
27primary goal is to be I<correct> and its secondary goal is to be 35primary goal is to be I<correct> and its secondary goal is to be
28I<fast>. To reach the latter goal it was written in C. 36I<fast>. To reach the latter goal it was written in C.
37
38Beginning with version 2.0 of the JSON module, when both JSON and
39JSON::XS are installed, then JSON will fall back on JSON::XS (this can be
40overriden) with no overhead due to emulation (by inheritign constructor
41and methods). If JSON::XS is not available, it will fall back to the
42compatible JSON::PP module as backend, so using JSON instead of JSON::XS
43gives you a portable JSON API that can be fast when you need and doesn't
44require a C compiler when that is a problem.
29 45
30As this is the n-th-something JSON module on CPAN, what was the reason 46As this is the n-th-something JSON module on CPAN, what was the reason
31to write yet another JSON module? While it seems there are many JSON 47to write yet another JSON module? While it seems there are many JSON
32modules, none of them correctly handle all corner cases, and in most cases 48modules, none of them correctly handle all corner cases, and in most cases
33their maintainers are unresponsive, gone missing, or not listening to bug 49their maintainers are unresponsive, gone missing, or not listening to bug
… …
84 100
85package JSON::XS; 101package JSON::XS;
86 102
87use strict; 103use strict;
88 104
89our $VERSION = '2.0'; 105our $VERSION = '2.01';
90our @ISA = qw(Exporter); 106our @ISA = qw(Exporter);
91 107
92our @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}
93 119
94use Exporter; 120use Exporter;
95use XSLoader; 121use XSLoader;
96 122
97=head1 FUNCTIONAL INTERFACE 123=head1 FUNCTIONAL INTERFACE
… …
99The following convenience methods are provided by this module. They are 125The following convenience methods are provided by this module. They are
100exported by default: 126exported 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
106Converts 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
107(that is, the string contains octets only). Croaks on error. 133(that is, the string contains octets only). Croaks on error.
108 134
109This function call is functionally identical to: 135This 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
113except being faster. 139except being faster.
114 140
115=item $perl_scalar = from_json $json_text 141=item $perl_scalar = decode_json $json_text
116 142
117The 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
118to 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
119reference. Croaks on error. 145reference. Croaks on error.
120 146
121This function call is functionally identical to: 147This function call is functionally identical to:
122 148
… …
432=item $enabled = $json->get_allow_blessed 458=item $enabled = $json->get_allow_blessed
433 459
434If C<$enable> is true (or missing), then the C<encode> method will not 460If C<$enable> is true (or missing), then the C<encode> method will not
435barf when it encounters a blessed reference. Instead, the value of the 461barf when it encounters a blessed reference. Instead, the value of the
436B<convert_blessed> option will decide whether C<null> (C<convert_blessed> 462B<convert_blessed> option will decide whether C<null> (C<convert_blessed>
437disabled or no C<to_json> method found) or a representation of the 463disabled or no C<TO_JSON> method found) or a representation of the
438object (C<convert_blessed> enabled and C<to_json> method found) is being 464object (C<convert_blessed> enabled and C<TO_JSON> method found) is being
439encoded. Has no effect on C<decode>. 465encoded. Has no effect on C<decode>.
440 466
441If C<$enable> is false (the default), then C<encode> will throw an 467If C<$enable> is false (the default), then C<encode> will throw an
442exception when it encounters a blessed object. 468exception when it encounters a blessed object.
443 469
… …
455The 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>
456returns other blessed objects, those will be handled in the same 482returns other blessed objects, those will be handled in the same
457way. 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
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
459methods 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
460usually 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>
461function. 487function or method.
462 488
463This 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
464future, global hooks might get installed that influence C<decode> and are 490future, global hooks might get installed that influence C<decode> and are
465enabled by this setting. 491enabled by this setting.
466 492
… …
739Other unblessed references are generally not allowed and will cause an 765Other unblessed references are generally not allowed and will cause an
740exception 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
741C<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
742also 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.
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
748These special values become JSON true and JSON false values, 774These special values become JSON true and JSON false values,
749respectively. 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.
… …
760difficult objects to encode: JSON::XS will encode undefined scalars as 786difficult objects to encode: JSON::XS will encode undefined scalars as
761JSON 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
762before encoding as JSON strings and anything else as number value: 788before encoding as JSON strings and anything else as number value:
763 789
764 # dump as number 790 # dump as number
765 to_json [2] # yields [2] 791 encode_json [2] # yields [2]
766 to_json [-3.0e17] # yields [-3e+17] 792 encode_json [-3.0e17] # yields [-3e+17]
767 my $value = 5; to_json [$value] # yields [5] 793 my $value = 5; encode_json [$value] # yields [5]
768 794
769 # used as string, so dump as string 795 # used as string, so dump as string
770 print $value; 796 print $value;
771 to_json [$value] # yields ["5"] 797 encode_json [$value] # yields ["5"]
772 798
773 # undef becomes null 799 # undef becomes null
774 to_json [undef] # yields [null] 800 encode_json [undef] # yields [null]
775 801
776You 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:
777 803
778 my $x = 3.1; # some variable containing a number 804 my $x = 3.1; # some variable containing a number
779 "$x"; # stringified 805 "$x"; # stringified

Diff Legend

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