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.157 by root, Fri Feb 26 21:46:45 2016 UTC vs.
Revision 1.161 by root, Wed Nov 16 19:21:53 2016 UTC

… …
101 101
102package JSON::XS; 102package JSON::XS;
103 103
104use common::sense; 104use common::sense;
105 105
106our $VERSION = 3.02; 106our $VERSION = 3.03;
107our @ISA = qw(Exporter); 107our @ISA = qw(Exporter);
108 108
109our @EXPORT = qw(encode_json decode_json); 109our @EXPORT = qw(encode_json decode_json);
110 110
111use Exporter; 111use Exporter;
… …
748C<incr_skip> to skip the erroneous part). This is the most common way of 748C<incr_skip> to skip the erroneous part). This is the most common way of
749using the method. 749using the method.
750 750
751And finally, in list context, it will try to extract as many objects 751And finally, in list context, it will try to extract as many objects
752from the stream as it can find and return them, or the empty list 752from the stream as it can find and return them, or the empty list
753otherwise. For this to work, there must be no separators between the JSON 753otherwise. For this to work, there must be no separators (other than
754objects or arrays, instead they must be concatenated back-to-back. If 754whitespace) between the JSON objects or arrays, instead they must be
755an error occurs, an exception will be raised as in the scalar context 755concatenated back-to-back. If an error occurs, an exception will be
756case. Note that in this case, any previously-parsed JSON texts will be 756raised as in the scalar context case. Note that in this case, any
757lost. 757previously-parsed JSON texts will be lost.
758 758
759Example: Parse some JSON arrays/objects in a given string and return 759Example: Parse some JSON arrays/objects in a given string and return
760them. 760them.
761 761
762 my @objs = JSON::XS->new->incr_parse ("[5][7][1,2]"); 762 my @objs = JSON::XS->new->incr_parse ("[5][7][1,2]");
… …
768C<incr_parse> in I<scalar context> successfully returned an object. Under 768C<incr_parse> in I<scalar context> successfully returned an object. Under
769all other circumstances you must not call this function (I mean it. 769all other circumstances you must not call this function (I mean it.
770although in simple tests it might actually work, it I<will> fail under 770although in simple tests it might actually work, it I<will> fail under
771real world conditions). As a special exception, you can also call this 771real world conditions). As a special exception, you can also call this
772method before having parsed anything. 772method before having parsed anything.
773
774That means you can only use this function to look at or manipulate text
775before or after complete JSON objects, not while the parser is in the
776middle of parsing a JSON object.
773 777
774This function is useful in two cases: a) finding the trailing text after a 778This function is useful in two cases: a) finding the trailing text after a
775JSON object or b) parsing multiple JSON objects separated by non-JSON text 779JSON object or b) parsing multiple JSON objects separated by non-JSON text
776(such as commas). 780(such as commas).
777 781
… …
1608 1612
1609=head1 INTEROPERABILITY WITH OTHER MODULES 1613=head1 INTEROPERABILITY WITH OTHER MODULES
1610 1614
1611C<JSON::XS> uses the L<Types::Serialiser> module to provide boolean 1615C<JSON::XS> uses the L<Types::Serialiser> module to provide boolean
1612constants. That means that the JSON true and false values will be 1616constants. That means that the JSON true and false values will be
1613comaptible to true and false values of iother modules that do the same, 1617comaptible to true and false values of other modules that do the same,
1614such as L<JSON::PP> and L<CBOR::XS>. 1618such as L<JSON::PP> and L<CBOR::XS>.
1615 1619
1616 1620
1617=head1 INTEROPERABILITY WITH OTHER JSON DECODERS 1621=head1 INTEROPERABILITY WITH OTHER JSON DECODERS
1618 1622
… …
1635 1639
1636When you use C<allow_tags> to use the extended (and also nonstandard and 1640When you use C<allow_tags> to use the extended (and also nonstandard and
1637invalid) JSON syntax for serialised objects, and you still want to decode 1641invalid) JSON syntax for serialised objects, and you still want to decode
1638the generated When you want to serialise objects, you can run a regex 1642the generated When you want to serialise objects, you can run a regex
1639to replace the tagged syntax by standard JSON arrays (it only works for 1643to replace the tagged syntax by standard JSON arrays (it only works for
1640"normal" packagesnames without comma, newlines or single colons). First, 1644"normal" package names without comma, newlines or single colons). First,
1641the readable Perl version: 1645the readable Perl version:
1642 1646
1643 # if your FREEZE methods return no values, you need this replace first: 1647 # if your FREEZE methods return no values, you need this replace first:
1644 $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[\s*\]/[$1]/gx; 1648 $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[\s*\]/[$1]/gx;
1645 1649
… …
1681Since this module was written, Google has written a new JSON RFC, RFC 7159 1685Since this module was written, Google has written a new JSON RFC, RFC 7159
1682(and RFC7158). Unfortunately, this RFC breaks compatibility with both the 1686(and RFC7158). Unfortunately, this RFC breaks compatibility with both the
1683original JSON specification on www.json.org and RFC4627. 1687original JSON specification on www.json.org and RFC4627.
1684 1688
1685As far as I can see, you can get partial compatibility when parsing by 1689As far as I can see, you can get partial compatibility when parsing by
1686using C<< ->allow_nonref >>. However, consider thew security implications 1690using C<< ->allow_nonref >>. However, consider the security implications
1687of doing so. 1691of doing so.
1688 1692
1689I haven't decided yet when to break compatibility with RFC4627 by default 1693I haven't decided yet when to break compatibility with RFC4627 by default
1690(and potentially leave applications insecure) and change the default to 1694(and potentially leave applications insecure) and change the default to
1691follow RFC7159, but application authors are well advised to call C<< 1695follow RFC7159, but application authors are well advised to call C<<
1692->allow_nonref(0) >> even if this is the current default, if they cannot 1696->allow_nonref(0) >> even if this is the current default, if they cannot
1693handle non-reference values, in preparation for the day when the4 default 1697handle non-reference values, in preparation for the day when the default
1694will change. 1698will change.
1695 1699
1696 1700
1697=head1 THREADS 1701=head1 THREADS
1698 1702

Diff Legend

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