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.139 by root, Thu May 23 09:31:32 2013 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
… …
104use common::sense; 104use common::sense;
105 105
106our $VERSION = 2.34; 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
… …
667 657
668See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 658See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
669 659
670=item $json_text = $json->encode ($perl_scalar) 660=item $json_text = $json->encode ($perl_scalar)
671 661
672Converts the given Perl data structure (a simple scalar or a reference 662Converts the given Perl value or data structure to its JSON
673to a hash or array) to its JSON representation. Simple scalars will be 663representation. Croaks on error.
674converted into JSON string or number sequences, while references to arrays
675become JSON arrays and references to hashes become JSON objects. Undefined
676Perl values (e.g. C<undef>) become JSON C<null> values. Neither C<true>
677nor C<false> values will be generated.
678 664
679=item $perl_scalar = $json->decode ($json_text) 665=item $perl_scalar = $json->decode ($json_text)
680 666
681The 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,
682returning the resulting simple scalar or reference. Croaks on error. 668returning the resulting simple scalar or reference. Croaks on error.
683
684JSON numbers and strings become simple Perl scalars. JSON arrays become
685Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
686C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
687 669
688=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text) 670=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
689 671
690This 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
691when there is trailing garbage after the first JSON object, it will 673when there is trailing garbage after the first JSON object, it will
… …
741 723
742If 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
743exactly 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
744object, 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,
745this 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
746C<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
747using the method. 729using the method.
748 730
749And 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
750from 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
751otherwise. 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
… …
780C<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
781state 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
782parse state. 764parse state.
783 765
784The 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
785occured is removed. 767occurred is removed.
786 768
787=item $json->incr_reset 769=item $json->incr_reset
788 770
789This completely resets the incremental parser, that is, after this call, 771This completely resets the incremental parser, that is, after this call,
790it will be as if the parser had never parsed anything. 772it will be as if the parser had never parsed anything.
… …
988If 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
989it 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
990a numeric (floating point) value if that is possible without loss of 972a numeric (floating point) value if that is possible without loss of
991precision. Otherwise it will preserve the number as a string value (in 973precision. Otherwise it will preserve the number as a string value (in
992which case you lose roundtripping ability, as the JSON number will be 974which case you lose roundtripping ability, as the JSON number will be
993re-encoded toa JSON string). 975re-encoded to a JSON string).
994 976
995Numbers containing a fractional or exponential part will always be 977Numbers containing a fractional or exponential part will always be
996represented as numeric (floating point) values, possibly at a loss of 978represented as numeric (floating point) values, possibly at a loss of
997precision (in which case you might lose perfect roundtripping ability, but 979precision (in which case you might lose perfect roundtripping ability, but
998the JSON number will still be re-encoded as a JSON number). 980the JSON number will still be re-encoded as a JSON number).
999 981
1000Note that precision is not accuracy - binary floating point values cannot 982Note that precision is not accuracy - binary floating point values cannot
1001represent most decimal fractions exactly, and when converting from and to 983represent most decimal fractions exactly, and when converting from and to
1002floating point, JSON::XS only guarantees precision up to but not including 984floating point, JSON::XS only guarantees precision up to but not including
1003the leats significant bit. 985the least significant bit.
1004 986
1005=item true, false 987=item true, false
1006 988
1007These 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>,
1008respectively. They are overloaded to act almost exactly like the numbers 990respectively. They are overloaded to act almost exactly like the numbers
… …
1024 1006
1025=over 4 1007=over 4
1026 1008
1027=item hash references 1009=item hash references
1028 1010
1029Perl hash references become JSON objects. As there is no inherent ordering 1011Perl hash references become JSON objects. As there is no inherent
1030in hash keys (or JSON objects), they will usually be encoded in a 1012ordering in hash keys (or JSON objects), they will usually be encoded
1031pseudo-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
1032stays 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
1033optionally sort the hash keys (determined by the I<canonical> flag), so 1015serialise to the same JSON text (given same settings and version of
1034the same datastructure will serialise to the same JSON text (given same 1016JSON::XS), but this incurs a runtime overhead and is only rarely useful,
1035settings 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.
1036and is only rarely useful, e.g. when you want to compare some JSON text
1037against another for equality.
1038 1018
1039=item array references 1019=item array references
1040 1020
1041Perl array references become JSON arrays. 1021Perl array references become JSON arrays.
1042 1022
… …
1138=item C<utf8> flag disabled 1118=item C<utf8> flag disabled
1139 1119
1140When 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
1141and expect Unicode strings, that is, characters with high ordinal Unicode 1121and expect Unicode strings, that is, characters with high ordinal Unicode
1142values (> 255) will be encoded as such characters, and likewise such 1122values (> 255) will be encoded as such characters, and likewise such
1143characters 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
1144"(re-)interpreting" them as Unicode codepoints or Unicode characters, 1124"(re-)interpreting" them as Unicode codepoints or Unicode characters,
1145respectively (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
1146funny/weird/dumb stuff). 1126funny/weird/dumb stuff).
1147 1127
1148This 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
… …
1264output for these property strings, e.g.: 1244output for these property strings, e.g.:
1265 1245
1266 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g; 1246 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1267 1247
1268This 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
1269occurence 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.
1270 1250
1271If you know of other incompatibilities, please let me know. 1251If you know of other incompatibilities, please let me know.
1272 1252
1273 1253
1274=head2 JSON and YAML 1254=head2 JSON and YAML
… …
1452 1432
1453Sometimes people avoid the Perl locale support and directly call the 1433Sometimes people avoid the Perl locale support and directly call the
1454system's setlocale function with C<LC_ALL>. 1434system's setlocale function with C<LC_ALL>.
1455 1435
1456This breaks both perl and modules such as JSON::XS, as stringification of 1436This breaks both perl and modules such as JSON::XS, as stringification of
1457numbers no longer works correcly (e.g. C<$x = 0.1; print "$x"+1> might 1437numbers no longer works correctly (e.g. C<$x = 0.1; print "$x"+1> might
1458print C<1>, and JSON::XS might output illegal JSON as JSON::XS relies on 1438print C<1>, and JSON::XS might output illegal JSON as JSON::XS relies on
1459perl to stringify numbers). 1439perl to stringify numbers).
1460 1440
1461The solution is simple: don't call C<setlocale>, or use it for only those 1441The solution is simple: don't call C<setlocale>, or use it for only those
1462categories you need, such as C<LC_MESSAGES> or C<LC_CTYPE>. 1442categories you need, such as C<LC_MESSAGES> or C<LC_CTYPE>.

Diff Legend

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