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

Comparing JSON-XS/README (file contents):
Revision 1.21 by root, Tue Dec 4 10:37:42 2007 UTC vs.
Revision 1.22 by root, Wed Dec 5 10:59:27 2007 UTC

… …
9 use JSON::XS; 9 use JSON::XS;
10 10
11 # exported functions, they croak on error 11 # exported functions, they croak on error
12 # and expect/generate UTF-8 12 # and expect/generate UTF-8
13 13
14 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; 14 $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
15 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; 15 $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text;
16 16
17 # OO-interface 17 # OO-interface
18 18
19 $coder = JSON::XS->new->ascii->pretty->allow_nonref; 19 $coder = JSON::XS->new->ascii->pretty->allow_nonref;
20 $pretty_printed_unencoded = $coder->encode ($perl_scalar); 20 $pretty_printed_unencoded = $coder->encode ($perl_scalar);
… …
86 86
87FUNCTIONAL INTERFACE 87FUNCTIONAL INTERFACE
88 The following convenience methods are provided by this module. They are 88 The following convenience methods are provided by this module. They are
89 exported by default: 89 exported by default:
90 90
91 $json_text = to_json $perl_scalar 91 $json_text = encode_json $perl_scalar
92 Converts the given Perl data structure to a UTF-8 encoded, binary 92 Converts the given Perl data structure to a UTF-8 encoded, binary
93 string (that is, the string contains octets only). Croaks on error. 93 string (that is, the string contains octets only). Croaks on error.
94 94
95 This function call is functionally identical to: 95 This function call is functionally identical to:
96 96
97 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 97 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
98 98
99 except being faster. 99 except being faster.
100 100
101 $perl_scalar = from_json $json_text 101 $perl_scalar = decode_json $json_text
102 The opposite of "to_json": expects an UTF-8 (binary) string and 102 The opposite of "encode_json": expects an UTF-8 (binary) string and
103 tries to parse that as an UTF-8 encoded JSON text, returning the 103 tries to parse that as an UTF-8 encoded JSON text, returning the
104 resulting reference. Croaks on error. 104 resulting reference. Croaks on error.
105 105
106 This function call is functionally identical to: 106 This function call is functionally identical to:
107 107
… …
407 returns other blessed objects, those will be handled in the same 407 returns other blessed objects, those will be handled in the same
408 way. "TO_JSON" must take care of not causing an endless recursion 408 way. "TO_JSON" must take care of not causing an endless recursion
409 cycle (== crash) in this case. The name of "TO_JSON" was chosen 409 cycle (== crash) in this case. The name of "TO_JSON" was chosen
410 because other methods called by the Perl core (== not by the user of 410 because other methods called by the Perl core (== not by the user of
411 the object) are usually in upper case letters and to avoid 411 the object) are usually in upper case letters and to avoid
412 collisions with the "to_json" function. 412 collisions with any "to_json" function or method.
413 413
414 This setting does not yet influence "decode" in any way, but in the 414 This setting does not yet influence "decode" in any way, but in the
415 future, global hooks might get installed that influence "decode" and 415 future, global hooks might get installed that influence "decode" and
416 are enabled by this setting. 416 are enabled by this setting.
417 417
… …
669 an exception to be thrown, except for references to the integers 0 669 an exception to be thrown, except for references to the integers 0
670 and 1, which get turned into "false" and "true" atoms in JSON. You 670 and 1, which get turned into "false" and "true" atoms in JSON. You
671 can also use "JSON::XS::false" and "JSON::XS::true" to improve 671 can also use "JSON::XS::false" and "JSON::XS::true" to improve
672 readability. 672 readability.
673 673
674 to_json [\0,JSON::XS::true] # yields [false,true] 674 encode_json [\0,JSON::XS::true] # yields [false,true]
675 675
676 JSON::XS::true, JSON::XS::false 676 JSON::XS::true, JSON::XS::false
677 These special values become JSON true and JSON false values, 677 These special values become JSON true and JSON false values,
678 respectively. You can also use "\1" and "\0" directly if you want. 678 respectively. You can also use "\1" and "\0" directly if you want.
679 679
… …
688 scalars as JSON null value, scalars that have last been used in a 688 scalars as JSON null value, scalars that have last been used in a
689 string context before encoding as JSON strings and anything else as 689 string context before encoding as JSON strings and anything else as
690 number value: 690 number value:
691 691
692 # dump as number 692 # dump as number
693 to_json [2] # yields [2] 693 encode_json [2] # yields [2]
694 to_json [-3.0e17] # yields [-3e+17] 694 encode_json [-3.0e17] # yields [-3e+17]
695 my $value = 5; to_json [$value] # yields [5] 695 my $value = 5; encode_json [$value] # yields [5]
696 696
697 # used as string, so dump as string 697 # used as string, so dump as string
698 print $value; 698 print $value;
699 to_json [$value] # yields ["5"] 699 encode_json [$value] # yields ["5"]
700 700
701 # undef becomes null 701 # undef becomes null
702 to_json [undef] # yields [null] 702 encode_json [undef] # yields [null]
703 703
704 You can force the type to be a JSON string by stringifying it: 704 You can force the type to be a JSON string by stringifying it:
705 705
706 my $x = 3.1; # some variable containing a number 706 my $x = 3.1; # some variable containing a number
707 "$x"; # stringified 707 "$x"; # stringified

Diff Legend

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