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.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
… …
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
692silently stop parsing there and return the number of characters consumed 674silently stop parsing there and return the number of characters consumed
693so far. 675so far.
694 676
695This 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
696(which is not the brightest thing to do in the first place) and you need
697to know where the JSON text ends. 678and you need to know where the JSON text ends.
698 679
699 JSON::XS->new->decode_prefix ("[1] the tail") 680 JSON::XS->new->decode_prefix ("[1] the tail")
700 => ([], 3) 681 => ([], 3)
701 682
702=back 683=back
… …
741 722
742If 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
743exactly 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
744object, 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,
745this 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
746C<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
747using the method. 728using the method.
748 729
749And 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
750from 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
751otherwise. 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
… …
780C<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
781state 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
782parse state. 763parse state.
783 764
784The 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
785occured is removed. 766occurred is removed.
786 767
787=item $json->incr_reset 768=item $json->incr_reset
788 769
789This completely resets the incremental parser, that is, after this call, 770This completely resets the incremental parser, that is, after this call,
790it will be as if the parser had never parsed anything. 771it will be as if the parser had never parsed anything.
… …
796=back 777=back
797 778
798=head2 LIMITATIONS 779=head2 LIMITATIONS
799 780
800All options that affect decoding are supported, except 781All options that affect decoding are supported, except
801C<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
802work 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
803them 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
804for JSON numbers, however. 785not hold true for JSON numbers, however.
805 786
806For 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
807start 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
808of 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
809takes the conservative route and disallows this case. 790takes the conservative route and disallows this case.
… …
988If 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
989it 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
990a numeric (floating point) value if that is possible without loss of 971a numeric (floating point) value if that is possible without loss of
991precision. Otherwise it will preserve the number as a string value (in 972precision. Otherwise it will preserve the number as a string value (in
992which case you lose roundtripping ability, as the JSON number will be 973which case you lose roundtripping ability, as the JSON number will be
993re-encoded toa JSON string). 974re-encoded to a JSON string).
994 975
995Numbers containing a fractional or exponential part will always be 976Numbers containing a fractional or exponential part will always be
996represented as numeric (floating point) values, possibly at a loss of 977represented as numeric (floating point) values, possibly at a loss of
997precision (in which case you might lose perfect roundtripping ability, but 978precision (in which case you might lose perfect roundtripping ability, but
998the JSON number will still be re-encoded as a JSON number). 979the JSON number will still be re-encoded as a JSON number).
999 980
1000Note that precision is not accuracy - binary floating point values cannot 981Note that precision is not accuracy - binary floating point values cannot
1001represent most decimal fractions exactly, and when converting from and to 982represent most decimal fractions exactly, and when converting from and to
1002floating point, JSON::XS only guarantees precision up to but not including 983floating point, JSON::XS only guarantees precision up to but not including
1003the leats significant bit. 984the least significant bit.
1004 985
1005=item true, false 986=item true, false
1006 987
1007These 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>,
1008respectively. They are overloaded to act almost exactly like the numbers 989respectively. They are overloaded to act almost exactly like the numbers
… …
1024 1005
1025=over 4 1006=over 4
1026 1007
1027=item hash references 1008=item hash references
1028 1009
1029Perl hash references become JSON objects. As there is no inherent ordering 1010Perl hash references become JSON objects. As there is no inherent
1030in hash keys (or JSON objects), they will usually be encoded in a 1011ordering in hash keys (or JSON objects), they will usually be encoded
1031pseudo-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
1032stays 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
1033optionally sort the hash keys (determined by the I<canonical> flag), so 1014serialise to the same JSON text (given same settings and version of
1034the same datastructure will serialise to the same JSON text (given same 1015JSON::XS), but this incurs a runtime overhead and is only rarely useful,
1035settings 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.
1036and is only rarely useful, e.g. when you want to compare some JSON text
1037against another for equality.
1038 1017
1039=item array references 1018=item array references
1040 1019
1041Perl array references become JSON arrays. 1020Perl array references become JSON arrays.
1042 1021
… …
1138=item C<utf8> flag disabled 1117=item C<utf8> flag disabled
1139 1118
1140When 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
1141and expect Unicode strings, that is, characters with high ordinal Unicode 1120and expect Unicode strings, that is, characters with high ordinal Unicode
1142values (> 255) will be encoded as such characters, and likewise such 1121values (> 255) will be encoded as such characters, and likewise such
1143characters 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
1144"(re-)interpreting" them as Unicode codepoints or Unicode characters, 1123"(re-)interpreting" them as Unicode codepoints or Unicode characters,
1145respectively (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
1146funny/weird/dumb stuff). 1125funny/weird/dumb stuff).
1147 1126
1148This 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
… …
1264output for these property strings, e.g.: 1243output for these property strings, e.g.:
1265 1244
1266 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g; 1245 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1267 1246
1268This 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
1269occurence 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.
1270 1249
1271If you know of other incompatibilities, please let me know. 1250If you know of other incompatibilities, please let me know.
1272 1251
1273 1252
1274=head2 JSON and YAML 1253=head2 JSON and YAML
… …
1452 1431
1453Sometimes people avoid the Perl locale support and directly call the 1432Sometimes people avoid the Perl locale support and directly call the
1454system's setlocale function with C<LC_ALL>. 1433system's setlocale function with C<LC_ALL>.
1455 1434
1456This breaks both perl and modules such as JSON::XS, as stringification of 1435This 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 1436numbers 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 1437print C<1>, and JSON::XS might output illegal JSON as JSON::XS relies on
1459perl to stringify numbers). 1438perl to stringify numbers).
1460 1439
1461The solution is simple: don't call C<setlocale>, or use it for only those 1440The 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>. 1441categories you need, such as C<LC_MESSAGES> or C<LC_CTYPE>.

Diff Legend

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