… | |
… | |
32 | primary goal is to be *correct* and its secondary goal is to be *fast*. |
32 | primary goal is to be *correct* and its secondary goal is to be *fast*. |
33 | To reach the latter goal it was written in C. |
33 | To reach the latter goal it was written in C. |
34 | |
34 | |
35 | Beginning with version 2.0 of the JSON module, when both JSON and |
35 | Beginning with version 2.0 of the JSON module, when both JSON and |
36 | JSON::XS are installed, then JSON will fall back on JSON::XS (this can |
36 | JSON::XS are installed, then JSON will fall back on JSON::XS (this can |
37 | be overriden) with no overhead due to emulation (by inheritign |
37 | be overridden) with no overhead due to emulation (by inheriting |
38 | constructor and methods). If JSON::XS is not available, it will fall |
38 | constructor and methods). If JSON::XS is not available, it will fall |
39 | back to the compatible JSON::PP module as backend, so using JSON instead |
39 | back to the compatible JSON::PP module as backend, so using JSON instead |
40 | of JSON::XS gives you a portable JSON API that can be fast when you need |
40 | of JSON::XS gives you a portable JSON API that can be fast when you need |
41 | and doesn't require a C compiler when that is a problem. |
41 | and doesn't require a C compiler when that is a problem. |
42 | |
42 | |
… | |
… | |
57 | This module knows how to handle Unicode, documents how and when it |
57 | This module knows how to handle Unicode, documents how and when it |
58 | does so, and even documents what "correct" means. |
58 | does so, and even documents what "correct" means. |
59 | |
59 | |
60 | * round-trip integrity |
60 | * round-trip integrity |
61 | |
61 | |
62 | When you serialise a perl data structure using only datatypes |
62 | When you serialise a perl data structure using only data types |
63 | supported by JSON, the deserialised data structure is identical on |
63 | supported by JSON, the deserialised data structure is identical on |
64 | the Perl level. (e.g. the string "2.0" doesn't suddenly become "2" |
64 | the Perl level. (e.g. the string "2.0" doesn't suddenly become "2" |
65 | just because it looks like a number). There minor *are* exceptions |
65 | just because it looks like a number). There minor *are* exceptions |
66 | to this, read the MAPPING section below to learn about those. |
66 | to this, read the MAPPING section below to learn about those. |
67 | |
67 | |
… | |
… | |
78 | too. |
78 | too. |
79 | |
79 | |
80 | * simple to use |
80 | * simple to use |
81 | |
81 | |
82 | This module has both a simple functional interface as well as an |
82 | This module has both a simple functional interface as well as an |
83 | objetc oriented interface interface. |
83 | object oriented interface interface. |
84 | |
84 | |
85 | * reasonably versatile output formats |
85 | * reasonably versatile output formats |
86 | |
86 | |
87 | You can choose between the most compact guaranteed-single-line |
87 | You can choose between the most compact guaranteed-single-line |
88 | format possible (nice for simple line-based protocols), a pure-ascii |
88 | format possible (nice for simple line-based protocols), a pure-ASCII |
89 | format (for when your transport is not 8-bit clean, still supports |
89 | format (for when your transport is not 8-bit clean, still supports |
90 | the whole Unicode range), or a pretty-printed format (for when you |
90 | the whole Unicode range), or a pretty-printed format (for when you |
91 | want to read that stuff). Or you can combine those features in |
91 | want to read that stuff). Or you can combine those features in |
92 | whatever way you like. |
92 | whatever way you like. |
93 | |
93 | |
… | |
… | |
101 | |
101 | |
102 | This function call is functionally identical to: |
102 | This function call is functionally identical to: |
103 | |
103 | |
104 | $json_text = JSON::XS->new->utf8->encode ($perl_scalar) |
104 | $json_text = JSON::XS->new->utf8->encode ($perl_scalar) |
105 | |
105 | |
106 | except being faster. |
106 | Except being faster. |
107 | |
107 | |
108 | $perl_scalar = decode_json $json_text |
108 | $perl_scalar = decode_json $json_text |
109 | The opposite of "encode_json": expects an UTF-8 (binary) string and |
109 | The opposite of "encode_json": expects an UTF-8 (binary) string and |
110 | tries to parse that as an UTF-8 encoded JSON text, returning the |
110 | tries to parse that as an UTF-8 encoded JSON text, returning the |
111 | resulting reference. Croaks on error. |
111 | resulting reference. Croaks on error. |
112 | |
112 | |
113 | This function call is functionally identical to: |
113 | This function call is functionally identical to: |
114 | |
114 | |
115 | $perl_scalar = JSON::XS->new->utf8->decode ($json_text) |
115 | $perl_scalar = JSON::XS->new->utf8->decode ($json_text) |
116 | |
116 | |
117 | except being faster. |
117 | Except being faster. |
118 | |
118 | |
119 | $is_boolean = JSON::XS::is_bool $scalar |
119 | $is_boolean = JSON::XS::is_bool $scalar |
120 | Returns true if the passed scalar represents either JSON::XS::true |
120 | Returns true if the passed scalar represents either JSON::XS::true |
121 | or JSON::XS::false, two constants that act like 1 and 0, |
121 | or JSON::XS::false, two constants that act like 1 and 0, |
122 | respectively and are used to represent JSON "true" and "false" |
122 | respectively and are used to represent JSON "true" and "false" |
… | |
… | |
152 | |
152 | |
153 | If you didn't know about that flag, just the better, pretend it |
153 | If you didn't know about that flag, just the better, pretend it |
154 | doesn't exist. |
154 | doesn't exist. |
155 | |
155 | |
156 | 4. A "Unicode String" is simply a string where each character can be |
156 | 4. A "Unicode String" is simply a string where each character can be |
157 | validly interpreted as a Unicode codepoint. |
157 | validly interpreted as a Unicode code point. |
158 | If you have UTF-8 encoded data, it is no longer a Unicode string, |
158 | If you have UTF-8 encoded data, it is no longer a Unicode string, |
159 | but a Unicode string encoded in UTF-8, giving you a binary string. |
159 | but a Unicode string encoded in UTF-8, giving you a binary string. |
160 | |
160 | |
161 | 5. A string containing "high" (> 255) character values is *not* a UTF-8 |
161 | 5. A string containing "high" (> 255) character values is *not* a UTF-8 |
162 | string. |
162 | string. |
… | |
… | |
397 | Example, encode a Perl scalar as JSON value with enabled |
397 | Example, encode a Perl scalar as JSON value with enabled |
398 | "allow_nonref", resulting in an invalid JSON text: |
398 | "allow_nonref", resulting in an invalid JSON text: |
399 | |
399 | |
400 | JSON::XS->new->allow_nonref->encode ("Hello, World!") |
400 | JSON::XS->new->allow_nonref->encode ("Hello, World!") |
401 | => "Hello, World!" |
401 | => "Hello, World!" |
|
|
402 | |
|
|
403 | $json = $json->allow_unknown ([$enable]) |
|
|
404 | $enabled = $json->get_allow_unknown |
|
|
405 | If $enable is true (or missing), then "encode" will *not* throw an |
|
|
406 | exception when it encounters values it cannot represent in JSON (for |
|
|
407 | example, filehandles) but instead will encode a JSON "null" value. |
|
|
408 | Note that blessed objects are not included here and are handled |
|
|
409 | separately by c<allow_nonref>. |
|
|
410 | |
|
|
411 | If $enable is false (the default), then "encode" will throw an |
|
|
412 | exception when it encounters anything it cannot encode as JSON. |
|
|
413 | |
|
|
414 | This option does not affect "decode" in any way, and it is |
|
|
415 | recommended to leave it off unless you know your communications |
|
|
416 | partner. |
402 | |
417 | |
403 | $json = $json->allow_blessed ([$enable]) |
418 | $json = $json->allow_blessed ([$enable]) |
404 | $enabled = $json->get_allow_blessed |
419 | $enabled = $json->get_allow_blessed |
405 | If $enable is true (or missing), then the "encode" method will not |
420 | If $enable is true (or missing), then the "encode" method will not |
406 | barf when it encounters a blessed reference. Instead, the value of |
421 | barf when it encounters a blessed reference. Instead, the value of |
… | |
… | |
541 | saving space. |
556 | saving space. |
542 | |
557 | |
543 | $json = $json->max_depth ([$maximum_nesting_depth]) |
558 | $json = $json->max_depth ([$maximum_nesting_depth]) |
544 | $max_depth = $json->get_max_depth |
559 | $max_depth = $json->get_max_depth |
545 | Sets the maximum nesting level (default 512) accepted while encoding |
560 | Sets the maximum nesting level (default 512) accepted while encoding |
546 | or decoding. If the JSON text or Perl data structure has an equal or |
561 | or decoding. If a higher nesting level is detected in JSON text or a |
547 | higher nesting level then this limit, then the encoder and decoder |
562 | Perl data structure, then the encoder and decoder will stop and |
548 | will stop and croak at that point. |
563 | croak at that point. |
549 | |
564 | |
550 | Nesting level is defined by number of hash- or arrayrefs that the |
565 | Nesting level is defined by number of hash- or arrayrefs that the |
551 | encoder needs to traverse to reach a given point or the number of |
566 | encoder needs to traverse to reach a given point or the number of |
552 | "{" or "[" characters without their matching closing parenthesis |
567 | "{" or "[" characters without their matching closing parenthesis |
553 | crossed to reach a given character in a string. |
568 | crossed to reach a given character in a string. |
554 | |
569 | |
555 | Setting the maximum depth to one disallows any nesting, so that |
570 | Setting the maximum depth to one disallows any nesting, so that |
556 | ensures that the object is only a single hash/object or array. |
571 | ensures that the object is only a single hash/object or array. |
557 | |
572 | |
558 | The argument to "max_depth" will be rounded up to the next highest |
|
|
559 | power of two. If no argument is given, the highest possible setting |
573 | If no argument is given, the highest possible setting will be used, |
560 | will be used, which is rarely useful. |
574 | which is rarely useful. |
|
|
575 | |
|
|
576 | Note that nesting is implemented by recursion in C. The default |
|
|
577 | value has been chosen to be as large as typical operating systems |
|
|
578 | allow without crashing. |
561 | |
579 | |
562 | See SECURITY CONSIDERATIONS, below, for more info on why this is |
580 | See SECURITY CONSIDERATIONS, below, for more info on why this is |
563 | useful. |
581 | useful. |
564 | |
582 | |
565 | $json = $json->max_size ([$maximum_string_size]) |
583 | $json = $json->max_size ([$maximum_string_size]) |
566 | $max_size = $json->get_max_size |
584 | $max_size = $json->get_max_size |
567 | Set the maximum length a JSON text may have (in bytes) where |
585 | Set the maximum length a JSON text may have (in bytes) where |
568 | decoding is being attempted. The default is 0, meaning no limit. |
586 | decoding is being attempted. The default is 0, meaning no limit. |
569 | When "decode" is called on a string longer then this number of |
587 | When "decode" is called on a string that is longer then this many |
570 | characters it will not attempt to decode the string but throw an |
588 | bytes, it will not attempt to decode the string but throw an |
571 | exception. This setting has no effect on "encode" (yet). |
589 | exception. This setting has no effect on "encode" (yet). |
572 | |
590 | |
573 | The argument to "max_size" will be rounded up to the next highest |
|
|
574 | power of two (so may be more than requested). If no argument is |
|
|
575 | given, the limit check will be deactivated (same as when 0 is |
591 | If no argument is given, the limit check will be deactivated (same |
576 | specified). |
592 | as when 0 is specified). |
577 | |
593 | |
578 | See SECURITY CONSIDERATIONS, below, for more info on why this is |
594 | See SECURITY CONSIDERATIONS, below, for more info on why this is |
579 | useful. |
595 | useful. |
580 | |
596 | |
581 | $json_text = $json->encode ($perl_scalar) |
597 | $json_text = $json->encode ($perl_scalar) |
… | |
… | |
607 | |
623 | |
608 | JSON::XS->new->decode_prefix ("[1] the tail") |
624 | JSON::XS->new->decode_prefix ("[1] the tail") |
609 | => ([], 3) |
625 | => ([], 3) |
610 | |
626 | |
611 | INCREMENTAL PARSING |
627 | INCREMENTAL PARSING |
612 | [This section and the API it details is still EXPERIMENTAL] |
|
|
613 | |
|
|
614 | In some cases, there is the need for incremental parsing of JSON texts. |
628 | In some cases, there is the need for incremental parsing of JSON texts. |
615 | While this module always has to keep both JSON text and resulting Perl |
629 | While this module always has to keep both JSON text and resulting Perl |
616 | data structure in memory at one time, it does allow you to parse a JSON |
630 | data structure in memory at one time, it does allow you to parse a JSON |
617 | stream incrementally. It does so by accumulating text until it has a |
631 | stream incrementally. It does so by accumulating text until it has a |
618 | full JSON object, which it then can decode. This process is similar to |
632 | full JSON object, which it then can decode. This process is similar to |
619 | using "decode_prefix" to see if a full JSON object is available, but is |
633 | using "decode_prefix" to see if a full JSON object is available, but is |
620 | much more efficient (JSON::XS will only attempt to parse the JSON text |
634 | much more efficient (and can be implemented with a minimum of method |
621 | once it is sure it has enough text to get a decisive result, using a |
635 | calls). |
622 | very simple but truly incremental parser). |
|
|
623 | |
636 | |
624 | The following two methods deal with this. |
637 | JSON::XS will only attempt to parse the JSON text once it is sure it has |
|
|
638 | enough text to get a decisive result, using a very simple but truly |
|
|
639 | incremental parser. This means that it sometimes won't stop as early as |
|
|
640 | the full parser, for example, it doesn't detect parenthese mismatches. |
|
|
641 | The only thing it guarantees is that it starts decoding as soon as a |
|
|
642 | syntactically valid JSON text has been seen. This means you need to set |
|
|
643 | resource limits (e.g. "max_size") to ensure the parser will stop parsing |
|
|
644 | in the presence if syntax errors. |
|
|
645 | |
|
|
646 | The following methods implement this incremental parser. |
625 | |
647 | |
626 | [void, scalar or list context] = $json->incr_parse ([$string]) |
648 | [void, scalar or list context] = $json->incr_parse ([$string]) |
627 | This is the central parsing function. It can both append new text |
649 | This is the central parsing function. It can both append new text |
628 | and extract objects from the stream accumulated so far (both of |
650 | and extract objects from the stream accumulated so far (both of |
629 | these functions are optional). |
651 | these functions are optional). |
… | |
… | |
668 | This will reset the state of the incremental parser and will remove |
690 | This will reset the state of the incremental parser and will remove |
669 | the parsed text from the input buffer. This is useful after |
691 | the parsed text from the input buffer. This is useful after |
670 | "incr_parse" died, in which case the input buffer and incremental |
692 | "incr_parse" died, in which case the input buffer and incremental |
671 | parser state is left unchanged, to skip the text parsed so far and |
693 | parser state is left unchanged, to skip the text parsed so far and |
672 | to reset the parse state. |
694 | to reset the parse state. |
|
|
695 | |
|
|
696 | $json->incr_reset |
|
|
697 | This completely resets the incremental parser, that is, after this |
|
|
698 | call, it will be as if the parser had never parsed anything. |
|
|
699 | |
|
|
700 | This is useful if you want ot repeatedly parse JSON objects and want |
|
|
701 | to ignore any trailing data, which means you have to reset the |
|
|
702 | parser after each successful decode. |
673 | |
703 | |
674 | LIMITATIONS |
704 | LIMITATIONS |
675 | All options that affect decoding are supported, except "allow_nonref". |
705 | All options that affect decoding are supported, except "allow_nonref". |
676 | The reason for this is that it cannot be made to work sensibly: JSON |
706 | The reason for this is that it cannot be made to work sensibly: JSON |
677 | objects and arrays are self-delimited, i.e. you can concatenate them |
707 | objects and arrays are self-delimited, i.e. you can concatenate them |
… | |
… | |
897 | an exception to be thrown, except for references to the integers 0 |
927 | an exception to be thrown, except for references to the integers 0 |
898 | and 1, which get turned into "false" and "true" atoms in JSON. You |
928 | and 1, which get turned into "false" and "true" atoms in JSON. You |
899 | can also use "JSON::XS::false" and "JSON::XS::true" to improve |
929 | can also use "JSON::XS::false" and "JSON::XS::true" to improve |
900 | readability. |
930 | readability. |
901 | |
931 | |
902 | encode_json [\0,JSON::XS::true] # yields [false,true] |
932 | encode_json [\0, JSON::XS::true] # yields [false,true] |
903 | |
933 | |
904 | JSON::XS::true, JSON::XS::false |
934 | JSON::XS::true, JSON::XS::false |
905 | These special values become JSON true and JSON false values, |
935 | These special values become JSON true and JSON false values, |
906 | respectively. You can also use "\1" and "\0" directly if you want. |
936 | respectively. You can also use "\1" and "\0" directly if you want. |
907 | |
937 | |
… | |
… | |
1097 | |
1127 | |
1098 | First comes a comparison between various modules using a very short |
1128 | First comes a comparison between various modules using a very short |
1099 | single-line JSON string (also available at |
1129 | single-line JSON string (also available at |
1100 | <http://dist.schmorp.de/misc/json/short.json>). |
1130 | <http://dist.schmorp.de/misc/json/short.json>). |
1101 | |
1131 | |
1102 | {"method": "handleMessage", "params": ["user1", "we were just talking"], \ |
1132 | {"method": "handleMessage", "params": ["user1", |
1103 | "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]} |
1133 | "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7, |
|
|
1134 | true, false]} |
1104 | |
1135 | |
1105 | It shows the number of encodes/decodes per second (JSON::XS uses the |
1136 | It shows the number of encodes/decodes per second (JSON::XS uses the |
1106 | functional interface, while JSON::XS/2 uses the OO interface with |
1137 | functional interface, while JSON::XS/2 uses the OO interface with |
1107 | pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink). |
1138 | pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink). |
1108 | Higher is better: |
1139 | Higher is better: |
… | |
… | |
1201 | |
1232 | |
1202 | (It might actually work, but you have been warned). |
1233 | (It might actually work, but you have been warned). |
1203 | |
1234 | |
1204 | BUGS |
1235 | BUGS |
1205 | While the goal of this module is to be correct, that unfortunately does |
1236 | While the goal of this module is to be correct, that unfortunately does |
1206 | not mean it's bug-free, only that I think its design is bug-free. It is |
1237 | not mean it's bug-free, only that I think its design is bug-free. If you |
1207 | still relatively early in its development. If you keep reporting bugs |
|
|
1208 | they will be fixed swiftly, though. |
1238 | keep reporting bugs they will be fixed swiftly, though. |
1209 | |
1239 | |
1210 | Please refrain from using rt.cpan.org or any other bug reporting |
1240 | Please refrain from using rt.cpan.org or any other bug reporting |
1211 | service. I put the contact address into my modules for a reason. |
1241 | service. I put the contact address into my modules for a reason. |
1212 | |
1242 | |
1213 | SEE ALSO |
1243 | SEE ALSO |