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.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);
… …
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

Diff Legend

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