| … | |
… | |
| 43 | As this is the n-th-something JSON module on CPAN, what was the reason |
43 | As this is the n-th-something JSON module on CPAN, what was the reason |
| 44 | to write yet another JSON module? While it seems there are many JSON |
44 | to write yet another JSON module? While it seems there are many JSON |
| 45 | modules, none of them correctly handle all corner cases, and in most |
45 | modules, none of them correctly handle all corner cases, and in most |
| 46 | cases their maintainers are unresponsive, gone missing, or not listening |
46 | cases their maintainers are unresponsive, gone missing, or not listening |
| 47 | to bug reports for other reasons. |
47 | to bug reports for other reasons. |
| 48 | |
|
|
| 49 | See COMPARISON, below, for a comparison to some other JSON modules. |
|
|
| 50 | |
48 | |
| 51 | See MAPPING, below, on how JSON::XS maps perl values to JSON values and |
49 | See MAPPING, below, on how JSON::XS maps perl values to JSON values and |
| 52 | vice versa. |
50 | vice versa. |
| 53 | |
51 | |
| 54 | FEATURES |
52 | FEATURES |
| … | |
… | |
| 629 | While this module always has to keep both JSON text and resulting Perl |
627 | While this module always has to keep both JSON text and resulting Perl |
| 630 | data structure in memory at one time, it does allow you to parse a JSON |
628 | data structure in memory at one time, it does allow you to parse a JSON |
| 631 | stream incrementally. It does so by accumulating text until it has a |
629 | stream incrementally. It does so by accumulating text until it has a |
| 632 | full JSON object, which it then can decode. This process is similar to |
630 | full JSON object, which it then can decode. This process is similar to |
| 633 | using "decode_prefix" to see if a full JSON object is available, but is |
631 | using "decode_prefix" to see if a full JSON object is available, but is |
| 634 | much more efficient (JSON::XS will only attempt to parse the JSON text |
632 | much more efficient (and can be implemented with a minimum of method |
| 635 | once it is sure it has enough text to get a decisive result, using a |
633 | calls). |
| 636 | very simple but truly incremental parser). |
|
|
| 637 | |
634 | |
| 638 | The following two methods deal with this. |
635 | JSON::XS will only attempt to parse the JSON text once it is sure it has |
|
|
636 | enough text to get a decisive result, using a very simple but truly |
|
|
637 | incremental parser. This means that it sometimes won't stop as early as |
|
|
638 | the full parser, for example, it doesn't detect parenthese mismatches. |
|
|
639 | The only thing it guarantees is that it starts decoding as soon as a |
|
|
640 | syntactically valid JSON text has been seen. This means you need to set |
|
|
641 | resource limits (e.g. "max_size") to ensure the parser will stop parsing |
|
|
642 | in the presence if syntax errors. |
|
|
643 | |
|
|
644 | The following methods implement this incremental parser. |
| 639 | |
645 | |
| 640 | [void, scalar or list context] = $json->incr_parse ([$string]) |
646 | [void, scalar or list context] = $json->incr_parse ([$string]) |
| 641 | This is the central parsing function. It can both append new text |
647 | This is the central parsing function. It can both append new text |
| 642 | and extract objects from the stream accumulated so far (both of |
648 | and extract objects from the stream accumulated so far (both of |
| 643 | these functions are optional). |
649 | these functions are optional). |
