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.140 by root, Thu Jun 27 11:45:17 2013 UTC vs.
Revision 1.143 by root, Fri Oct 25 20:02:54 2013 UTC

… …
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
… …
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.
… …
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

Diff Legend

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