… | |
… | |
49 | to write yet another JSON module? While it seems there are many JSON |
49 | to write yet another JSON module? While it seems there are many JSON |
50 | modules, none of them correctly handle all corner cases, and in most cases |
50 | modules, none of them correctly handle all corner cases, and in most cases |
51 | their maintainers are unresponsive, gone missing, or not listening to bug |
51 | their maintainers are unresponsive, gone missing, or not listening to bug |
52 | reports for other reasons. |
52 | reports for other reasons. |
53 | |
53 | |
54 | See COMPARISON, below, for a comparison to some other JSON modules. |
|
|
55 | |
|
|
56 | See MAPPING, below, on how JSON::XS maps perl values to JSON values and |
54 | See MAPPING, below, on how JSON::XS maps perl values to JSON values and |
57 | vice versa. |
55 | vice versa. |
58 | |
56 | |
59 | =head2 FEATURES |
57 | =head2 FEATURES |
60 | |
58 | |
… | |
… | |
101 | |
99 | |
102 | =cut |
100 | =cut |
103 | |
101 | |
104 | package JSON::XS; |
102 | package JSON::XS; |
105 | |
103 | |
|
|
104 | no warnings; |
106 | use strict; |
105 | use strict; |
107 | |
106 | |
108 | our $VERSION = '2.2'; |
107 | our $VERSION = '2.231'; |
109 | our @ISA = qw(Exporter); |
108 | our @ISA = qw(Exporter); |
110 | |
109 | |
111 | our @EXPORT = qw(encode_json decode_json to_json from_json); |
110 | our @EXPORT = qw(encode_json decode_json to_json from_json); |
112 | |
111 | |
113 | sub to_json($) { |
112 | sub to_json($) { |
… | |
… | |
706 | In some cases, there is the need for incremental parsing of JSON |
705 | In some cases, there is the need for incremental parsing of JSON |
707 | texts. While this module always has to keep both JSON text and resulting |
706 | texts. While this module always has to keep both JSON text and resulting |
708 | Perl data structure in memory at one time, it does allow you to parse a |
707 | Perl data structure in memory at one time, it does allow you to parse a |
709 | JSON stream incrementally. It does so by accumulating text until it has |
708 | JSON stream incrementally. It does so by accumulating text until it has |
710 | a full JSON object, which it then can decode. This process is similar to |
709 | a full JSON object, which it then can decode. This process is similar to |
711 | using C<decode_prefix> to see if a full JSON object is available, but is |
710 | using C<decode_prefix> to see if a full JSON object is available, but |
712 | much more efficient (JSON::XS will only attempt to parse the JSON text |
711 | is much more efficient (and can be implemented with a minimum of method |
|
|
712 | calls). |
|
|
713 | |
|
|
714 | JSON::XS will only attempt to parse the JSON text once it is sure it |
713 | once it is sure it has enough text to get a decisive result, using a very |
715 | has enough text to get a decisive result, using a very simple but |
714 | simple but truly incremental parser). |
716 | truly incremental parser. This means that it sometimes won't stop as |
|
|
717 | early as the full parser, for example, it doesn't detect parenthese |
|
|
718 | mismatches. The only thing it guarantees is that it starts decoding as |
|
|
719 | soon as a syntactically valid JSON text has been seen. This means you need |
|
|
720 | to set resource limits (e.g. C<max_size>) to ensure the parser will stop |
|
|
721 | parsing in the presence if syntax errors. |
715 | |
722 | |
716 | The following two methods deal with this. |
723 | The following methods implement this incremental parser. |
717 | |
724 | |
718 | =over 4 |
725 | =over 4 |
719 | |
726 | |
720 | =item [void, scalar or list context] = $json->incr_parse ([$string]) |
727 | =item [void, scalar or list context] = $json->incr_parse ([$string]) |
721 | |
728 | |
… | |
… | |
759 | JSON object or b) parsing multiple JSON objects separated by non-JSON text |
766 | JSON object or b) parsing multiple JSON objects separated by non-JSON text |
760 | (such as commas). |
767 | (such as commas). |
761 | |
768 | |
762 | =item $json->incr_skip |
769 | =item $json->incr_skip |
763 | |
770 | |
764 | This will reset the state of the incremental parser and will remove the |
771 | This will reset the state of the incremental parser and will remove |
765 | parsed text from the input buffer. This is useful after C<incr_parse> |
772 | the parsed text from the input buffer so far. This is useful after |
766 | died, in which case the input buffer and incremental parser state is left |
773 | C<incr_parse> died, in which case the input buffer and incremental parser |
767 | unchanged, to skip the text parsed so far and to reset the parse state. |
774 | state is left unchanged, to skip the text parsed so far and to reset the |
|
|
775 | parse state. |
|
|
776 | |
|
|
777 | The difference to C<incr_reset> is that only text until the parse error |
|
|
778 | occured is removed. |
|
|
779 | |
|
|
780 | =item $json->incr_reset |
|
|
781 | |
|
|
782 | This completely resets the incremental parser, that is, after this call, |
|
|
783 | it will be as if the parser had never parsed anything. |
|
|
784 | |
|
|
785 | This is useful if you want to repeatedly parse JSON objects and want to |
|
|
786 | ignore any trailing data, which means you have to reset the parser after |
|
|
787 | each successful decode. |
768 | |
788 | |
769 | =back |
789 | =back |
770 | |
790 | |
771 | =head2 LIMITATIONS |
791 | =head2 LIMITATIONS |
772 | |
792 | |