… | |
… | |
676 | can then use "incr_skip" to skip the erroneous part). This is the |
676 | can then use "incr_skip" to skip the erroneous part). This is the |
677 | most common way of using the method. |
677 | most common way of using the method. |
678 | |
678 | |
679 | And finally, in list context, it will try to extract as many objects |
679 | And finally, in list context, it will try to extract as many objects |
680 | from the stream as it can find and return them, or the empty list |
680 | from the stream as it can find and return them, or the empty list |
681 | otherwise. For this to work, there must be no separators between the |
681 | otherwise. For this to work, there must be no separators (other than |
682 | JSON objects or arrays, instead they must be concatenated |
682 | whitespace) between the JSON objects or arrays, instead they must be |
683 | back-to-back. If an error occurs, an exception will be raised as in |
683 | concatenated back-to-back. If an error occurs, an exception will be |
684 | the scalar context case. Note that in this case, any |
684 | raised as in the scalar context case. Note that in this case, any |
685 | previously-parsed JSON texts will be lost. |
685 | previously-parsed JSON texts will be lost. |
686 | |
686 | |
687 | Example: Parse some JSON arrays/objects in a given string and return |
687 | Example: Parse some JSON arrays/objects in a given string and return |
688 | them. |
688 | them. |
689 | |
689 | |
… | |
… | |
696 | object. Under all other circumstances you must not call this |
696 | object. Under all other circumstances you must not call this |
697 | function (I mean it. although in simple tests it might actually |
697 | function (I mean it. although in simple tests it might actually |
698 | work, it *will* fail under real world conditions). As a special |
698 | work, it *will* fail under real world conditions). As a special |
699 | exception, you can also call this method before having parsed |
699 | exception, you can also call this method before having parsed |
700 | anything. |
700 | anything. |
|
|
701 | |
|
|
702 | That means you can only use this function to look at or manipulate |
|
|
703 | text before or after complete JSON objects, not while the parser is |
|
|
704 | in the middle of parsing a JSON object. |
701 | |
705 | |
702 | This function is useful in two cases: a) finding the trailing text |
706 | This function is useful in two cases: a) finding the trailing text |
703 | after a JSON object or b) parsing multiple JSON objects separated by |
707 | after a JSON object or b) parsing multiple JSON objects separated by |
704 | non-JSON text (such as commas). |
708 | non-JSON text (such as commas). |
705 | |
709 | |
… | |
… | |
1481 | ensure that future versions are safe. |
1485 | ensure that future versions are safe. |
1482 | |
1486 | |
1483 | INTEROPERABILITY WITH OTHER MODULES |
1487 | INTEROPERABILITY WITH OTHER MODULES |
1484 | "JSON::XS" uses the Types::Serialiser module to provide boolean |
1488 | "JSON::XS" uses the Types::Serialiser module to provide boolean |
1485 | constants. That means that the JSON true and false values will be |
1489 | constants. That means that the JSON true and false values will be |
1486 | comaptible to true and false values of iother modules that do the same, |
1490 | comaptible to true and false values of other modules that do the same, |
1487 | such as JSON::PP and CBOR::XS. |
1491 | such as JSON::PP and CBOR::XS. |
1488 | |
1492 | |
1489 | INTEROPERABILITY WITH OTHER JSON DECODERS |
1493 | INTEROPERABILITY WITH OTHER JSON DECODERS |
1490 | As long as you only serialise data that can be directly expressed in |
1494 | As long as you only serialise data that can be directly expressed in |
1491 | JSON, "JSON::XS" is incapable of generating invalid JSON output (modulo |
1495 | JSON, "JSON::XS" is incapable of generating invalid JSON output (modulo |
… | |
… | |
1505 | TAGGED VALUE SYNTAX AND STANDARD JSON EN/DECODERS |
1509 | TAGGED VALUE SYNTAX AND STANDARD JSON EN/DECODERS |
1506 | When you use "allow_tags" to use the extended (and also nonstandard and |
1510 | When you use "allow_tags" to use the extended (and also nonstandard and |
1507 | invalid) JSON syntax for serialised objects, and you still want to |
1511 | invalid) JSON syntax for serialised objects, and you still want to |
1508 | decode the generated When you want to serialise objects, you can run a |
1512 | decode the generated When you want to serialise objects, you can run a |
1509 | regex to replace the tagged syntax by standard JSON arrays (it only |
1513 | regex to replace the tagged syntax by standard JSON arrays (it only |
1510 | works for "normal" packagesnames without comma, newlines or single |
1514 | works for "normal" package names without comma, newlines or single |
1511 | colons). First, the readable Perl version: |
1515 | colons). First, the readable Perl version: |
1512 | |
1516 | |
1513 | # if your FREEZE methods return no values, you need this replace first: |
1517 | # if your FREEZE methods return no values, you need this replace first: |
1514 | $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[\s*\]/[$1]/gx; |
1518 | $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[\s*\]/[$1]/gx; |
1515 | |
1519 | |
… | |
… | |
1549 | Since this module was written, Google has written a new JSON RFC, RFC |
1553 | Since this module was written, Google has written a new JSON RFC, RFC |
1550 | 7159 (and RFC7158). Unfortunately, this RFC breaks compatibility with |
1554 | 7159 (and RFC7158). Unfortunately, this RFC breaks compatibility with |
1551 | both the original JSON specification on www.json.org and RFC4627. |
1555 | both the original JSON specification on www.json.org and RFC4627. |
1552 | |
1556 | |
1553 | As far as I can see, you can get partial compatibility when parsing by |
1557 | As far as I can see, you can get partial compatibility when parsing by |
1554 | using "->allow_nonref". However, consider thew security implications of |
1558 | using "->allow_nonref". However, consider the security implications of |
1555 | doing so. |
1559 | doing so. |
1556 | |
1560 | |
1557 | I haven't decided yet when to break compatibility with RFC4627 by |
1561 | I haven't decided yet when to break compatibility with RFC4627 by |
1558 | default (and potentially leave applications insecure) and change the |
1562 | default (and potentially leave applications insecure) and change the |
1559 | default to follow RFC7159, but application authors are well advised to |
1563 | default to follow RFC7159, but application authors are well advised to |
1560 | call "->allow_nonref(0)" even if this is the current default, if they |
1564 | call "->allow_nonref(0)" even if this is the current default, if they |
1561 | cannot handle non-reference values, in preparation for the day when the4 |
1565 | cannot handle non-reference values, in preparation for the day when the |
1562 | default will change. |
1566 | default will change. |
1563 | |
1567 | |
1564 | THREADS |
1568 | THREADS |
1565 | This module is *not* guaranteed to be thread safe and there are no plans |
1569 | This module is *not* guaranteed to be thread safe and there are no plans |
1566 | to change this until Perl gets thread support (as opposed to the |
1570 | to change this until Perl gets thread support (as opposed to the |