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.138 by root, Wed Aug 1 19:04:41 2012 UTC vs.
Revision 1.143 by root, Fri Oct 25 20:02:54 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.33'; 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
691silently stop parsing there and return the number of characters consumed 674silently stop parsing there and return the number of characters consumed
692so far. 675so far.
693 676
694This is useful if your JSON texts are not delimited by an outer protocol 677This is useful if your JSON texts are not delimited by an outer protocol
695(which is not the brightest thing to do in the first place) and you need
696to know where the JSON text ends. 678and you need to know where the JSON text ends.
697 679
698 JSON::XS->new->decode_prefix ("[1] the tail") 680 JSON::XS->new->decode_prefix ("[1] the tail")
699 => ([], 3) 681 => ([], 3)
700 682
701=back 683=back
… …
740 722
741If the method is called in scalar context, then it will try to extract 723If 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 724exactly 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, 725object, 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 726this 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 727C<incr_skip> to skip the erroneous part). This is the most common way of
746using the method. 728using the method.
747 729
748And finally, in list context, it will try to extract as many objects 730And 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 731from 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 732otherwise. 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 761C<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 762state is left unchanged, to skip the text parsed so far and to reset the
781parse state. 763parse state.
782 764
783The difference to C<incr_reset> is that only text until the parse error 765The difference to C<incr_reset> is that only text until the parse error
784occured is removed. 766occurred is removed.
785 767
786=item $json->incr_reset 768=item $json->incr_reset
787 769
788This completely resets the incremental parser, that is, after this call, 770This completely resets the incremental parser, that is, after this call,
789it will be as if the parser had never parsed anything. 771it will be as if the parser had never parsed anything.
… …
795=back 777=back
796 778
797=head2 LIMITATIONS 779=head2 LIMITATIONS
798 780
799All options that affect decoding are supported, except 781All options that affect decoding are supported, except
800C<allow_nonref>. The reason for this is that it cannot be made to 782C<allow_nonref>. The reason for this is that it cannot be made to work
801work sensibly: JSON objects and arrays are self-delimited, i.e. you can concatenate 783sensibly: JSON objects and arrays are self-delimited, i.e. you can
802them back to back and still decode them perfectly. This does not hold true 784concatenate them back to back and still decode them perfectly. This does
803for JSON numbers, however. 785not hold true for JSON numbers, however.
804 786
805For example, is the string C<1> a single JSON number, or is it simply the 787For example, is the string C<1> a single JSON number, or is it simply the
806start of C<12>? Or is C<12> a single JSON number, or the concatenation 788start of C<12>? Or is C<12> a single JSON number, or the concatenation
807of C<1> and C<2>? In neither case you can tell, and this is why JSON::XS 789of C<1> and C<2>? In neither case you can tell, and this is why JSON::XS
808takes the conservative route and disallows this case. 790takes the conservative route and disallows this case.
… …
987If the number consists of digits only, JSON::XS will try to represent 969If 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 970it 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 971a numeric (floating point) value if that is possible without loss of
990precision. Otherwise it will preserve the number as a string value (in 972precision. Otherwise it will preserve the number as a string value (in
991which case you lose roundtripping ability, as the JSON number will be 973which case you lose roundtripping ability, as the JSON number will be
992re-encoded toa JSON string). 974re-encoded to a JSON string).
993 975
994Numbers containing a fractional or exponential part will always be 976Numbers containing a fractional or exponential part will always be
995represented as numeric (floating point) values, possibly at a loss of 977represented as numeric (floating point) values, possibly at a loss of
996precision (in which case you might lose perfect roundtripping ability, but 978precision (in which case you might lose perfect roundtripping ability, but
997the JSON number will still be re-encoded as a JSON number). 979the JSON number will still be re-encoded as a JSON number).
998 980
999Note that precision is not accuracy - binary floating point values cannot 981Note that precision is not accuracy - binary floating point values cannot
1000represent most decimal fractions exactly, and when converting from and to 982represent most decimal fractions exactly, and when converting from and to
1001floating point, JSON::XS only guarantees precision up to but not including 983floating point, JSON::XS only guarantees precision up to but not including
1002the leats significant bit. 984the least significant bit.
1003 985
1004=item true, false 986=item true, false
1005 987
1006These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>, 988These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
1007respectively. They are overloaded to act almost exactly like the numbers 989respectively. They are overloaded to act almost exactly like the numbers
… …
1023 1005
1024=over 4 1006=over 4
1025 1007
1026=item hash references 1008=item hash references
1027 1009
1028Perl hash references become JSON objects. As there is no inherent ordering 1010Perl hash references become JSON objects. As there is no inherent
1029in hash keys (or JSON objects), they will usually be encoded in a 1011ordering in hash keys (or JSON objects), they will usually be encoded
1030pseudo-random order that can change between runs of the same program but 1012in 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 1013(determined by the I<canonical> flag), so the same datastructure will
1032optionally sort the hash keys (determined by the I<canonical> flag), so 1014serialise to the same JSON text (given same settings and version of
1033the same datastructure will serialise to the same JSON text (given same 1015JSON::XS), but this incurs a runtime overhead and is only rarely useful,
1034settings and version of JSON::XS), but this incurs a runtime overhead 1016e.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 1017
1038=item array references 1018=item array references
1039 1019
1040Perl array references become JSON arrays. 1020Perl array references become JSON arrays.
1041 1021
… …
1137=item C<utf8> flag disabled 1117=item C<utf8> flag disabled
1138 1118
1139When C<utf8> is disabled (the default), then C<encode>/C<decode> generate 1119When C<utf8> is disabled (the default), then C<encode>/C<decode> generate
1140and expect Unicode strings, that is, characters with high ordinal Unicode 1120and expect Unicode strings, that is, characters with high ordinal Unicode
1141values (> 255) will be encoded as such characters, and likewise such 1121values (> 255) will be encoded as such characters, and likewise such
1142characters are decoded as-is, no canges to them will be done, except 1122characters are decoded as-is, no changes to them will be done, except
1143"(re-)interpreting" them as Unicode codepoints or Unicode characters, 1123"(re-)interpreting" them as Unicode codepoints or Unicode characters,
1144respectively (to Perl, these are the same thing in strings unless you do 1124respectively (to Perl, these are the same thing in strings unless you do
1145funny/weird/dumb stuff). 1125funny/weird/dumb stuff).
1146 1126
1147This is useful when you want to do the encoding yourself (e.g. when you 1127This is useful when you want to do the encoding yourself (e.g. when you
… …
1263output for these property strings, e.g.: 1243output for these property strings, e.g.:
1264 1244
1265 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g; 1245 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1266 1246
1267This works because C<__proto__> is not valid outside of strings, so every 1247This 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. 1248occurrence of C<"__proto__"\s*:> must be a string used as property name.
1269 1249
1270If you know of other incompatibilities, please let me know. 1250If you know of other incompatibilities, please let me know.
1271 1251
1272 1252
1273=head2 JSON and YAML 1253=head2 JSON and YAML
… …
1445process simulations - use fork, it's I<much> faster, cheaper, better). 1425process simulations - use fork, it's I<much> faster, cheaper, better).
1446 1426
1447(It might actually work, but you have been warned). 1427(It might actually work, but you have been warned).
1448 1428
1449 1429
1430=head1 THE PERILS OF SETLOCALE
1431
1432Sometimes people avoid the Perl locale support and directly call the
1433system's setlocale function with C<LC_ALL>.
1434
1435This breaks both perl and modules such as JSON::XS, as stringification of
1436numbers no longer works correctly (e.g. C<$x = 0.1; print "$x"+1> might
1437print C<1>, and JSON::XS might output illegal JSON as JSON::XS relies on
1438perl to stringify numbers).
1439
1440The solution is simple: don't call C<setlocale>, or use it for only those
1441categories you need, such as C<LC_MESSAGES> or C<LC_CTYPE>.
1442
1443If you need C<LC_NUMERIC>, you should enable it only around the code that
1444actually needs it (avoiding stringification of numbers), and restore it
1445afterwards.
1446
1447
1450=head1 BUGS 1448=head1 BUGS
1451 1449
1452While the goal of this module is to be correct, that unfortunately does 1450While 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 1451not 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. 1452keep reporting bugs they will be fixed swiftly, though.

Diff Legend

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