… | |
… | |
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. |
… | |
… | |
623 | |
623 | |
624 | JSON::XS->new->decode_prefix ("[1] the tail") |
624 | JSON::XS->new->decode_prefix ("[1] the tail") |
625 | => ([], 3) |
625 | => ([], 3) |
626 | |
626 | |
627 | INCREMENTAL PARSING |
627 | INCREMENTAL PARSING |
628 | [This section and the API it details is still EXPERIMENTAL] |
|
|
629 | |
|
|
630 | 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. |
631 | 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 |
632 | 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 |
633 | 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 |
634 | 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 |
… | |
… | |
684 | This will reset the state of the incremental parser and will remove |
682 | This will reset the state of the incremental parser and will remove |
685 | the parsed text from the input buffer. This is useful after |
683 | the parsed text from the input buffer. This is useful after |
686 | "incr_parse" died, in which case the input buffer and incremental |
684 | "incr_parse" died, in which case the input buffer and incremental |
687 | parser state is left unchanged, to skip the text parsed so far and |
685 | parser state is left unchanged, to skip the text parsed so far and |
688 | to reset the parse state. |
686 | to reset the parse state. |
|
|
687 | |
|
|
688 | $json->incr_reset |
|
|
689 | This completely resets the incremental parser, that is, after this |
|
|
690 | call, it will be as if the parser had never parsed anything. |
|
|
691 | |
|
|
692 | This is useful if you want ot repeatedly parse JSON objects and want |
|
|
693 | to ignore any trailing data, which means you have to reset the |
|
|
694 | parser after each successful decode. |
689 | |
695 | |
690 | LIMITATIONS |
696 | LIMITATIONS |
691 | All options that affect decoding are supported, except "allow_nonref". |
697 | All options that affect decoding are supported, except "allow_nonref". |
692 | The reason for this is that it cannot be made to work sensibly: JSON |
698 | The reason for this is that it cannot be made to work sensibly: JSON |
693 | objects and arrays are self-delimited, i.e. you can concatenate them |
699 | objects and arrays are self-delimited, i.e. you can concatenate them |
… | |
… | |
913 | an exception to be thrown, except for references to the integers 0 |
919 | an exception to be thrown, except for references to the integers 0 |
914 | and 1, which get turned into "false" and "true" atoms in JSON. You |
920 | and 1, which get turned into "false" and "true" atoms in JSON. You |
915 | can also use "JSON::XS::false" and "JSON::XS::true" to improve |
921 | can also use "JSON::XS::false" and "JSON::XS::true" to improve |
916 | readability. |
922 | readability. |
917 | |
923 | |
918 | encode_json [\0,JSON::XS::true] # yields [false,true] |
924 | encode_json [\0, JSON::XS::true] # yields [false,true] |
919 | |
925 | |
920 | JSON::XS::true, JSON::XS::false |
926 | JSON::XS::true, JSON::XS::false |
921 | These special values become JSON true and JSON false values, |
927 | These special values become JSON true and JSON false values, |
922 | respectively. You can also use "\1" and "\0" directly if you want. |
928 | respectively. You can also use "\1" and "\0" directly if you want. |
923 | |
929 | |
… | |
… | |
1218 | |
1224 | |
1219 | (It might actually work, but you have been warned). |
1225 | (It might actually work, but you have been warned). |
1220 | |
1226 | |
1221 | BUGS |
1227 | BUGS |
1222 | While the goal of this module is to be correct, that unfortunately does |
1228 | While the goal of this module is to be correct, that unfortunately does |
1223 | not mean it's bug-free, only that I think its design is bug-free. It is |
1229 | not mean it's bug-free, only that I think its design is bug-free. If you |
1224 | still relatively early in its development. If you keep reporting bugs |
|
|
1225 | they will be fixed swiftly, though. |
1230 | keep reporting bugs they will be fixed swiftly, though. |
1226 | |
1231 | |
1227 | Please refrain from using rt.cpan.org or any other bug reporting |
1232 | Please refrain from using rt.cpan.org or any other bug reporting |
1228 | service. I put the contact address into my modules for a reason. |
1233 | service. I put the contact address into my modules for a reason. |
1229 | |
1234 | |
1230 | SEE ALSO |
1235 | SEE ALSO |