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.4 by root, Thu Mar 22 21:13:58 2007 UTC vs.
Revision 1.9 by root, Fri Mar 23 16:00:19 2007 UTC

… …
59=cut 59=cut
60 60
61package JSON::XS; 61package JSON::XS;
62 62
63BEGIN { 63BEGIN {
64 $VERSION = '0.1'; 64 $VERSION = '0.3';
65 @ISA = qw(Exporter); 65 @ISA = qw(Exporter);
66 66
67 @EXPORT = qw(to_json from_json); 67 @EXPORT = qw(to_json from_json);
68 require Exporter; 68 require Exporter;
69 69
… …
114be chained: 114be chained:
115 115
116 my $json = JSON::XS->new->utf8(1)->space_after(1)->encode ({a => [1,2]}) 116 my $json = JSON::XS->new->utf8(1)->space_after(1)->encode ({a => [1,2]})
117 => {"a": [1, 2]} 117 => {"a": [1, 2]}
118 118
119=item $json = $json->ascii ($enable) 119=item $json = $json->ascii ([$enable])
120 120
121If C<$enable> is true, then the C<encode> method will not generate 121If C<$enable> is true (or missing), then the C<encode> method will
122characters outside the code range C<0..127>. Any unicode characters 122not generate characters outside the code range C<0..127>. Any unicode
123outside that range will be escaped using either a single \uXXXX (BMP 123characters outside that range will be escaped using either a single
124characters) or a double \uHHHH\uLLLLL escape sequence, as per RFC4627. 124\uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, as per
125RFC4627.
125 126
126If C<$enable> is false, then the C<encode> method will not escape Unicode 127If C<$enable> is false, then the C<encode> method will not escape Unicode
127characters unless necessary. 128characters unless necessary.
128 129
129 JSON::XS->new->ascii (1)->encode (chr 0x10401) 130 JSON::XS->new->ascii (1)->encode (chr 0x10401)
130 => \ud801\udc01 131 => \ud801\udc01
131 132
132=item $json = $json->utf8 ($enable) 133=item $json = $json->utf8 ([$enable])
133 134
134If C<$enable> is true, then the C<encode> method will encode the JSON 135If C<$enable> is true (or missing), then the C<encode> method will encode
135string into UTF-8, as required by many protocols, while the C<decode> 136the JSON string into UTF-8, as required by many protocols, while the
136method expects to be handled an UTF-8-encoded string. Please note that 137C<decode> method expects to be handled an UTF-8-encoded string. Please
137UTF-8-encoded strings do not contain any characters outside the range 138note that UTF-8-encoded strings do not contain any characters outside the
138C<0..255>, they are thus useful for bytewise/binary I/O. 139range C<0..255>, they are thus useful for bytewise/binary I/O.
139 140
140If C<$enable> is false, then the C<encode> method will return the JSON 141If C<$enable> is false, then the C<encode> method will return the JSON
141string as a (non-encoded) unicode string, while C<decode> expects thus a 142string as a (non-encoded) unicode string, while C<decode> expects thus a
142unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs 143unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
143to be done yourself, e.g. using the Encode module. 144to be done yourself, e.g. using the Encode module.
144 145
145=item $json = $json->pretty ($enable) 146=item $json = $json->pretty ([$enable])
146 147
147This enables (or disables) all of the C<indent>, C<space_before> and 148This enables (or disables) all of the C<indent>, C<space_before> and
148C<space_after> (and in the future possibly more) flags in one call to 149C<space_after> (and in the future possibly more) flags in one call to
149generate the most readable (or most compact) form possible. 150generate the most readable (or most compact) form possible.
150 151
… …
155 1, 156 1,
156 2 157 2
157 ] 158 ]
158 } 159 }
159 160
160=item $json = $json->indent ($enable) 161=item $json = $json->indent ([$enable])
161 162
162If C<$enable> is true, then the C<encode> method will use a multiline 163If C<$enable> is true (or missing), then the C<encode> method will use a multiline
163format as output, putting every array member or object/hash key-value pair 164format as output, putting every array member or object/hash key-value pair
164into its own line, identing them properly. 165into its own line, identing them properly.
165 166
166If C<$enable> is false, no newlines or indenting will be produced, and the 167If C<$enable> is false, no newlines or indenting will be produced, and the
167resulting JSON strings is guarenteed not to contain any C<newlines>. 168resulting JSON strings is guarenteed not to contain any C<newlines>.
168 169
169This setting has no effect when decoding JSON strings. 170This setting has no effect when decoding JSON strings.
170 171
171=item $json = $json->space_before ($enable) 172=item $json = $json->space_before ([$enable])
172 173
173If C<$enable> is true, then the C<encode> method will add an extra 174If C<$enable> is true (or missing), then the C<encode> method will add an extra
174optional space before the C<:> separating keys from values in JSON objects. 175optional space before the C<:> separating keys from values in JSON objects.
175 176
176If C<$enable> is false, then the C<encode> method will not add any extra 177If C<$enable> is false, then the C<encode> method will not add any extra
177space at those places. 178space at those places.
178 179
179This setting has no effect when decoding JSON strings. You will also most 180This setting has no effect when decoding JSON strings. You will also most
180likely combine this setting with C<space_after>. 181likely combine this setting with C<space_after>.
181 182
182=item $json = $json->space_after ($enable) 183=item $json = $json->space_after ([$enable])
183 184
184If C<$enable> is true, then the C<encode> method will add an extra 185If C<$enable> is true (or missing), then the C<encode> method will add an extra
185optional space after the C<:> separating keys from values in JSON objects 186optional space after the C<:> separating keys from values in JSON objects
186and extra whitespace after the C<,> separating key-value pairs and array 187and extra whitespace after the C<,> separating key-value pairs and array
187members. 188members.
188 189
189If C<$enable> is false, then the C<encode> method will not add any extra 190If C<$enable> is false, then the C<encode> method will not add any extra
190space at those places. 191space at those places.
191 192
192This setting has no effect when decoding JSON strings. 193This setting has no effect when decoding JSON strings.
193 194
194=item $json = $json->canonical ($enable) 195=item $json = $json->canonical ([$enable])
195 196
196If C<$enable> is true, then the C<encode> method will output JSON objects 197If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
197by sorting their keys. This is adding a comparatively high overhead. 198by sorting their keys. This is adding a comparatively high overhead.
198 199
199If C<$enable> is false, then the C<encode> method will output key-value 200If C<$enable> is false, then the C<encode> method will output key-value
200pairs in the order Perl stores them (which will likely change between runs 201pairs in the order Perl stores them (which will likely change between runs
201of the same script). 202of the same script).
… …
205the same hash migh be encoded differently even if contains the same data, 206the same hash migh be encoded differently even if contains the same data,
206as key-value pairs have no inherent ordering in Perl. 207as key-value pairs have no inherent ordering in Perl.
207 208
208This setting has no effect when decoding JSON strings. 209This setting has no effect when decoding JSON strings.
209 210
210=item $json = $json->allow_nonref ($enable) 211=item $json = $json->allow_nonref ([$enable])
211 212
212If C<$enable> is true, then the C<encode> method can convert a 213If C<$enable> is true (or missing), then the C<encode> method can convert a
213non-reference into its corresponding string, number or null JSON value, 214non-reference into its corresponding string, number or null JSON value,
214which is an extension to RFC4627. Likewise, C<decode> will accept those JSON 215which is an extension to RFC4627. Likewise, C<decode> will accept those JSON
215values instead of croaking. 216values instead of croaking.
216 217
217If C<$enable> is false, then the C<encode> method will croak if it isn't 218If C<$enable> is false, then the C<encode> method will croak if it isn't
218passed an arrayref or hashref, as JSON strings must either be an object 219passed an arrayref or hashref, as JSON strings must either be an object
219or array. Likewise, C<decode> will croak if given something that is not a 220or array. Likewise, C<decode> will croak if given something that is not a
220JSON object or array. 221JSON object or array.
222
223=item $json = $json->shrink ([$enable])
224
225Perl usually over-allocates memory a bit when allocating space for
226strings. This flag optionally resizes strings generated by either
227C<encode> or C<decode> to their minimum size possible. This can save
228memory when your JSON strings are either very very long or you have many
229short strings. It will also try to downgrade any strings to octet-form
230if possible: perl stores strings internally either in an encoding called
231UTF-X or in octet-form. The latter cannot store everything but uses less
232space in general.
233
234If C<$enable> is true (or missing), the string returned by C<encode> will be shrunk-to-fit,
235while all strings generated by C<decode> will also be shrunk-to-fit.
236
237If C<$enable> is false, then the normal perl allocation algorithms are used.
238If you work with your data, then this is likely to be faster.
239
240In the future, this setting might control other things, such as converting
241strings that look like integers or floats into integers or floats
242internally (there is no difference on the Perl level), saving space.
221 243
222=item $json_string = $json->encode ($perl_scalar) 244=item $json_string = $json->encode ($perl_scalar)
223 245
224Converts the given Perl data structure (a simple scalar or a reference 246Converts the given Perl data structure (a simple scalar or a reference
225to a hash or array) to its JSON representation. Simple scalars will be 247to a hash or array) to its JSON representation. Simple scalars will be
… …
247followed by some benchmark values. JSON::XS was designed not to suffer 269followed by some benchmark values. JSON::XS was designed not to suffer
248from any of these problems or limitations. 270from any of these problems or limitations.
249 271
250=over 4 272=over 4
251 273
252=item JSON 274=item JSON 1.07
253 275
254Slow (but very portable, as it is written in pure Perl). 276Slow (but very portable, as it is written in pure Perl).
255 277
256Undocumented/buggy Unicode handling (how JSON handles unicode values is 278Undocumented/buggy Unicode handling (how JSON handles unicode values is
257undocumented. One can get far by feeding it unicode strings and doing 279undocumented. One can get far by feeding it unicode strings and doing
… …
259 281
260No roundtripping (strings get clobbered if they look like numbers, e.g. 282No roundtripping (strings get clobbered if they look like numbers, e.g.
261the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will 283the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will
262decode into the number 2. 284decode into the number 2.
263 285
264=item JSON::PC 286=item JSON::PC 0.01
265 287
266Very fast. 288Very fast.
267 289
268Undocumented/buggy Unicode handling. 290Undocumented/buggy Unicode handling.
269 291
… …
276which is not a valid JSON string. 298which is not a valid JSON string.
277 299
278Unmaintained (maintainer unresponsive for many months, bugs are not 300Unmaintained (maintainer unresponsive for many months, bugs are not
279getting fixed). 301getting fixed).
280 302
281=item JSON::Syck 303=item JSON::Syck 0.21
282 304
283Very buggy (often crashes). 305Very buggy (often crashes).
284 306
285Very inflexible (no human-readable format supported, format pretty much 307Very inflexible (no human-readable format supported, format pretty much
286undocumented. I need at least a format for easy reading by humans and a 308undocumented. I need at least a format for easy reading by humans and a
… …
305JSON. One bank might parse a given non-JSON request and deduct money, 327JSON. One bank might parse a given non-JSON request and deduct money,
306while the other might reject the transaction with a syntax error. While a 328while the other might reject the transaction with a syntax error. While a
307good protocol will at least recover, that is extra unnecessary work and 329good protocol will at least recover, that is extra unnecessary work and
308the transaction will still not succeed). 330the transaction will still not succeed).
309 331
310=item JSON::DWIW 332=item JSON::DWIW 0.04
311 333
312Very fast. Very natural. Very nice. 334Very fast. Very natural. Very nice.
313 335
314Undocumented unicode handling (but the best of the pack. Unicode escapes 336Undocumented unicode handling (but the best of the pack. Unicode escapes
315still don't get parsed properly). 337still don't get parsed properly).

Diff Legend

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