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.137 by root, Thu Aug 11 17:06:53 2011 UTC vs.
Revision 1.142 by root, Fri Oct 25 19:57:42 2013 UTC

… …
83this module usually compares favourably in terms of speed, too. 83this module usually compares favourably in terms of speed, too.
84 84
85=item * simple to use 85=item * simple to use
86 86
87This module has both a simple functional interface as well as an object 87This module has both a simple functional interface as well as an object
88oriented interface interface. 88oriented interface.
89 89
90=item * reasonably versatile output formats 90=item * reasonably versatile output formats
91 91
92You can choose between the most compact guaranteed-single-line format 92You can choose between the most compact guaranteed-single-line format
93possible (nice for simple line-based protocols), a pure-ASCII format 93possible (nice for simple line-based protocols), a pure-ASCII format
… …
101 101
102package JSON::XS; 102package JSON::XS;
103 103
104use common::sense; 104use common::sense;
105 105
106our $VERSION = '2.32'; 106our $VERSION = 2.34;
107our @ISA = qw(Exporter); 107our @ISA = qw(Exporter);
108 108
109our @EXPORT = qw(encode_json decode_json to_json from_json); 109our @EXPORT = qw(encode_json decode_json);
110
111sub to_json($) {
112 require Carp;
113 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");
114}
115
116sub from_json($) {
117 require Carp;
118 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");
119}
120 110
121use Exporter; 111use Exporter;
122use XSLoader; 112use XSLoader;
123 113
124=head1 FUNCTIONAL INTERFACE 114=head1 FUNCTIONAL INTERFACE
… …
432If C<$enable> is true (or missing), then the C<encode> method will output JSON objects 422If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
433by sorting their keys. This is adding a comparatively high overhead. 423by sorting their keys. This is adding a comparatively high overhead.
434 424
435If C<$enable> is false, then the C<encode> method will output key-value 425If C<$enable> is false, then the C<encode> method will output key-value
436pairs in the order Perl stores them (which will likely change between runs 426pairs in the order Perl stores them (which will likely change between runs
437of the same script). 427of the same script, and can change even within the same run from 5.18
428onwards).
438 429
439This option is useful if you want the same data structure to be encoded as 430This option is useful if you want the same data structure to be encoded as
440the same JSON text (given the same overall settings). If it is disabled, 431the same JSON text (given the same overall settings). If it is disabled,
441the same hash might be encoded differently even if contains the same data, 432the same hash might be encoded differently even if contains the same data,
442as key-value pairs have no inherent ordering in Perl. 433as key-value pairs have no inherent ordering in Perl.
… …
666 657
667See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 658See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
668 659
669=item $json_text = $json->encode ($perl_scalar) 660=item $json_text = $json->encode ($perl_scalar)
670 661
671Converts the given Perl data structure (a simple scalar or a reference 662Converts the given Perl value or data structure to its JSON
672to a hash or array) to its JSON representation. Simple scalars will be 663representation. Croaks on error.
673converted into JSON string or number sequences, while references to arrays
674become JSON arrays and references to hashes become JSON objects. Undefined
675Perl values (e.g. C<undef>) become JSON C<null> values. Neither C<true>
676nor C<false> values will be generated.
677 664
678=item $perl_scalar = $json->decode ($json_text) 665=item $perl_scalar = $json->decode ($json_text)
679 666
680The opposite of C<encode>: expects a JSON text and tries to parse it, 667The opposite of C<encode>: expects a JSON text and tries to parse it,
681returning the resulting simple scalar or reference. Croaks on error. 668returning the resulting simple scalar or reference. Croaks on error.
682
683JSON numbers and strings become simple Perl scalars. JSON arrays become
684Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
685C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
686 669
687=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text) 670=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
688 671
689This works like the C<decode> method, but instead of raising an exception 672This works like the C<decode> method, but instead of raising an exception
690when there is trailing garbage after the first JSON object, it will 673when there is trailing garbage after the first JSON object, it will
… …
740 723
741If the method is called in scalar context, then it will try to extract 724If the method is called in scalar context, then it will try to extract
742exactly I<one> JSON object. If that is successful, it will return this 725exactly I<one> JSON object. If that is successful, it will return this
743object, otherwise it will return C<undef>. If there is a parse error, 726object, otherwise it will return C<undef>. If there is a parse error,
744this method will croak just as C<decode> would do (one can then use 727this method will croak just as C<decode> would do (one can then use
745C<incr_skip> to skip the errornous part). This is the most common way of 728C<incr_skip> to skip the erroneous part). This is the most common way of
746using the method. 729using the method.
747 730
748And finally, in list context, it will try to extract as many objects 731And finally, in list context, it will try to extract as many objects
749from the stream as it can find and return them, or the empty list 732from the stream as it can find and return them, or the empty list
750otherwise. For this to work, there must be no separators between the JSON 733otherwise. For this to work, there must be no separators between the JSON
… …
779C<incr_parse> died, in which case the input buffer and incremental parser 762C<incr_parse> died, in which case the input buffer and incremental parser
780state is left unchanged, to skip the text parsed so far and to reset the 763state is left unchanged, to skip the text parsed so far and to reset the
781parse state. 764parse state.
782 765
783The difference to C<incr_reset> is that only text until the parse error 766The difference to C<incr_reset> is that only text until the parse error
784occured is removed. 767occurred is removed.
785 768
786=item $json->incr_reset 769=item $json->incr_reset
787 770
788This completely resets the incremental parser, that is, after this call, 771This completely resets the incremental parser, that is, after this call,
789it will be as if the parser had never parsed anything. 772it will be as if the parser had never parsed anything.
… …
987If the number consists of digits only, JSON::XS will try to represent 970If the number consists of digits only, JSON::XS will try to represent
988it as an integer value. If that fails, it will try to represent it as 971it as an integer value. If that fails, it will try to represent it as
989a numeric (floating point) value if that is possible without loss of 972a numeric (floating point) value if that is possible without loss of
990precision. Otherwise it will preserve the number as a string value (in 973precision. Otherwise it will preserve the number as a string value (in
991which case you lose roundtripping ability, as the JSON number will be 974which case you lose roundtripping ability, as the JSON number will be
992re-encoded toa JSON string). 975re-encoded to a JSON string).
993 976
994Numbers containing a fractional or exponential part will always be 977Numbers containing a fractional or exponential part will always be
995represented as numeric (floating point) values, possibly at a loss of 978represented as numeric (floating point) values, possibly at a loss of
996precision (in which case you might lose perfect roundtripping ability, but 979precision (in which case you might lose perfect roundtripping ability, but
997the JSON number will still be re-encoded as a JSON number). 980the JSON number will still be re-encoded as a JSON number).
998 981
999Note that precision is not accuracy - binary floating point values cannot 982Note that precision is not accuracy - binary floating point values cannot
1000represent most decimal fractions exactly, and when converting from and to 983represent most decimal fractions exactly, and when converting from and to
1001floating point, JSON::XS only guarantees precision up to but not including 984floating point, JSON::XS only guarantees precision up to but not including
1002the leats significant bit. 985the least significant bit.
1003 986
1004=item true, false 987=item true, false
1005 988
1006These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>, 989These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
1007respectively. They are overloaded to act almost exactly like the numbers 990respectively. They are overloaded to act almost exactly like the numbers
… …
1023 1006
1024=over 4 1007=over 4
1025 1008
1026=item hash references 1009=item hash references
1027 1010
1028Perl hash references become JSON objects. As there is no inherent ordering 1011Perl hash references become JSON objects. As there is no inherent
1029in hash keys (or JSON objects), they will usually be encoded in a 1012ordering in hash keys (or JSON objects), they will usually be encoded
1030pseudo-random order that can change between runs of the same program but 1013in a pseudo-random order. JSON::XS can optionally sort the hash keys
1031stays generally the same within a single run of a program. JSON::XS can 1014(determined by the I<canonical> flag), so the same datastructure will
1032optionally sort the hash keys (determined by the I<canonical> flag), so 1015serialise to the same JSON text (given same settings and version of
1033the same datastructure will serialise to the same JSON text (given same 1016JSON::XS), but this incurs a runtime overhead and is only rarely useful,
1034settings and version of JSON::XS), but this incurs a runtime overhead 1017e.g. when you want to compare some JSON text against another for equality.
1035and is only rarely useful, e.g. when you want to compare some JSON text
1036against another for equality.
1037 1018
1038=item array references 1019=item array references
1039 1020
1040Perl array references become JSON arrays. 1021Perl array references become JSON arrays.
1041 1022
… …
1137=item C<utf8> flag disabled 1118=item C<utf8> flag disabled
1138 1119
1139When C<utf8> is disabled (the default), then C<encode>/C<decode> generate 1120When C<utf8> is disabled (the default), then C<encode>/C<decode> generate
1140and expect Unicode strings, that is, characters with high ordinal Unicode 1121and expect Unicode strings, that is, characters with high ordinal Unicode
1141values (> 255) will be encoded as such characters, and likewise such 1122values (> 255) will be encoded as such characters, and likewise such
1142characters are decoded as-is, no canges to them will be done, except 1123characters are decoded as-is, no changes to them will be done, except
1143"(re-)interpreting" them as Unicode codepoints or Unicode characters, 1124"(re-)interpreting" them as Unicode codepoints or Unicode characters,
1144respectively (to Perl, these are the same thing in strings unless you do 1125respectively (to Perl, these are the same thing in strings unless you do
1145funny/weird/dumb stuff). 1126funny/weird/dumb stuff).
1146 1127
1147This is useful when you want to do the encoding yourself (e.g. when you 1128This is useful when you want to do the encoding yourself (e.g. when you
… …
1263output for these property strings, e.g.: 1244output for these property strings, e.g.:
1264 1245
1265 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g; 1246 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1266 1247
1267This works because C<__proto__> is not valid outside of strings, so every 1248This works because C<__proto__> is not valid outside of strings, so every
1268occurence of C<"__proto__"\s*:> must be a string used as property name. 1249occurrence of C<"__proto__"\s*:> must be a string used as property name.
1269 1250
1270If you know of other incompatibilities, please let me know. 1251If you know of other incompatibilities, please let me know.
1271 1252
1272 1253
1273=head2 JSON and YAML 1254=head2 JSON and YAML
… …
1445process simulations - use fork, it's I<much> faster, cheaper, better). 1426process simulations - use fork, it's I<much> faster, cheaper, better).
1446 1427
1447(It might actually work, but you have been warned). 1428(It might actually work, but you have been warned).
1448 1429
1449 1430
1431=head1 THE PERILS OF SETLOCALE
1432
1433Sometimes people avoid the Perl locale support and directly call the
1434system's setlocale function with C<LC_ALL>.
1435
1436This breaks both perl and modules such as JSON::XS, as stringification of
1437numbers no longer works correctly (e.g. C<$x = 0.1; print "$x"+1> might
1438print C<1>, and JSON::XS might output illegal JSON as JSON::XS relies on
1439perl to stringify numbers).
1440
1441The solution is simple: don't call C<setlocale>, or use it for only those
1442categories you need, such as C<LC_MESSAGES> or C<LC_CTYPE>.
1443
1444If you need C<LC_NUMERIC>, you should enable it only around the code that
1445actually needs it (avoiding stringification of numbers), and restore it
1446afterwards.
1447
1448
1450=head1 BUGS 1449=head1 BUGS
1451 1450
1452While the goal of this module is to be correct, that unfortunately does 1451While the goal of this module is to be correct, that unfortunately does
1453not mean it's bug-free, only that I think its design is bug-free. If you 1452not mean it's bug-free, only that I think its design is bug-free. If you
1454keep reporting bugs they will be fixed swiftly, though. 1453keep reporting bugs they will be fixed swiftly, though.

Diff Legend

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