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.158 by root, Thu Sep 1 11:38:39 2016 UTC vs.
Revision 1.165 by root, Tue Sep 5 13:07:09 2017 UTC

… …
40Beginning with version 2.0 of the JSON module, when both JSON and 40Beginning with version 2.0 of the JSON module, when both JSON and
41JSON::XS are installed, then JSON will fall back on JSON::XS (this can be 41JSON::XS are installed, then JSON will fall back on JSON::XS (this can be
42overridden) with no overhead due to emulation (by inheriting constructor 42overridden) with no overhead due to emulation (by inheriting constructor
43and methods). If JSON::XS is not available, it will fall back to the 43and methods). If JSON::XS is not available, it will fall back to the
44compatible JSON::PP module as backend, so using JSON instead of JSON::XS 44compatible JSON::PP module as backend, so using JSON instead of JSON::XS
45gives you a portable JSON API that can be fast when you need and doesn't 45gives you a portable JSON API that can be fast when you need it and
46require a C compiler when that is a problem. 46doesn't require a C compiler when that is a problem.
47 47
48As this is the n-th-something JSON module on CPAN, what was the reason 48As this is the n-th-something JSON module on CPAN, what was the reason
49to write yet another JSON module? While it seems there are many JSON 49to write yet another JSON module? While it seems there are many JSON
50modules, none of them correctly handle all corner cases, and in most cases 50modules, none of them correctly handle all corner cases, and in most cases
51their maintainers are unresponsive, gone missing, or not listening to bug 51their maintainers are unresponsive, gone missing, or not listening to bug
… …
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.04;
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;
… …
131 131
132Except being faster. 132Except being faster.
133 133
134=item $perl_scalar = decode_json $json_text 134=item $perl_scalar = decode_json $json_text
135 135
136The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries 136The opposite of C<encode_json>: expects a UTF-8 (binary) string and tries
137to parse that as an UTF-8 encoded JSON text, returning the resulting 137to parse that as a UTF-8 encoded JSON text, returning the resulting
138reference. Croaks on error. 138reference. Croaks on error.
139 139
140This function call is functionally identical to: 140This function call is functionally identical to:
141 141
142 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 142 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
… …
270 270
271=item $enabled = $json->get_utf8 271=item $enabled = $json->get_utf8
272 272
273If C<$enable> is true (or missing), then the C<encode> method will encode 273If C<$enable> is true (or missing), then the C<encode> method will encode
274the JSON result into UTF-8, as required by many protocols, while the 274the JSON result into UTF-8, as required by many protocols, while the
275C<decode> method expects to be handled an UTF-8-encoded string. Please 275C<decode> method expects to be handed a UTF-8-encoded string. Please
276note that UTF-8-encoded strings do not contain any characters outside the 276note that UTF-8-encoded strings do not contain any characters outside the
277range C<0..255>, they are thus useful for bytewise/binary I/O. In future 277range C<0..255>, they are thus useful for bytewise/binary I/O. In future
278versions, enabling this option might enable autodetection of the UTF-16 278versions, enabling this option might enable autodetection of the UTF-16
279and UTF-32 encoding families, as described in RFC4627. 279and UTF-32 encoding families, as described in RFC4627.
280 280
… …
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 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.
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
778=item $json->incr_skip 782=item $json->incr_skip
… …
1285expect your input strings to be encoded as UTF-8, that is, no "character" 1289expect your input strings to be encoded as UTF-8, that is, no "character"
1286of the input string must have any value > 255, as UTF-8 does not allow 1290of the input string must have any value > 255, as UTF-8 does not allow
1287that. 1291that.
1288 1292
1289The C<utf8> flag therefore switches between two modes: disabled means you 1293The C<utf8> flag therefore switches between two modes: disabled means you
1290will get a Unicode string in Perl, enabled means you get an UTF-8 encoded 1294will get a Unicode string in Perl, enabled means you get a UTF-8 encoded
1291octet/binary string in Perl. 1295octet/binary string in Perl.
1292 1296
1293=item C<latin1> or C<ascii> flags enabled 1297=item C<latin1> or C<ascii> flags enabled
1294 1298
1295With C<latin1> (or C<ascii>) enabled, C<encode> will escape characters 1299With C<latin1> (or C<ascii>) enabled, C<encode> will escape characters
… …
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 (I-)THREADS
1698 1702
1699This module is I<not> guaranteed to be thread safe and there are no 1703This module is I<not> guaranteed to be ithread (or MULTIPLICITY-) safe
1700plans to change this until Perl gets thread support (as opposed to the 1704and there are no plans to change this. Note that perl's builtin so-called
1701horribly slow so-called "threads" which are simply slow and bloated 1705theeads/ithreads are officially deprecated and should not be used.
1702process simulations - use fork, it's I<much> faster, cheaper, better).
1703
1704(It might actually work, but you have been warned).
1705 1706
1706 1707
1707=head1 THE PERILS OF SETLOCALE 1708=head1 THE PERILS OF SETLOCALE
1708 1709
1709Sometimes people avoid the Perl locale support and directly call the 1710Sometimes people avoid the Perl locale support and directly call the

Diff Legend

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