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