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.6 by root, Thu Mar 22 23:24:18 2007 UTC vs.
Revision 1.7 by root, Fri Mar 23 15:10:55 2007 UTC

… …
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.
230
231If C<$enable> is true (or missing), the string returned by C<encode> will be shrunk-to-fit,
232while all strings generated by C<decode> will also be shrunk-to-fit.
233
234If C<$enable> is false, then the normal perl allocation algorithms are used.
235If you work with your data, then this is likely to be faster.
236
237In the future, this setting might control other things, such as converting
238strings that look like integers or floats into integers or floats
239internally (there is no difference on the Perl level), saving space.
221 240
222=item $json_string = $json->encode ($perl_scalar) 241=item $json_string = $json->encode ($perl_scalar)
223 242
224Converts the given Perl data structure (a simple scalar or a reference 243Converts the given Perl data structure (a simple scalar or a reference
225to a hash or array) to its JSON representation. Simple scalars will be 244to a hash or array) to its JSON representation. Simple scalars will be

Diff Legend

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