ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/JSON-XS/README
(Generate patch)

Comparing JSON-XS/README (file contents):
Revision 1.25 by root, Wed Apr 16 18:38:38 2008 UTC vs.
Revision 1.26 by root, Tue Jun 3 06:43:45 2008 UTC

… …
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
627INCREMENTAL PARSING 627INCREMENTAL 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
1221BUGS 1227BUGS
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
1230SEE ALSO 1235SEE ALSO

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines