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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.15 by root, Sat Mar 24 01:15:22 2007 UTC vs.
Revision 1.16 by root, Sat Mar 24 02:23:51 2007 UTC

… …
49by JSON, the deserialised data structure is identical on the Perl level. 49by JSON, the deserialised data structure is identical on the Perl level.
50(e.g. the string "2.0" doesn't suddenly become "2"). 50(e.g. the string "2.0" doesn't suddenly become "2").
51 51
52=item * strict checking of JSON correctness 52=item * strict checking of JSON correctness
53 53
54There is no guessing, no generating of illegal JSON strings by default, 54There is no guessing, no generating of illegal JSON texts by default,
55and only JSON is accepted as input by default (the latter is a security 55and only JSON is accepted as input by default (the latter is a security
56feature). 56feature).
57 57
58=item * fast 58=item * fast
59 59
… …
95The following convinience methods are provided by this module. They are 95The following convinience methods are provided by this module. They are
96exported by default: 96exported by default:
97 97
98=over 4 98=over 4
99 99
100=item $json_string = to_json $perl_scalar 100=item $json_text = to_json $perl_scalar
101 101
102Converts the given Perl data structure (a simple scalar or a reference to 102Converts the given Perl data structure (a simple scalar or a reference to
103a hash or array) to a UTF-8 encoded, binary string (that is, the string contains 103a hash or array) to a UTF-8 encoded, binary string (that is, the string contains
104octets only). Croaks on error. 104octets only). Croaks on error.
105 105
106This function call is functionally identical to C<< JSON::XS->new->utf8->encode ($perl_scalar) >>. 106This function call is functionally identical to:
107 107
108 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
109
110except being faster.
111
108=item $perl_scalar = from_json $json_string 112=item $perl_scalar = from_json $json_text
109 113
110The opposite of C<to_json>: expects an UTF-8 (binary) string and tries to 114The opposite of C<to_json>: expects an UTF-8 (binary) string and tries to
111parse that as an UTF-8 encoded JSON string, returning the resulting simple 115parse that as an UTF-8 encoded JSON text, returning the resulting simple
112scalar or reference. Croaks on error. 116scalar or reference. Croaks on error.
113 117
114This function call is functionally identical to C<< JSON::XS->new->utf8->decode ($json_string) >>. 118This function call is functionally identical to:
119
120 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
121
122except being faster.
115 123
116=back 124=back
117 125
118=head1 OBJECT-ORIENTED INTERFACE 126=head1 OBJECT-ORIENTED INTERFACE
119 127
… …
128strings. All boolean flags described below are by default I<disabled>. 136strings. All boolean flags described below are by default I<disabled>.
129 137
130The mutators for flags all return the JSON object again and thus calls can 138The mutators for flags all return the JSON object again and thus calls can
131be chained: 139be chained:
132 140
133 my $json = JSON::XS->new->utf8(1)->space_after(1)->encode ({a => [1,2]}) 141 my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]})
134 => {"a": [1, 2]} 142 => {"a": [1, 2]}
135 143
136=item $json = $json->ascii ([$enable]) 144=item $json = $json->ascii ([$enable])
137 145
138If C<$enable> is true (or missing), then the C<encode> method will 146If C<$enable> is true (or missing), then the C<encode> method will not
139not generate characters outside the code range C<0..127>. Any unicode 147generate characters outside the code range C<0..127> (which is ASCII). Any
140characters outside that range will be escaped using either a single 148unicode characters outside that range will be escaped using either a
141\uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, as per 149single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence,
142RFC4627. 150as per RFC4627.
143 151
144If C<$enable> is false, then the C<encode> method will not escape Unicode 152If C<$enable> is false, then the C<encode> method will not escape Unicode
145characters unless necessary. 153characters unless required by the JSON syntax. This results in a faster
154and more compact format.
146 155
147 JSON::XS->new->ascii (1)->encode (chr 0x10401) 156 JSON::XS->new->ascii (1)->encode ([chr 0x10401])
148 => \ud801\udc01 157 => ["\ud801\udc01"]
149 158
150=item $json = $json->utf8 ([$enable]) 159=item $json = $json->utf8 ([$enable])
151 160
152If C<$enable> is true (or missing), then the C<encode> method will encode 161If C<$enable> is true (or missing), then the C<encode> method will encode
153the JSON string into UTF-8, as required by many protocols, while the 162the JSON result into UTF-8, as required by many protocols, while the
154C<decode> method expects to be handled an UTF-8-encoded string. Please 163C<decode> method expects to be handled an UTF-8-encoded string. Please
155note that UTF-8-encoded strings do not contain any characters outside the 164note that UTF-8-encoded strings do not contain any characters outside the
156range C<0..255>, they are thus useful for bytewise/binary I/O. 165range C<0..255>, they are thus useful for bytewise/binary I/O. In future
166versions, enabling this option might enable autodetection of the UTF-16
167and UTF-32 encoding families, as described in RFC4627.
157 168
158If C<$enable> is false, then the C<encode> method will return the JSON 169If C<$enable> is false, then the C<encode> method will return the JSON
159string as a (non-encoded) unicode string, while C<decode> expects thus a 170string as a (non-encoded) unicode string, while C<decode> expects thus a
160unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs 171unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
161to be done yourself, e.g. using the Encode module. 172to be done yourself, e.g. using the Encode module.
162 173
163Example, output UTF-16-encoded JSON: 174Example, output UTF-16BE-encoded JSON:
175
176 use Encode;
177 $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object);
178
179Example, decode UTF-32LE-encoded JSON:
180
181 use Encode;
182 $object = JSON::XS->new->decode (decode "UTF-32LE", $jsontext);
164 183
165=item $json = $json->pretty ([$enable]) 184=item $json = $json->pretty ([$enable])
166 185
167This enables (or disables) all of the C<indent>, C<space_before> and 186This enables (or disables) all of the C<indent>, C<space_before> and
168C<space_after> (and in the future possibly more) flags in one call to 187C<space_after> (and in the future possibly more) flags in one call to
… …
184If C<$enable> is true (or missing), then the C<encode> method will use a multiline 203If C<$enable> is true (or missing), then the C<encode> method will use a multiline
185format as output, putting every array member or object/hash key-value pair 204format as output, putting every array member or object/hash key-value pair
186into its own line, identing them properly. 205into its own line, identing them properly.
187 206
188If C<$enable> is false, no newlines or indenting will be produced, and the 207If C<$enable> is false, no newlines or indenting will be produced, and the
189resulting JSON strings is guarenteed not to contain any C<newlines>. 208resulting JSON text is guarenteed not to contain any C<newlines>.
190 209
191This setting has no effect when decoding JSON strings. 210This setting has no effect when decoding JSON texts.
192 211
193=item $json = $json->space_before ([$enable]) 212=item $json = $json->space_before ([$enable])
194 213
195If C<$enable> is true (or missing), then the C<encode> method will add an extra 214If C<$enable> is true (or missing), then the C<encode> method will add an extra
196optional space before the C<:> separating keys from values in JSON objects. 215optional space before the C<:> separating keys from values in JSON objects.
197 216
198If C<$enable> is false, then the C<encode> method will not add any extra 217If C<$enable> is false, then the C<encode> method will not add any extra
199space at those places. 218space at those places.
200 219
201This setting has no effect when decoding JSON strings. You will also most 220This setting has no effect when decoding JSON texts. You will also
202likely combine this setting with C<space_after>. 221most likely combine this setting with C<space_after>.
203 222
204Example, space_before enabled, space_after and indent disabled: 223Example, space_before enabled, space_after and indent disabled:
205 224
206 {"key" :"value"} 225 {"key" :"value"}
207 226
… …
213members. 232members.
214 233
215If C<$enable> is false, then the C<encode> method will not add any extra 234If C<$enable> is false, then the C<encode> method will not add any extra
216space at those places. 235space at those places.
217 236
218This setting has no effect when decoding JSON strings. 237This setting has no effect when decoding JSON texts.
219 238
220Example, space_before and indent disabled, space_after enabled: 239Example, space_before and indent disabled, space_after enabled:
221 240
222 {"key": "value"} 241 {"key": "value"}
223 242
… …
229If C<$enable> is false, then the C<encode> method will output key-value 248If C<$enable> is false, then the C<encode> method will output key-value
230pairs in the order Perl stores them (which will likely change between runs 249pairs in the order Perl stores them (which will likely change between runs
231of the same script). 250of the same script).
232 251
233This option is useful if you want the same data structure to be encoded as 252This option is useful if you want the same data structure to be encoded as
234the same JSON string (given the same overall settings). If it is disabled, 253the same JSON text (given the same overall settings). If it is disabled,
235the same hash migh be encoded differently even if contains the same data, 254the same hash migh be encoded differently even if contains the same data,
236as key-value pairs have no inherent ordering in Perl. 255as key-value pairs have no inherent ordering in Perl.
237 256
238This setting has no effect when decoding JSON strings. 257This setting has no effect when decoding JSON texts.
239 258
240=item $json = $json->allow_nonref ([$enable]) 259=item $json = $json->allow_nonref ([$enable])
241 260
242If C<$enable> is true (or missing), then the C<encode> method can convert a 261If C<$enable> is true (or missing), then the C<encode> method can convert a
243non-reference into its corresponding string, number or null JSON value, 262non-reference into its corresponding string, number or null JSON value,
244which is an extension to RFC4627. Likewise, C<decode> will accept those JSON 263which is an extension to RFC4627. Likewise, C<decode> will accept those JSON
245values instead of croaking. 264values instead of croaking.
246 265
247If C<$enable> is false, then the C<encode> method will croak if it isn't 266If C<$enable> is false, then the C<encode> method will croak if it isn't
248passed an arrayref or hashref, as JSON strings must either be an object 267passed an arrayref or hashref, as JSON texts must either be an object
249or array. Likewise, C<decode> will croak if given something that is not a 268or array. Likewise, C<decode> will croak if given something that is not a
250JSON object or array. 269JSON object or array.
251 270
252Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>, 271Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,
253resulting in an invalid JSON text: 272resulting in an invalid JSON text:
… …
258=item $json = $json->shrink ([$enable]) 277=item $json = $json->shrink ([$enable])
259 278
260Perl usually over-allocates memory a bit when allocating space for 279Perl usually over-allocates memory a bit when allocating space for
261strings. This flag optionally resizes strings generated by either 280strings. This flag optionally resizes strings generated by either
262C<encode> or C<decode> to their minimum size possible. This can save 281C<encode> or C<decode> to their minimum size possible. This can save
263memory when your JSON strings are either very very long or you have many 282memory when your JSON texts are either very very long or you have many
264short strings. It will also try to downgrade any strings to octet-form 283short strings. It will also try to downgrade any strings to octet-form
265if possible: perl stores strings internally either in an encoding called 284if possible: perl stores strings internally either in an encoding called
266UTF-X or in octet-form. The latter cannot store everything but uses less 285UTF-X or in octet-form. The latter cannot store everything but uses less
267space in general. 286space in general.
268 287
… …
274 293
275In the future, this setting might control other things, such as converting 294In the future, this setting might control other things, such as converting
276strings that look like integers or floats into integers or floats 295strings that look like integers or floats into integers or floats
277internally (there is no difference on the Perl level), saving space. 296internally (there is no difference on the Perl level), saving space.
278 297
279=item $json_string = $json->encode ($perl_scalar) 298=item $json_text = $json->encode ($perl_scalar)
280 299
281Converts the given Perl data structure (a simple scalar or a reference 300Converts the given Perl data structure (a simple scalar or a reference
282to a hash or array) to its JSON representation. Simple scalars will be 301to a hash or array) to its JSON representation. Simple scalars will be
283converted into JSON string or number sequences, while references to arrays 302converted into JSON string or number sequences, while references to arrays
284become JSON arrays and references to hashes become JSON objects. Undefined 303become JSON arrays and references to hashes become JSON objects. Undefined
285Perl values (e.g. C<undef>) become JSON C<null> values. Neither C<true> 304Perl values (e.g. C<undef>) become JSON C<null> values. Neither C<true>
286nor C<false> values will be generated. 305nor C<false> values will be generated.
287 306
288=item $perl_scalar = $json->decode ($json_string) 307=item $perl_scalar = $json->decode ($json_text)
289 308
290The opposite of C<encode>: expects a JSON string and tries to parse it, 309The opposite of C<encode>: expects a JSON text and tries to parse it,
291returning the resulting simple scalar or reference. Croaks on error. 310returning the resulting simple scalar or reference. Croaks on error.
292 311
293JSON numbers and strings become simple Perl scalars. JSON arrays become 312JSON numbers and strings become simple Perl scalars. JSON arrays become
294Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes 313Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
295C<1>, C<false> becomes C<0> and C<null> becomes C<undef>. 314C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
… …
448 467
449Has problems handling many Perl values (e.g. regex results and other magic 468Has problems handling many Perl values (e.g. regex results and other magic
450values will make it croak). 469values will make it croak).
451 470
452Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}> 471Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}>
453which is not a valid JSON string. 472which is not a valid JSON text.
454 473
455Unmaintained (maintainer unresponsive for many months, bugs are not 474Unmaintained (maintainer unresponsive for many months, bugs are not
456getting fixed). 475getting fixed).
457 476
458=item JSON::Syck 0.21 477=item JSON::Syck 0.21
… …
460Very buggy (often crashes). 479Very buggy (often crashes).
461 480
462Very inflexible (no human-readable format supported, format pretty much 481Very inflexible (no human-readable format supported, format pretty much
463undocumented. I need at least a format for easy reading by humans and a 482undocumented. I need at least a format for easy reading by humans and a
464single-line compact format for use in a protocol, and preferably a way to 483single-line compact format for use in a protocol, and preferably a way to
465generate ASCII-only JSON strings). 484generate ASCII-only JSON texts).
466 485
467Completely broken (and confusingly documented) Unicode handling (unicode 486Completely broken (and confusingly documented) Unicode handling (unicode
468escapes are not working properly, you need to set ImplicitUnicode to 487escapes are not working properly, you need to set ImplicitUnicode to
469I<different> values on en- and decoding to get symmetric behaviour). 488I<different> values on en- and decoding to get symmetric behaviour).
470 489
… …
493 512
494Very inflexible. 513Very inflexible.
495 514
496No roundtripping. 515No roundtripping.
497 516
498Does not generate valid JSON (key strings are often unquoted, empty keys 517Does not generate valid JSON texts (key strings are often unquoted, empty keys
499result in nothing being output) 518result in nothing being output)
500 519
501Does not check input for validity. 520Does not check input for validity.
502 521
503=back 522=back

Diff Legend

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