Debian Codegraph @

upstream/opensuse-tumbleweed/man3/JSON::PP.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "JSON::PP 3pm"
61 .TH JSON::PP 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 JSON::PP \- JSON::XS compatible pure\-Perl module.
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use JSON::PP;
72 \&
73 \& # exported functions, they croak on error
74 \& # and expect/generate UTF\-8
75 \&
76 \& $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
77 \& $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text;
78 \&
79 \& # OO\-interface
80 \&
81 \& $json = JSON::PP\->new\->ascii\->pretty\->allow_nonref;
82 \&
83 \& $pretty_printed_json_text = $json\->encode( $perl_scalar );
84 \& $perl_scalar = $json\->decode( $json_text );
85 \&
86 \& # Note that JSON version 2.0 and above will automatically use
87 \& # JSON::XS or JSON::PP, so you should be able to just:
88 \&
89 \& use JSON;
90 .Ve
91 .SH DESCRIPTION
92 .IX Header "DESCRIPTION"
93 JSON::PP is a pure perl JSON decoder/encoder, and (almost) compatible to much
94 faster JSON::XS written by Marc Lehmann in C. JSON::PP works as
95 a fallback module when you use JSON module without having
96 installed JSON::XS.
97 .PP
98 Because of this fallback feature of JSON.pm, JSON::PP tries not to
99 be more JavaScript\-friendly than JSON::XS (i.e. not to escape extra
100 characters such as U+2028 and U+2029, etc),
101 in order for you not to lose such JavaScript\-friendliness silently
102 when you use JSON.pm and install JSON::XS for speed or by accident.
103 If you need JavaScript\-friendly RFC7159\-compliant pure perl module,
104 try JSON::Tiny, which is derived from Mojolicious web
105 framework and is also smaller and faster than JSON::PP.
106 .PP
107 JSON::PP has been in the Perl core since Perl 5.14, mainly for
108 CPAN toolchain modules to parse META.json.
109 .SH "FUNCTIONAL INTERFACE"
110 .IX Header "FUNCTIONAL INTERFACE"
111 This section is taken from JSON::XS almost verbatim. \f(CW\*(C`encode_json\*(C'\fR
112 and \f(CW\*(C`decode_json\*(C'\fR are exported by default.
113 .SS encode_json
114 .IX Subsection "encode_json"
115 .Vb 1
116 \& $json_text = encode_json $perl_scalar
117 .Ve
118 .PP
119 Converts the given Perl data structure to a UTF\-8 encoded, binary string
120 (that is, the string contains octets only). Croaks on error.
121 .PP
122 This function call is functionally identical to:
123 .PP
124 .Vb 1
125 \& $json_text = JSON::PP\->new\->utf8\->encode($perl_scalar)
126 .Ve
127 .PP
128 Except being faster.
129 .SS decode_json
130 .IX Subsection "decode_json"
131 .Vb 1
132 \& $perl_scalar = decode_json $json_text
133 .Ve
134 .PP
135 The opposite of \f(CW\*(C`encode_json\*(C'\fR: expects an UTF\-8 (binary) string and tries
136 to parse that as an UTF\-8 encoded JSON text, returning the resulting
137 reference. Croaks on error.
138 .PP
139 This function call is functionally identical to:
140 .PP
141 .Vb 1
142 \& $perl_scalar = JSON::PP\->new\->utf8\->decode($json_text)
143 .Ve
144 .PP
145 Except being faster.
146 .SS JSON::PP::is_bool
147 .IX Subsection "JSON::PP::is_bool"
148 .Vb 1
149 \& $is_boolean = JSON::PP::is_bool($scalar)
150 .Ve
151 .PP
152 Returns true if the passed scalar represents either JSON::PP::true or
153 JSON::PP::false, two constants that act like \f(CW1\fR and \f(CW0\fR respectively
154 and are also used to represent JSON \f(CW\*(C`true\*(C'\fR and \f(CW\*(C`false\*(C'\fR in Perl strings.
155 .PP
156 On perl 5.36 and above, will also return true when given one of perl\*(Aqs
157 standard boolean values, such as the result of a comparison.
158 .PP
159 See MAPPING, below, for more information on how JSON values are mapped to
160 Perl.
161 .SH "OBJECT\-ORIENTED INTERFACE"
162 .IX Header "OBJECT-ORIENTED INTERFACE"
163 This section is also taken from JSON::XS.
164 .PP
165 The object oriented interface lets you configure your own encoding or
166 decoding style, within the limits of supported formats.
167 .SS new
168 .IX Subsection "new"
169 .Vb 1
170 \& $json = JSON::PP\->new
171 .Ve
172 .PP
173 Creates a new JSON::PP object that can be used to de/encode JSON
174 strings. All boolean flags described below are by default \fIdisabled\fR
175 (with the exception of \f(CW\*(C`allow_nonref\*(C'\fR, which defaults to \fIenabled\fR since
176 version \f(CW4.0\fR).
177 .PP
178 The mutators for flags all return the JSON::PP object again and thus calls can
179 be chained:
180 .PP
181 .Vb 2
182 \& my $json = JSON::PP\->new\->utf8\->space_after\->encode({a => [1,2]})
183 \& => {"a": [1, 2]}
184 .Ve
185 .SS ascii
186 .IX Subsection "ascii"
187 .Vb 1
188 \& $json = $json\->ascii([$enable])
189 \&
190 \& $enabled = $json\->get_ascii
191 .Ve
192 .PP
193 If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will not
194 generate characters outside the code range \f(CW0..127\fR (which is ASCII). Any
195 Unicode characters outside that range will be escaped using either a
196 single \euXXXX (BMP characters) or a double \euHHHH\euLLLLL escape sequence,
197 as per RFC4627. The resulting encoded JSON text can be treated as a native
198 Unicode string, an ascii\-encoded, latin1\-encoded or UTF\-8 encoded string,
199 or any other superset of ASCII.
200 .PP
201 If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not escape Unicode
202 characters unless required by the JSON syntax or other flags. This results
203 in a faster and more compact format.
204 .PP
205 See also the section \fIENCODING/CODESET FLAG NOTES\fR later in this document.
206 .PP
207 The main use for this flag is to produce JSON texts that can be
208 transmitted over a 7\-bit channel, as the encoded JSON texts will not
209 contain any 8 bit characters.
210 .PP
211 .Vb 2
212 \& JSON::PP\->new\->ascii(1)\->encode([chr 0x10401])
213 \& => ["\eud801\eudc01"]
214 .Ve
215 .SS latin1
216 .IX Subsection "latin1"
217 .Vb 1
218 \& $json = $json\->latin1([$enable])
219 \&
220 \& $enabled = $json\->get_latin1
221 .Ve
222 .PP
223 If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will encode
224 the resulting JSON text as latin1 (or iso\-8859\-1), escaping any characters
225 outside the code range \f(CW0..255\fR. The resulting string can be treated as a
226 latin1\-encoded JSON text or a native Unicode string. The \f(CW\*(C`decode\*(C'\fR method
227 will not be affected in any way by this flag, as \f(CW\*(C`decode\*(C'\fR by default
228 expects Unicode, which is a strict superset of latin1.
229 .PP
230 If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not escape Unicode
231 characters unless required by the JSON syntax or other flags.
232 .PP
233 See also the section \fIENCODING/CODESET FLAG NOTES\fR later in this document.
234 .PP
235 The main use for this flag is efficiently encoding binary data as JSON
236 text, as most octets will not be escaped, resulting in a smaller encoded
237 size. The disadvantage is that the resulting JSON text is encoded
238 in latin1 (and must correctly be treated as such when storing and
239 transferring), a rare encoding for JSON. It is therefore most useful when
240 you want to store data structures known to contain binary data efficiently
241 in files or databases, not when talking to other JSON encoders/decoders.
242 .PP
243 .Vb 2
244 \& JSON::PP\->new\->latin1\->encode (["\ex{89}\ex{abc}"]
245 \& => ["\ex{89}\e\eu0abc"] # (perl syntax, U+abc escaped, U+89 not)
246 .Ve
247 .SS utf8
248 .IX Subsection "utf8"
249 .Vb 1
250 \& $json = $json\->utf8([$enable])
251 \&
252 \& $enabled = $json\->get_utf8
253 .Ve
254 .PP
255 If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will encode
256 the JSON result into UTF\-8, as required by many protocols, while the
257 \&\f(CW\*(C`decode\*(C'\fR method expects to be handled an UTF\-8\-encoded string. Please
258 note that UTF\-8\-encoded strings do not contain any characters outside the
259 range \f(CW0..255\fR, they are thus useful for bytewise/binary I/O. In future
260 versions, enabling this option might enable autodetection of the UTF\-16
261 and UTF\-32 encoding families, as described in RFC4627.
262 .PP
263 If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will return the JSON
264 string as a (non\-encoded) Unicode string, while \f(CW\*(C`decode\*(C'\fR expects thus a
265 Unicode string. Any decoding or encoding (e.g. to UTF\-8 or UTF\-16) needs
266 to be done yourself, e.g. using the Encode module.
267 .PP
268 See also the section \fIENCODING/CODESET FLAG NOTES\fR later in this document.
269 .PP
270 Example, output UTF\-16BE\-encoded JSON:
271 .PP
272 .Vb 2
273 \& use Encode;
274 \& $jsontext = encode "UTF\-16BE", JSON::PP\->new\->encode ($object);
275 .Ve
276 .PP
277 Example, decode UTF\-32LE\-encoded JSON:
278 .PP
279 .Vb 2
280 \& use Encode;
281 \& $object = JSON::PP\->new\->decode (decode "UTF\-32LE", $jsontext);
282 .Ve
283 .SS pretty
284 .IX Subsection "pretty"
285 .Vb 1
286 \& $json = $json\->pretty([$enable])
287 .Ve
288 .PP
289 This enables (or disables) all of the \f(CW\*(C`indent\*(C'\fR, \f(CW\*(C`space_before\*(C'\fR and
290 \&\f(CW\*(C`space_after\*(C'\fR (and in the future possibly more) flags in one call to
291 generate the most readable (or most compact) form possible.
292 .SS indent
293 .IX Subsection "indent"
294 .Vb 1
295 \& $json = $json\->indent([$enable])
296 \&
297 \& $enabled = $json\->get_indent
298 .Ve
299 .PP
300 If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will use a multiline
301 format as output, putting every array member or object/hash key\-value pair
302 into its own line, indenting them properly.
303 .PP
304 If \f(CW$enable\fR is false, no newlines or indenting will be produced, and the
305 resulting JSON text is guaranteed not to contain any \f(CW\*(C`newlines\*(C'\fR.
306 .PP
307 This setting has no effect when decoding JSON texts.
308 .PP
309 The default indent space length is three.
310 You can use \f(CW\*(C`indent_length\*(C'\fR to change the length.
311 .SS space_before
312 .IX Subsection "space_before"
313 .Vb 1
314 \& $json = $json\->space_before([$enable])
315 \&
316 \& $enabled = $json\->get_space_before
317 .Ve
318 .PP
319 If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will add an extra
320 optional space before the \f(CW\*(C`:\*(C'\fR separating keys from values in JSON objects.
321 .PP
322 If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not add any extra
323 space at those places.
324 .PP
325 This setting has no effect when decoding JSON texts. You will also
326 most likely combine this setting with \f(CW\*(C`space_after\*(C'\fR.
327 .PP
328 Example, space_before enabled, space_after and indent disabled:
329 .PP
330 .Vb 1
331 \& {"key" :"value"}
332 .Ve
333 .SS space_after
334 .IX Subsection "space_after"
335 .Vb 1
336 \& $json = $json\->space_after([$enable])
337 \&
338 \& $enabled = $json\->get_space_after
339 .Ve
340 .PP
341 If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will add an extra
342 optional space after the \f(CW\*(C`:\*(C'\fR separating keys from values in JSON objects
343 and extra whitespace after the \f(CW\*(C`,\*(C'\fR separating key\-value pairs and array
344 members.
345 .PP
346 If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not add any extra
347 space at those places.
348 .PP
349 This setting has no effect when decoding JSON texts.
350 .PP
351 Example, space_before and indent disabled, space_after enabled:
352 .PP
353 .Vb 1
354 \& {"key": "value"}
355 .Ve
356 .SS relaxed
357 .IX Subsection "relaxed"
358 .Vb 1
359 \& $json = $json\->relaxed([$enable])
360 \&
361 \& $enabled = $json\->get_relaxed
362 .Ve
363 .PP
364 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept some
365 extensions to normal JSON syntax (see below). \f(CW\*(C`encode\*(C'\fR will not be
366 affected in anyway. \fIBe aware that this option makes you accept invalid
367 JSON texts as if they were valid!\fR. I suggest only to use this option to
368 parse application\-specific files written by humans (configuration files,
369 resource files etc.)
370 .PP
371 If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept
372 valid JSON texts.
373 .PP
374 Currently accepted extensions are:
375 .IP \(bu 4
376 list items can have an end\-comma
377 .Sp
378 JSON \fIseparates\fR array elements and key\-value pairs with commas. This
379 can be annoying if you write JSON texts manually and want to be able to
380 quickly append elements, so this extension accepts comma at the end of
381 such items not just between them:
382 .Sp
383 .Vb 8
384 \& [
385 \& 1,
386 \& 2, <\- this comma not normally allowed
387 \& ]
388 \& {
389 \& "k1": "v1",
390 \& "k2": "v2", <\- this comma not normally allowed
391 \& }
392 .Ve
393 .IP \(bu 4
394 shell\-style \*(Aq#\*(Aq\-comments
395 .Sp
396 Whenever JSON allows whitespace, shell\-style comments are additionally
397 allowed. They are terminated by the first carriage\-return or line\-feed
398 character, after which more white\-space and comments are allowed.
399 .Sp
400 .Vb 4
401 \& [
402 \& 1, # this comment not allowed in JSON
403 \& # neither this one...
404 \& ]
405 .Ve
406 .IP \(bu 4
407 C\-style multiple\-line \*(Aq/* */\*(Aq\-comments (JSON::PP only)
408 .Sp
409 Whenever JSON allows whitespace, C\-style multiple\-line comments are additionally
410 allowed. Everything between \f(CW\*(C`/*\*(C'\fR and \f(CW\*(C`*/\*(C'\fR is a comment, after which
411 more white\-space and comments are allowed.
412 .Sp
413 .Vb 4
414 \& [
415 \& 1, /* this comment not allowed in JSON */
416 \& /* neither this one... */
417 \& ]
418 .Ve
419 .IP \(bu 4
420 C++\-style one\-line \*(Aq//\*(Aq\-comments (JSON::PP only)
421 .Sp
422 Whenever JSON allows whitespace, C++\-style one\-line comments are additionally
423 allowed. They are terminated by the first carriage\-return or line\-feed
424 character, after which more white\-space and comments are allowed.
425 .Sp
426 .Vb 4
427 \& [
428 \& 1, // this comment not allowed in JSON
429 \& // neither this one...
430 \& ]
431 .Ve
432 .IP \(bu 4
433 literal ASCII TAB characters in strings
434 .Sp
435 Literal ASCII TAB characters are now allowed in strings (and treated as
436 \&\f(CW\*(C`\et\*(C'\fR).
437 .Sp
438 .Vb 4
439 \& [
440 \& "Hello\etWorld",
441 \& "Hello<TAB>World", # literal <TAB> would not normally be allowed
442 \& ]
443 .Ve
444 .SS canonical
445 .IX Subsection "canonical"
446 .Vb 1
447 \& $json = $json\->canonical([$enable])
448 \&
449 \& $enabled = $json\->get_canonical
450 .Ve
451 .PP
452 If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will output JSON objects
453 by sorting their keys. This is adding a comparatively high overhead.
454 .PP
455 If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will output key\-value
456 pairs in the order Perl stores them (which will likely change between runs
457 of the same script, and can change even within the same run from 5.18
458 onwards).
459 .PP
460 This option is useful if you want the same data structure to be encoded as
461 the same JSON text (given the same overall settings). If it is disabled,
462 the same hash might be encoded differently even if contains the same data,
463 as key\-value pairs have no inherent ordering in Perl.
464 .PP
465 This setting has no effect when decoding JSON texts.
466 .PP
467 This setting has currently no effect on tied hashes.
468 .SS allow_nonref
469 .IX Subsection "allow_nonref"
470 .Vb 1
471 \& $json = $json\->allow_nonref([$enable])
472 \&
473 \& $enabled = $json\->get_allow_nonref
474 .Ve
475 .PP
476 Unlike other boolean options, this opotion is enabled by default beginning
477 with version \f(CW4.0\fR.
478 .PP
479 If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method can convert a
480 non\-reference into its corresponding string, number or null JSON value,
481 which is an extension to RFC4627. Likewise, \f(CW\*(C`decode\*(C'\fR will accept those JSON
482 values instead of croaking.
483 .PP
484 If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will croak if it isn\*(Aqt
485 passed an arrayref or hashref, as JSON texts must either be an object
486 or array. Likewise, \f(CW\*(C`decode\*(C'\fR will croak if given something that is not a
487 JSON object or array.
488 .PP
489 Example, encode a Perl scalar as JSON value without enabled \f(CW\*(C`allow_nonref\*(C'\fR,
490 resulting in an error:
491 .PP
492 .Vb 2
493 \& JSON::PP\->new\->allow_nonref(0)\->encode ("Hello, World!")
494 \& => hash\- or arrayref expected...
495 .Ve
496 .SS allow_unknown
497 .IX Subsection "allow_unknown"
498 .Vb 1
499 \& $json = $json\->allow_unknown([$enable])
500 \&
501 \& $enabled = $json\->get_allow_unknown
502 .Ve
503 .PP
504 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR will \fInot\fR throw an
505 exception when it encounters values it cannot represent in JSON (for
506 example, filehandles) but instead will encode a JSON \f(CW\*(C`null\*(C'\fR value. Note
507 that blessed objects are not included here and are handled separately by
508 c<allow_blessed>.
509 .PP
510 If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will throw an
511 exception when it encounters anything it cannot encode as JSON.
512 .PP
513 This option does not affect \f(CW\*(C`decode\*(C'\fR in any way, and it is recommended to
514 leave it off unless you know your communications partner.
515 .SS allow_blessed
516 .IX Subsection "allow_blessed"
517 .Vb 1
518 \& $json = $json\->allow_blessed([$enable])
519 \&
520 \& $enabled = $json\->get_allow_blessed
521 .Ve
522 .PP
523 See "OBJECT SERIALISATION" for details.
524 .PP
525 If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will not
526 barf when it encounters a blessed reference that it cannot convert
527 otherwise. Instead, a JSON \f(CW\*(C`null\*(C'\fR value is encoded instead of the object.
528 .PP
529 If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will throw an
530 exception when it encounters a blessed object that it cannot convert
531 otherwise.
532 .PP
533 This setting has no effect on \f(CW\*(C`decode\*(C'\fR.
534 .SS convert_blessed
535 .IX Subsection "convert_blessed"
536 .Vb 1
537 \& $json = $json\->convert_blessed([$enable])
538 \&
539 \& $enabled = $json\->get_convert_blessed
540 .Ve
541 .PP
542 See "OBJECT SERIALISATION" for details.
543 .PP
544 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR, upon encountering a
545 blessed object, will check for the availability of the \f(CW\*(C`TO_JSON\*(C'\fR method
546 on the object\*(Aqs class. If found, it will be called in scalar context and
547 the resulting scalar will be encoded instead of the object.
548 .PP
549 The \f(CW\*(C`TO_JSON\*(C'\fR method may safely call die if it wants. If \f(CW\*(C`TO_JSON\*(C'\fR
550 returns other blessed objects, those will be handled in the same
551 way. \f(CW\*(C`TO_JSON\*(C'\fR must take care of not causing an endless recursion cycle
552 (== crash) in this case. The name of \f(CW\*(C`TO_JSON\*(C'\fR was chosen because other
553 methods called by the Perl core (== not by the user of the object) are
554 usually in upper case letters and to avoid collisions with any \f(CW\*(C`to_json\*(C'\fR
555 function or method.
556 .PP
557 If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will not consider
558 this type of conversion.
559 .PP
560 This setting has no effect on \f(CW\*(C`decode\*(C'\fR.
561 .SS allow_tags
562 .IX Subsection "allow_tags"
563 .Vb 1
564 \& $json = $json\->allow_tags([$enable])
565 \&
566 \& $enabled = $json\->get_allow_tags
567 .Ve
568 .PP
569 See "OBJECT SERIALISATION" for details.
570 .PP
571 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR, upon encountering a
572 blessed object, will check for the availability of the \f(CW\*(C`FREEZE\*(C'\fR method on
573 the object\*(Aqs class. If found, it will be used to serialise the object into
574 a nonstandard tagged JSON value (that JSON decoders cannot decode).
575 .PP
576 It also causes \f(CW\*(C`decode\*(C'\fR to parse such tagged JSON values and deserialise
577 them via a call to the \f(CW\*(C`THAW\*(C'\fR method.
578 .PP
579 If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will not consider
580 this type of conversion, and tagged JSON values will cause a parse error
581 in \f(CW\*(C`decode\*(C'\fR, as if tags were not part of the grammar.
582 .SS boolean_values
583 .IX Subsection "boolean_values"
584 .Vb 1
585 \& $json\->boolean_values([$false, $true])
586 \&
587 \& ($false, $true) = $json\->get_boolean_values
588 .Ve
589 .PP
590 By default, JSON booleans will be decoded as overloaded
591 \&\f(CW$JSON::PP::false\fR and \f(CW$JSON::PP::true\fR objects.
592 .PP
593 With this method you can specify your own boolean values for decoding \-
594 on decode, JSON \f(CW\*(C`false\*(C'\fR will be decoded as a copy of \f(CW$false\fR, and JSON
595 \&\f(CW\*(C`true\*(C'\fR will be decoded as \f(CW$true\fR ("copy" here is the same thing as
596 assigning a value to another variable, i.e. \f(CW\*(C`$copy = $false\*(C'\fR).
597 .PP
598 This is useful when you want to pass a decoded data structure directly
599 to other serialisers like YAML, Data::MessagePack and so on.
600 .PP
601 Note that this works only when you \f(CW\*(C`decode\*(C'\fR. You can set incompatible
602 boolean objects (like boolean), but when you \f(CW\*(C`encode\*(C'\fR a data structure
603 with such boolean objects, you still need to enable \f(CW\*(C`convert_blessed\*(C'\fR
604 (and add a \f(CW\*(C`TO_JSON\*(C'\fR method if necessary).
605 .PP
606 Calling this method without any arguments will reset the booleans
607 to their default values.
608 .PP
609 \&\f(CW\*(C`get_boolean_values\*(C'\fR will return both \f(CW$false\fR and \f(CW$true\fR values, or
610 the empty list when they are set to the default.
611 .SS core_bools
612 .IX Subsection "core_bools"
613 .Vb 1
614 \& $json\->core_bools([$enable]);
615 .Ve
616 .PP
617 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR, will produce standard
618 perl boolean values. Equivalent to calling:
619 .PP
620 .Vb 1
621 \& $json\->boolean_values(!!1, !!0)
622 .Ve
623 .PP
624 \&\f(CW\*(C`get_core_bools\*(C'\fR will return true if this has been set. On perl 5.36, it will
625 also return true if the boolean values have been set to perl\*(Aqs core booleans
626 using the \f(CW\*(C`boolean_values\*(C'\fR method.
627 .PP
628 The methods \f(CW\*(C`unblessed_bool\*(C'\fR and \f(CW\*(C`get_unblessed_bool\*(C'\fR are provided as aliases
629 for compatibility with Cpanel::JSON::XS.
630 .SS filter_json_object
631 .IX Subsection "filter_json_object"
632 .Vb 1
633 \& $json = $json\->filter_json_object([$coderef])
634 .Ve
635 .PP
636 When \f(CW$coderef\fR is specified, it will be called from \f(CW\*(C`decode\*(C'\fR each
637 time it decodes a JSON object. The only argument is a reference to
638 the newly\-created hash. If the code references returns a single scalar
639 (which need not be a reference), this value (or rather a copy of it) is
640 inserted into the deserialised data structure. If it returns an empty
641 list (NOTE: \fInot\fR \f(CW\*(C`undef\*(C'\fR, which is a valid scalar), the original
642 deserialised hash will be inserted. This setting can slow down decoding
643 considerably.
644 .PP
645 When \f(CW$coderef\fR is omitted or undefined, any existing callback will
646 be removed and \f(CW\*(C`decode\*(C'\fR will not change the deserialised hash in any
647 way.
648 .PP
649 Example, convert all JSON objects into the integer 5:
650 .PP
651 .Vb 5
652 \& my $js = JSON::PP\->new\->filter_json_object(sub { 5 });
653 \& # returns [5]
654 \& $js\->decode(\*(Aq[{}]\*(Aq);
655 \& # returns 5
656 \& $js\->decode(\*(Aq{"a":1, "b":2}\*(Aq);
657 .Ve
658 .SS filter_json_single_key_object
659 .IX Subsection "filter_json_single_key_object"
660 .Vb 1
661 \& $json = $json\->filter_json_single_key_object($key [=> $coderef])
662 .Ve
663 .PP
664 Works remotely similar to \f(CW\*(C`filter_json_object\*(C'\fR, but is only called for
665 JSON objects having a single key named \f(CW$key\fR.
666 .PP
667 This \f(CW$coderef\fR is called before the one specified via
668 \&\f(CW\*(C`filter_json_object\*(C'\fR, if any. It gets passed the single value in the JSON
669 object. If it returns a single value, it will be inserted into the data
670 structure. If it returns nothing (not even \f(CW\*(C`undef\*(C'\fR but the empty list),
671 the callback from \f(CW\*(C`filter_json_object\*(C'\fR will be called next, as if no
672 single\-key callback were specified.
673 .PP
674 If \f(CW$coderef\fR is omitted or undefined, the corresponding callback will be
675 disabled. There can only ever be one callback for a given key.
676 .PP
677 As this callback gets called less often then the \f(CW\*(C`filter_json_object\*(C'\fR
678 one, decoding speed will not usually suffer as much. Therefore, single\-key
679 objects make excellent targets to serialise Perl objects into, especially
680 as single\-key JSON objects are as close to the type\-tagged value concept
681 as JSON gets (it\*(Aqs basically an ID/VALUE tuple). Of course, JSON does not
682 support this in any way, so you need to make sure your data never looks
683 like a serialised Perl hash.
684 .PP
685 Typical names for the single object key are \f(CW\*(C`_\|_class_whatever_\|_\*(C'\fR, or
686 \&\f(CW\*(C`$_\|_dollars_are_rarely_used_\|_$\*(C'\fR or \f(CW\*(C`}ugly_brace_placement\*(C'\fR, or even
687 things like \f(CW\*(C`_\|_class_md5sum(classname)_\|_\*(C'\fR, to reduce the risk of clashing
688 with real hashes.
689 .PP
690 Example, decode JSON objects of the form \f(CW\*(C`{ "_\|_widget_\|_" => <id> }\*(C'\fR
691 into the corresponding \f(CW$WIDGET{<id>}\fR object:
692 .PP
693 .Vb 7
694 \& # return whatever is in $WIDGET{5}:
695 \& JSON::PP
696 \& \->new
697 \& \->filter_json_single_key_object (_\|_widget_\|_ => sub {
698 \& $WIDGET{ $_[0] }
699 \& })
700 \& \->decode (\*(Aq{"_\|_widget_\|_": 5\*(Aq)
701 \&
702 \& # this can be used with a TO_JSON method in some "widget" class
703 \& # for serialisation to json:
704 \& sub WidgetBase::TO_JSON {
705 \& my ($self) = @_;
706 \&
707 \& unless ($self\->{id}) {
708 \& $self\->{id} = ..get..some..id..;
709 \& $WIDGET{$self\->{id}} = $self;
710 \& }
711 \&
712 \& { _\|_widget_\|_ => $self\->{id} }
713 \& }
714 .Ve
715 .SS shrink
716 .IX Subsection "shrink"
717 .Vb 1
718 \& $json = $json\->shrink([$enable])
719 \&
720 \& $enabled = $json\->get_shrink
721 .Ve
722 .PP
723 If \f(CW$enable\fR is true (or missing), the string returned by \f(CW\*(C`encode\*(C'\fR will
724 be shrunk (i.e. downgraded if possible).
725 .PP
726 The actual definition of what shrink does might change in future versions,
727 but it will always try to save space at the expense of time.
728 .PP
729 If \f(CW$enable\fR is false, then JSON::PP does nothing.
730 .SS max_depth
731 .IX Subsection "max_depth"
732 .Vb 1
733 \& $json = $json\->max_depth([$maximum_nesting_depth])
734 \&
735 \& $max_depth = $json\->get_max_depth
736 .Ve
737 .PP
738 Sets the maximum nesting level (default \f(CW512\fR) accepted while encoding
739 or decoding. If a higher nesting level is detected in JSON text or a Perl
740 data structure, then the encoder and decoder will stop and croak at that
741 point.
742 .PP
743 Nesting level is defined by number of hash\- or arrayrefs that the encoder
744 needs to traverse to reach a given point or the number of \f(CW\*(C`{\*(C'\fR or \f(CW\*(C`[\*(C'\fR
745 characters without their matching closing parenthesis crossed to reach a
746 given character in a string.
747 .PP
748 Setting the maximum depth to one disallows any nesting, so that ensures
749 that the object is only a single hash/object or array.
750 .PP
751 If no argument is given, the highest possible setting will be used, which
752 is rarely useful.
753 .PP
754 See "SECURITY CONSIDERATIONS" in JSON::XS for more info on why this is useful.
755 .SS max_size
756 .IX Subsection "max_size"
757 .Vb 1
758 \& $json = $json\->max_size([$maximum_string_size])
759 \&
760 \& $max_size = $json\->get_max_size
761 .Ve
762 .PP
763 Set the maximum length a JSON text may have (in bytes) where decoding is
764 being attempted. The default is \f(CW0\fR, meaning no limit. When \f(CW\*(C`decode\*(C'\fR
765 is called on a string that is longer then this many bytes, it will not
766 attempt to decode the string but throw an exception. This setting has no
767 effect on \f(CW\*(C`encode\*(C'\fR (yet).
768 .PP
769 If no argument is given, the limit check will be deactivated (same as when
770 \&\f(CW0\fR is specified).
771 .PP
772 See "SECURITY CONSIDERATIONS" in JSON::XS for more info on why this is useful.
773 .SS encode
774 .IX Subsection "encode"
775 .Vb 1
776 \& $json_text = $json\->encode($perl_scalar)
777 .Ve
778 .PP
779 Converts the given Perl value or data structure to its JSON
780 representation. Croaks on error.
781 .SS decode
782 .IX Subsection "decode"
783 .Vb 1
784 \& $perl_scalar = $json\->decode($json_text)
785 .Ve
786 .PP
787 The opposite of \f(CW\*(C`encode\*(C'\fR: expects a JSON text and tries to parse it,
788 returning the resulting simple scalar or reference. Croaks on error.
789 .SS decode_prefix
790 .IX Subsection "decode_prefix"
791 .Vb 1
792 \& ($perl_scalar, $characters) = $json\->decode_prefix($json_text)
793 .Ve
794 .PP
795 This works like the \f(CW\*(C`decode\*(C'\fR method, but instead of raising an exception
796 when there is trailing garbage after the first JSON object, it will
797 silently stop parsing there and return the number of characters consumed
798 so far.
799 .PP
800 This is useful if your JSON texts are not delimited by an outer protocol
801 and you need to know where the JSON text ends.
802 .PP
803 .Vb 2
804 \& JSON::PP\->new\->decode_prefix ("[1] the tail")
805 \& => ([1], 3)
806 .Ve
807 .SH "FLAGS FOR JSON::PP ONLY"
808 .IX Header "FLAGS FOR JSON::PP ONLY"
809 The following flags and properties are for JSON::PP only. If you use
810 any of these, you can\*(Aqt make your application run faster by replacing
811 JSON::PP with JSON::XS. If you need these and also speed boost,
812 you might want to try Cpanel::JSON::XS, a fork of JSON::XS by
813 Reini Urban, which supports some of these (with a different set of
814 incompatibilities). Most of these historical flags are only kept
815 for backward compatibility, and should not be used in a new application.
816 .SS allow_singlequote
817 .IX Subsection "allow_singlequote"
818 .Vb 2
819 \& $json = $json\->allow_singlequote([$enable])
820 \& $enabled = $json\->get_allow_singlequote
821 .Ve
822 .PP
823 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept
824 invalid JSON texts that contain strings that begin and end with
825 single quotation marks. \f(CW\*(C`encode\*(C'\fR will not be affected in any way.
826 \&\fIBe aware that this option makes you accept invalid JSON texts
827 as if they were valid!\fR. I suggest only to use this option to
828 parse application\-specific files written by humans (configuration
829 files, resource files etc.)
830 .PP
831 If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept
832 valid JSON texts.
833 .PP
834 .Vb 3
835 \& $json\->allow_singlequote\->decode(qq|{"foo":\*(Aqbar\*(Aq}|);
836 \& $json\->allow_singlequote\->decode(qq|{\*(Aqfoo\*(Aq:"bar"}|);
837 \& $json\->allow_singlequote\->decode(qq|{\*(Aqfoo\*(Aq:\*(Aqbar\*(Aq}|);
838 .Ve
839 .SS allow_barekey
840 .IX Subsection "allow_barekey"
841 .Vb 2
842 \& $json = $json\->allow_barekey([$enable])
843 \& $enabled = $json\->get_allow_barekey
844 .Ve
845 .PP
846 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept
847 invalid JSON texts that contain JSON objects whose names don\*(Aqt
848 begin and end with quotation marks. \f(CW\*(C`encode\*(C'\fR will not be affected
849 in any way. \fIBe aware that this option makes you accept invalid JSON
850 texts as if they were valid!\fR. I suggest only to use this option to
851 parse application\-specific files written by humans (configuration
852 files, resource files etc.)
853 .PP
854 If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept
855 valid JSON texts.
856 .PP
857 .Vb 1
858 \& $json\->allow_barekey\->decode(qq|{foo:"bar"}|);
859 .Ve
860 .SS allow_bignum
861 .IX Subsection "allow_bignum"
862 .Vb 2
863 \& $json = $json\->allow_bignum([$enable])
864 \& $enabled = $json\->get_allow_bignum
865 .Ve
866 .PP
867 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will convert
868 big integers Perl cannot handle as integer into Math::BigInt
869 objects and convert floating numbers into Math::BigFloat
870 objects. \f(CW\*(C`encode\*(C'\fR will convert \f(CW\*(C`Math::BigInt\*(C'\fR and \f(CW\*(C`Math::BigFloat\*(C'\fR
871 objects into JSON numbers.
872 .PP
873 .Vb 4
874 \& $json\->allow_nonref\->allow_bignum;
875 \& $bigfloat = $json\->decode(\*(Aq2.000000000000000000000000001\*(Aq);
876 \& print $json\->encode($bigfloat);
877 \& # => 2.000000000000000000000000001
878 .Ve
879 .PP
880 See also MAPPING.
881 .SS loose
882 .IX Subsection "loose"
883 .Vb 2
884 \& $json = $json\->loose([$enable])
885 \& $enabled = $json\->get_loose
886 .Ve
887 .PP
888 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept
889 invalid JSON texts that contain unescaped [\ex00\-\ex1f\ex22\ex5c]
890 characters. \f(CW\*(C`encode\*(C'\fR will not be affected in any way.
891 \&\fIBe aware that this option makes you accept invalid JSON texts
892 as if they were valid!\fR. I suggest only to use this option to
893 parse application\-specific files written by humans (configuration
894 files, resource files etc.)
895 .PP
896 If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept
897 valid JSON texts.
898 .PP
899 .Vb 2
900 \& $json\->loose\->decode(qq|["abc
901 \& def"]|);
902 .Ve
903 .SS escape_slash
904 .IX Subsection "escape_slash"
905 .Vb 2
906 \& $json = $json\->escape_slash([$enable])
907 \& $enabled = $json\->get_escape_slash
908 .Ve
909 .PP
910 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR will explicitly
911 escape \fIslash\fR (solidus; \f(CW\*(C`U+002F\*(C'\fR) characters to reduce the risk of
912 XSS (cross site scripting) that may be caused by \f(CW\*(C`</script>\*(C'\fR
913 in a JSON text, with the cost of bloating the size of JSON texts.
914 .PP
915 This option may be useful when you embed JSON in HTML, but embedding
916 arbitrary JSON in HTML (by some HTML template toolkit or by string
917 interpolation) is risky in general. You must escape necessary
918 characters in correct order, depending on the context.
919 .PP
920 \&\f(CW\*(C`decode\*(C'\fR will not be affected in any way.
921 .SS indent_length
922 .IX Subsection "indent_length"
923 .Vb 2
924 \& $json = $json\->indent_length($number_of_spaces)
925 \& $length = $json\->get_indent_length
926 .Ve
927 .PP
928 This option is only useful when you also enable \f(CW\*(C`indent\*(C'\fR or \f(CW\*(C`pretty\*(C'\fR.
929 .PP
930 JSON::XS indents with three spaces when you \f(CW\*(C`encode\*(C'\fR (if requested
931 by \f(CW\*(C`indent\*(C'\fR or \f(CW\*(C`pretty\*(C'\fR), and the number cannot be changed.
932 JSON::PP allows you to change/get the number of indent spaces with these
933 mutator/accessor. The default number of spaces is three (the same as
934 JSON::XS), and the acceptable range is from \f(CW0\fR (no indentation;
935 it\*(Aqd be better to disable indentation by \f(CWindent(0)\fR) to \f(CW15\fR.
936 .SS sort_by
937 .IX Subsection "sort_by"
938 .Vb 2
939 \& $json = $json\->sort_by($code_ref)
940 \& $json = $json\->sort_by($subroutine_name)
941 .Ve
942 .PP
943 If you just want to sort keys (names) in JSON objects when you
944 \&\f(CW\*(C`encode\*(C'\fR, enable \f(CW\*(C`canonical\*(C'\fR option (see above) that allows you to
945 sort object keys alphabetically.
946 .PP
947 If you do need to sort non\-alphabetically for whatever reasons,
948 you can give a code reference (or a subroutine name) to \f(CW\*(C`sort_by\*(C'\fR,
949 then the argument will be passed to Perl\*(Aqs \f(CW\*(C`sort\*(C'\fR built\-in function.
950 .PP
951 As the sorting is done in the JSON::PP scope, you usually need to
952 prepend \f(CW\*(C`JSON::PP::\*(C'\fR to the subroutine name, and the special variables
953 \&\f(CW$a\fR and \f(CW$b\fR used in the subrontine used by \f(CW\*(C`sort\*(C'\fR function.
954 .PP
955 Example:
956 .PP
957 .Vb 9
958 \& my %ORDER = (id => 1, class => 2, name => 3);
959 \& $json\->sort_by(sub {
960 \& ($ORDER{$JSON::PP::a} // 999) <=> ($ORDER{$JSON::PP::b} // 999)
961 \& or $JSON::PP::a cmp $JSON::PP::b
962 \& });
963 \& print $json\->encode([
964 \& {name => \*(AqCPAN\*(Aq, id => 1, href => \*(Aqhttp://cpan.org\*(Aq}
965 \& ]);
966 \& # [{"id":1,"name":"CPAN","href":"http://cpan.org"}]
967 .Ve
968 .PP
969 Note that \f(CW\*(C`sort_by\*(C'\fR affects all the plain hashes in the data structure.
970 If you need finer control, \f(CW\*(C`tie\*(C'\fR necessary hashes with a module that
971 implements ordered hash (such as Hash::Ordered and Tie::IxHash).
972 \&\f(CW\*(C`canonical\*(C'\fR and \f(CW\*(C`sort_by\*(C'\fR don\*(Aqt affect the key order in \f(CW\*(C`tie\*(C'\fRd
973 hashes.
974 .PP
975 .Vb 5
976 \& use Hash::Ordered;
977 \& tie my %hash, \*(AqHash::Ordered\*(Aq,
978 \& (name => \*(AqCPAN\*(Aq, id => 1, href => \*(Aqhttp://cpan.org\*(Aq);
979 \& print $json\->encode([\e%hash]);
980 \& # [{"name":"CPAN","id":1,"href":"http://cpan.org"}] # order is kept
981 .Ve
982 .SH "INCREMENTAL PARSING"
983 .IX Header "INCREMENTAL PARSING"
984 This section is also taken from JSON::XS.
985 .PP
986 In some cases, there is the need for incremental parsing of JSON
987 texts. While this module always has to keep both JSON text and resulting
988 Perl data structure in memory at one time, it does allow you to parse a
989 JSON stream incrementally. It does so by accumulating text until it has
990 a full JSON object, which it then can decode. This process is similar to
991 using \f(CW\*(C`decode_prefix\*(C'\fR to see if a full JSON object is available, but
992 is much more efficient (and can be implemented with a minimum of method
993 calls).
994 .PP
995 JSON::PP will only attempt to parse the JSON text once it is sure it
996 has enough text to get a decisive result, using a very simple but
997 truly incremental parser. This means that it sometimes won\*(Aqt stop as
998 early as the full parser, for example, it doesn\*(Aqt detect mismatched
999 parentheses. The only thing it guarantees is that it starts decoding as
1000 soon as a syntactically valid JSON text has been seen. This means you need
1001 to set resource limits (e.g. \f(CW\*(C`max_size\*(C'\fR) to ensure the parser will stop
1002 parsing in the presence if syntax errors.
1003 .PP
1004 The following methods implement this incremental parser.
1005 .SS incr_parse
1006 .IX Subsection "incr_parse"
1007 .Vb 1
1008 \& $json\->incr_parse( [$string] ) # void context
1009 \&
1010 \& $obj_or_undef = $json\->incr_parse( [$string] ) # scalar context
1011 \&
1012 \& @obj_or_empty = $json\->incr_parse( [$string] ) # list context
1013 .Ve
1014 .PP
1015 This is the central parsing function. It can both append new text and
1016 extract objects from the stream accumulated so far (both of these
1017 functions are optional).
1018 .PP
1019 If \f(CW$string\fR is given, then this string is appended to the already
1020 existing JSON fragment stored in the \f(CW$json\fR object.
1021 .PP
1022 After that, if the function is called in void context, it will simply
1023 return without doing anything further. This can be used to add more text
1024 in as many chunks as you want.
1025 .PP
1026 If the method is called in scalar context, then it will try to extract
1027 exactly \fIone\fR JSON object. If that is successful, it will return this
1028 object, otherwise it will return \f(CW\*(C`undef\*(C'\fR. If there is a parse error,
1029 this method will croak just as \f(CW\*(C`decode\*(C'\fR would do (one can then use
1030 \&\f(CW\*(C`incr_skip\*(C'\fR to skip the erroneous part). This is the most common way of
1031 using the method.
1032 .PP
1033 And finally, in list context, it will try to extract as many objects
1034 from the stream as it can find and return them, or the empty list
1035 otherwise. For this to work, there must be no separators (other than
1036 whitespace) between the JSON objects or arrays, instead they must be
1037 concatenated back\-to\-back. If an error occurs, an exception will be
1038 raised as in the scalar context case. Note that in this case, any
1039 previously\-parsed JSON texts will be lost.
1040 .PP
1041 Example: Parse some JSON arrays/objects in a given string and return
1042 them.
1043 .PP
1044 .Vb 1
1045 \& my @objs = JSON::PP\->new\->incr_parse ("[5][7][1,2]");
1046 .Ve
1047 .SS incr_text
1048 .IX Subsection "incr_text"
1049 .Vb 1
1050 \& $lvalue_string = $json\->incr_text
1051 .Ve
1052 .PP
1053 This method returns the currently stored JSON fragment as an lvalue, that
1054 is, you can manipulate it. This \fIonly\fR works when a preceding call to
1055 \&\f(CW\*(C`incr_parse\*(C'\fR in \fIscalar context\fR successfully returned an object. Under
1056 all other circumstances you must not call this function (I mean it.
1057 although in simple tests it might actually work, it \fIwill\fR fail under
1058 real world conditions). As a special exception, you can also call this
1059 method before having parsed anything.
1060 .PP
1061 That means you can only use this function to look at or manipulate text
1062 before or after complete JSON objects, not while the parser is in the
1063 middle of parsing a JSON object.
1064 .PP
1065 This function is useful in two cases: a) finding the trailing text after a
1066 JSON object or b) parsing multiple JSON objects separated by non\-JSON text
1067 (such as commas).
1068 .SS incr_skip
1069 .IX Subsection "incr_skip"
1070 .Vb 1
1071 \& $json\->incr_skip
1072 .Ve
1073 .PP
1074 This will reset the state of the incremental parser and will remove
1075 the parsed text from the input buffer so far. This is useful after
1076 \&\f(CW\*(C`incr_parse\*(C'\fR died, in which case the input buffer and incremental parser
1077 state is left unchanged, to skip the text parsed so far and to reset the
1078 parse state.
1079 .PP
1080 The difference to \f(CW\*(C`incr_reset\*(C'\fR is that only text until the parse error
1081 occurred is removed.
1082 .SS incr_reset
1083 .IX Subsection "incr_reset"
1084 .Vb 1
1085 \& $json\->incr_reset
1086 .Ve
1087 .PP
1088 This completely resets the incremental parser, that is, after this call,
1089 it will be as if the parser had never parsed anything.
1090 .PP
1091 This is useful if you want to repeatedly parse JSON objects and want to
1092 ignore any trailing data, which means you have to reset the parser after
1093 each successful decode.
1094 .SH MAPPING
1095 .IX Header "MAPPING"
1096 Most of this section is also taken from JSON::XS.
1097 .PP
1098 This section describes how JSON::PP maps Perl values to JSON values and
1099 vice versa. These mappings are designed to "do the right thing" in most
1100 circumstances automatically, preserving round\-tripping characteristics
1101 (what you put in comes out as something equivalent).
1102 .PP
1103 For the more enlightened: note that in the following descriptions,
1104 lowercase \fIperl\fR refers to the Perl interpreter, while uppercase \fIPerl\fR
1105 refers to the abstract Perl language itself.
1106 .SS "JSON \-> PERL"
1107 .IX Subsection "JSON -> PERL"
1108 .IP object 4
1109 .IX Item "object"
1110 A JSON object becomes a reference to a hash in Perl. No ordering of object
1111 keys is preserved (JSON does not preserve object key ordering itself).
1112 .IP array 4
1113 .IX Item "array"
1114 A JSON array becomes a reference to an array in Perl.
1115 .IP string 4
1116 .IX Item "string"
1117 A JSON string becomes a string scalar in Perl \- Unicode codepoints in JSON
1118 are represented by the same codepoints in the Perl string, so no manual
1119 decoding is necessary.
1120 .IP number 4
1121 .IX Item "number"
1122 A JSON number becomes either an integer, numeric (floating point) or
1123 string scalar in perl, depending on its range and any fractional parts. On
1124 the Perl level, there is no difference between those as Perl handles all
1125 the conversion details, but an integer may take slightly less memory and
1126 might represent more values exactly than floating point numbers.
1127 .Sp
1128 If the number consists of digits only, JSON::PP will try to represent
1129 it as an integer value. If that fails, it will try to represent it as
1130 a numeric (floating point) value if that is possible without loss of
1131 precision. Otherwise it will preserve the number as a string value (in
1132 which case you lose roundtripping ability, as the JSON number will be
1133 re\-encoded to a JSON string).
1134 .Sp
1135 Numbers containing a fractional or exponential part will always be
1136 represented as numeric (floating point) values, possibly at a loss of
1137 precision (in which case you might lose perfect roundtripping ability, but
1138 the JSON number will still be re\-encoded as a JSON number).
1139 .Sp
1140 Note that precision is not accuracy \- binary floating point values cannot
1141 represent most decimal fractions exactly, and when converting from and to
1142 floating point, JSON::PP only guarantees precision up to but not including
1143 the least significant bit.
1144 .Sp
1145 When \f(CW\*(C`allow_bignum\*(C'\fR is enabled, big integer values and any numeric
1146 values will be converted into Math::BigInt and Math::BigFloat
1147 objects respectively, without becoming string scalars or losing
1148 precision.
1149 .IP "true, false" 4
1150 .IX Item "true, false"
1151 These JSON atoms become \f(CW\*(C`JSON::PP::true\*(C'\fR and \f(CW\*(C`JSON::PP::false\*(C'\fR,
1152 respectively. They are overloaded to act almost exactly like the numbers
1153 \&\f(CW1\fR and \f(CW0\fR. You can check whether a scalar is a JSON boolean by using
1154 the \f(CW\*(C`JSON::PP::is_bool\*(C'\fR function.
1155 .IP null 4
1156 .IX Item "null"
1157 A JSON null atom becomes \f(CW\*(C`undef\*(C'\fR in Perl.
1158 .ie n .IP "shell\-style comments (""# \fItext\fR"")" 4
1159 .el .IP "shell\-style comments (\f(CW# \fR\f(CItext\fR\f(CW\fR)" 4
1160 .IX Item "shell-style comments (# text)"
1161 As a nonstandard extension to the JSON syntax that is enabled by the
1162 \&\f(CW\*(C`relaxed\*(C'\fR setting, shell\-style comments are allowed. They can start
1163 anywhere outside strings and go till the end of the line.
1164 .ie n .IP "tagged values (""(\fItag\fR)\fIvalue\fR"")." 4
1165 .el .IP "tagged values (\f(CW(\fR\f(CItag\fR\f(CW)\fR\f(CIvalue\fR\f(CW\fR)." 4
1166 .IX Item "tagged values ((tag)value)."
1167 Another nonstandard extension to the JSON syntax, enabled with the
1168 \&\f(CW\*(C`allow_tags\*(C'\fR setting, are tagged values. In this implementation, the
1169 \&\fItag\fR must be a perl package/class name encoded as a JSON string, and the
1170 \&\fIvalue\fR must be a JSON array encoding optional constructor arguments.
1171 .Sp
1172 See "OBJECT SERIALISATION", below, for details.
1173 .SS "PERL \-> JSON"
1174 .IX Subsection "PERL -> JSON"
1175 The mapping from Perl to JSON is slightly more difficult, as Perl is a
1176 truly typeless language, so we can only guess which JSON type is meant by
1177 a Perl value.
1178 .IP "hash references" 4
1179 .IX Item "hash references"
1180 Perl hash references become JSON objects. As there is no inherent
1181 ordering in hash keys (or JSON objects), they will usually be encoded
1182 in a pseudo\-random order. JSON::PP can optionally sort the hash keys
1183 (determined by the \fIcanonical\fR flag and/or \fIsort_by\fR property), so
1184 the same data structure will serialise to the same JSON text (given
1185 same settings and version of JSON::PP), but this incurs a runtime
1186 overhead and is only rarely useful, e.g. when you want to compare some
1187 JSON text against another for equality.
1188 .IP "array references" 4
1189 .IX Item "array references"
1190 Perl array references become JSON arrays.
1191 .IP "other references" 4
1192 .IX Item "other references"
1193 Other unblessed references are generally not allowed and will cause an
1194 exception to be thrown, except for references to the integers \f(CW0\fR and
1195 \&\f(CW1\fR, which get turned into \f(CW\*(C`false\*(C'\fR and \f(CW\*(C`true\*(C'\fR atoms in JSON. You can
1196 also use \f(CW\*(C`JSON::PP::false\*(C'\fR and \f(CW\*(C`JSON::PP::true\*(C'\fR to improve
1197 readability.
1198 .Sp
1199 .Vb 1
1200 \& to_json [\e0, JSON::PP::true] # yields [false,true]
1201 .Ve
1202 .IP "JSON::PP::true, JSON::PP::false" 4
1203 .IX Item "JSON::PP::true, JSON::PP::false"
1204 These special values become JSON true and JSON false values,
1205 respectively. You can also use \f(CW\*(C`\e1\*(C'\fR and \f(CW\*(C`\e0\*(C'\fR directly if you want.
1206 .IP JSON::PP::null 4
1207 .IX Item "JSON::PP::null"
1208 This special value becomes JSON null.
1209 .IP "blessed objects" 4
1210 .IX Item "blessed objects"
1211 Blessed objects are not directly representable in JSON, but \f(CW\*(C`JSON::PP\*(C'\fR
1212 allows various ways of handling objects. See "OBJECT SERIALISATION",
1213 below, for details.
1214 .IP "simple scalars" 4
1215 .IX Item "simple scalars"
1216 Simple Perl scalars (any scalar that is not a reference) are the most
1217 difficult objects to encode: JSON::PP will encode undefined scalars as
1218 JSON \f(CW\*(C`null\*(C'\fR values, scalars that have last been used in a string context
1219 before encoding as JSON strings, and anything else as number value:
1220 .Sp
1221 .Vb 4
1222 \& # dump as number
1223 \& encode_json [2] # yields [2]
1224 \& encode_json [\-3.0e17] # yields [\-3e+17]
1225 \& my $value = 5; encode_json [$value] # yields [5]
1226 \&
1227 \& # used as string, so dump as string
1228 \& print $value;
1229 \& encode_json [$value] # yields ["5"]
1230 \&
1231 \& # undef becomes null
1232 \& encode_json [undef] # yields [null]
1233 .Ve
1234 .Sp
1235 You can force the type to be a JSON string by stringifying it:
1236 .Sp
1237 .Vb 5
1238 \& my $x = 3.1; # some variable containing a number
1239 \& "$x"; # stringified
1240 \& $x .= ""; # another, more awkward way to stringify
1241 \& print $x; # perl does it for you, too, quite often
1242 \& # (but for older perls)
1243 .Ve
1244 .Sp
1245 You can force the type to be a JSON number by numifying it:
1246 .Sp
1247 .Vb 3
1248 \& my $x = "3"; # some variable containing a string
1249 \& $x += 0; # numify it, ensuring it will be dumped as a number
1250 \& $x *= 1; # same thing, the choice is yours.
1251 .Ve
1252 .Sp
1253 You can not currently force the type in other, less obscure, ways.
1254 .Sp
1255 Since version 2.91_01, JSON::PP uses a different number detection logic
1256 that converts a scalar that is possible to turn into a number safely.
1257 The new logic is slightly faster, and tends to help people who use older
1258 perl or who want to encode complicated data structure. However, this may
1259 results in a different JSON text from the one JSON::XS encodes (and
1260 thus may break tests that compare entire JSON texts). If you do
1261 need the previous behavior for compatibility or for finer control,
1262 set PERL_JSON_PP_USE_B environmental variable to true before you
1263 \&\f(CW\*(C`use\*(C'\fR JSON::PP (or JSON.pm).
1264 .Sp
1265 Note that numerical precision has the same meaning as under Perl (so
1266 binary to decimal conversion follows the same rules as in Perl, which
1267 can differ to other languages). Also, your perl interpreter might expose
1268 extensions to the floating point numbers of your platform, such as
1269 infinities or NaN\*(Aqs \- these cannot be represented in JSON, and it is an
1270 error to pass those in.
1271 .Sp
1272 JSON::PP (and JSON::XS) trusts what you pass to \f(CW\*(C`encode\*(C'\fR method
1273 (or \f(CW\*(C`encode_json\*(C'\fR function) is a clean, validated data structure with
1274 values that can be represented as valid JSON values only, because it\*(Aqs
1275 not from an external data source (as opposed to JSON texts you pass to
1276 \&\f(CW\*(C`decode\*(C'\fR or \f(CW\*(C`decode_json\*(C'\fR, which JSON::PP considers tainted and
1277 doesn\*(Aqt trust). As JSON::PP doesn\*(Aqt know exactly what you and consumers
1278 of your JSON texts want the unexpected values to be (you may want to
1279 convert them into null, or to stringify them with or without
1280 normalisation (string representation of infinities/NaN may vary
1281 depending on platforms), or to croak without conversion), you\*(Aqre advised
1282 to do what you and your consumers need before you encode, and also not
1283 to numify values that may start with values that look like a number
1284 (including infinities/NaN), without validating.
1285 .SS "OBJECT SERIALISATION"
1286 .IX Subsection "OBJECT SERIALISATION"
1287 As JSON cannot directly represent Perl objects, you have to choose between
1288 a pure JSON representation (without the ability to deserialise the object
1289 automatically again), and a nonstandard extension to the JSON syntax,
1290 tagged values.
1291 .PP
1292 \fISERIALISATION\fR
1293 .IX Subsection "SERIALISATION"
1294 .PP
1295 What happens when \f(CW\*(C`JSON::PP\*(C'\fR encounters a Perl object depends on the
1296 \&\f(CW\*(C`allow_blessed\*(C'\fR, \f(CW\*(C`convert_blessed\*(C'\fR, \f(CW\*(C`allow_tags\*(C'\fR and \f(CW\*(C`allow_bignum\*(C'\fR
1297 settings, which are used in this order:
1298 .ie n .IP "1. ""allow_tags"" is enabled and the object has a ""FREEZE"" method." 4
1299 .el .IP "1. \f(CWallow_tags\fR is enabled and the object has a \f(CWFREEZE\fR method." 4
1300 .IX Item "1. allow_tags is enabled and the object has a FREEZE method."
1301 In this case, \f(CW\*(C`JSON::PP\*(C'\fR creates a tagged JSON value, using a nonstandard
1302 extension to the JSON syntax.
1303 .Sp
1304 This works by invoking the \f(CW\*(C`FREEZE\*(C'\fR method on the object, with the first
1305 argument being the object to serialise, and the second argument being the
1306 constant string \f(CW\*(C`JSON\*(C'\fR to distinguish it from other serialisers.
1307 .Sp
1308 The \f(CW\*(C`FREEZE\*(C'\fR method can return any number of values (i.e. zero or
1309 more). These values and the paclkage/classname of the object will then be
1310 encoded as a tagged JSON value in the following format:
1311 .Sp
1312 .Vb 1
1313 \& ("classname")[FREEZE return values...]
1314 .Ve
1315 .Sp
1316 e.g.:
1317 .Sp
1318 .Vb 3
1319 \& ("URI")["http://www.google.com/"]
1320 \& ("MyDate")[2013,10,29]
1321 \& ("ImageData::JPEG")["Z3...VlCg=="]
1322 .Ve
1323 .Sp
1324 For example, the hypothetical \f(CW\*(C`My::Object\*(C'\fR \f(CW\*(C`FREEZE\*(C'\fR method might use the
1325 objects \f(CW\*(C`type\*(C'\fR and \f(CW\*(C`id\*(C'\fR members to encode the object:
1326 .Sp
1327 .Vb 2
1328 \& sub My::Object::FREEZE {
1329 \& my ($self, $serialiser) = @_;
1330 \&
1331 \& ($self\->{type}, $self\->{id})
1332 \& }
1333 .Ve
1334 .ie n .IP "2. ""convert_blessed"" is enabled and the object has a ""TO_JSON"" method." 4
1335 .el .IP "2. \f(CWconvert_blessed\fR is enabled and the object has a \f(CWTO_JSON\fR method." 4
1336 .IX Item "2. convert_blessed is enabled and the object has a TO_JSON method."
1337 In this case, the \f(CW\*(C`TO_JSON\*(C'\fR method of the object is invoked in scalar
1338 context. It must return a single scalar that can be directly encoded into
1339 JSON. This scalar replaces the object in the JSON text.
1340 .Sp
1341 For example, the following \f(CW\*(C`TO_JSON\*(C'\fR method will convert all URI
1342 objects to JSON strings when serialised. The fact that these values
1343 originally were URI objects is lost.
1344 .Sp
1345 .Vb 4
1346 \& sub URI::TO_JSON {
1347 \& my ($uri) = @_;
1348 \& $uri\->as_string
1349 \& }
1350 .Ve
1351 .ie n .IP "3. ""allow_bignum"" is enabled and the object is a ""Math::BigInt"" or ""Math::BigFloat""." 4
1352 .el .IP "3. \f(CWallow_bignum\fR is enabled and the object is a \f(CWMath::BigInt\fR or \f(CWMath::BigFloat\fR." 4
1353 .IX Item "3. allow_bignum is enabled and the object is a Math::BigInt or Math::BigFloat."
1354 The object will be serialised as a JSON number value.
1355 .ie n .IP "4. ""allow_blessed"" is enabled." 4
1356 .el .IP "4. \f(CWallow_blessed\fR is enabled." 4
1357 .IX Item "4. allow_blessed is enabled."
1358 The object will be serialised as a JSON null value.
1359 .IP "5. none of the above" 4
1360 .IX Item "5. none of the above"
1361 If none of the settings are enabled or the respective methods are missing,
1362 \&\f(CW\*(C`JSON::PP\*(C'\fR throws an exception.
1363 .PP
1364 \fIDESERIALISATION\fR
1365 .IX Subsection "DESERIALISATION"
1366 .PP
1367 For deserialisation there are only two cases to consider: either
1368 nonstandard tagging was used, in which case \f(CW\*(C`allow_tags\*(C'\fR decides,
1369 or objects cannot be automatically be deserialised, in which
1370 case you can use postprocessing or the \f(CW\*(C`filter_json_object\*(C'\fR or
1371 \&\f(CW\*(C`filter_json_single_key_object\*(C'\fR callbacks to get some real objects our of
1372 your JSON.
1373 .PP
1374 This section only considers the tagged value case: a tagged JSON object
1375 is encountered during decoding and \f(CW\*(C`allow_tags\*(C'\fR is disabled, a parse
1376 error will result (as if tagged values were not part of the grammar).
1377 .PP
1378 If \f(CW\*(C`allow_tags\*(C'\fR is enabled, \f(CW\*(C`JSON::PP\*(C'\fR will look up the \f(CW\*(C`THAW\*(C'\fR method
1379 of the package/classname used during serialisation (it will not attempt
1380 to load the package as a Perl module). If there is no such method, the
1381 decoding will fail with an error.
1382 .PP
1383 Otherwise, the \f(CW\*(C`THAW\*(C'\fR method is invoked with the classname as first
1384 argument, the constant string \f(CW\*(C`JSON\*(C'\fR as second argument, and all the
1385 values from the JSON array (the values originally returned by the
1386 \&\f(CW\*(C`FREEZE\*(C'\fR method) as remaining arguments.
1387 .PP
1388 The method must then return the object. While technically you can return
1389 any Perl scalar, you might have to enable the \f(CW\*(C`allow_nonref\*(C'\fR setting to
1390 make that work in all cases, so better return an actual blessed reference.
1391 .PP
1392 As an example, let\*(Aqs implement a \f(CW\*(C`THAW\*(C'\fR function that regenerates the
1393 \&\f(CW\*(C`My::Object\*(C'\fR from the \f(CW\*(C`FREEZE\*(C'\fR example earlier:
1394 .PP
1395 .Vb 2
1396 \& sub My::Object::THAW {
1397 \& my ($class, $serialiser, $type, $id) = @_;
1398 \&
1399 \& $class\->new (type => $type, id => $id)
1400 \& }
1401 .Ve
1402 .SH "ENCODING/CODESET FLAG NOTES"
1403 .IX Header "ENCODING/CODESET FLAG NOTES"
1404 This section is taken from JSON::XS.
1405 .PP
1406 The interested reader might have seen a number of flags that signify
1407 encodings or codesets \- \f(CW\*(C`utf8\*(C'\fR, \f(CW\*(C`latin1\*(C'\fR and \f(CW\*(C`ascii\*(C'\fR. There seems to be
1408 some confusion on what these do, so here is a short comparison:
1409 .PP
1410 \&\f(CW\*(C`utf8\*(C'\fR controls whether the JSON text created by \f(CW\*(C`encode\*(C'\fR (and expected
1411 by \f(CW\*(C`decode\*(C'\fR) is UTF\-8 encoded or not, while \f(CW\*(C`latin1\*(C'\fR and \f(CW\*(C`ascii\*(C'\fR only
1412 control whether \f(CW\*(C`encode\*(C'\fR escapes character values outside their respective
1413 codeset range. Neither of these flags conflict with each other, although
1414 some combinations make less sense than others.
1415 .PP
1416 Care has been taken to make all flags symmetrical with respect to
1417 \&\f(CW\*(C`encode\*(C'\fR and \f(CW\*(C`decode\*(C'\fR, that is, texts encoded with any combination of
1418 these flag values will be correctly decoded when the same flags are used
1419 \&\- in general, if you use different flag settings while encoding vs. when
1420 decoding you likely have a bug somewhere.
1421 .PP
1422 Below comes a verbose discussion of these flags. Note that a "codeset" is
1423 simply an abstract set of character\-codepoint pairs, while an encoding
1424 takes those codepoint numbers and \fIencodes\fR them, in our case into
1425 octets. Unicode is (among other things) a codeset, UTF\-8 is an encoding,
1426 and ISO\-8859\-1 (= latin 1) and ASCII are both codesets \fIand\fR encodings at
1427 the same time, which can be confusing.
1428 .ie n .IP """utf8"" flag disabled" 4
1429 .el .IP "\f(CWutf8\fR flag disabled" 4
1430 .IX Item "utf8 flag disabled"
1431 When \f(CW\*(C`utf8\*(C'\fR is disabled (the default), then \f(CW\*(C`encode\*(C'\fR/\f(CW\*(C`decode\*(C'\fR generate
1432 and expect Unicode strings, that is, characters with high ordinal Unicode
1433 values (> 255) will be encoded as such characters, and likewise such
1434 characters are decoded as\-is, no changes to them will be done, except
1435 "(re\-)interpreting" them as Unicode codepoints or Unicode characters,
1436 respectively (to Perl, these are the same thing in strings unless you do
1437 funny/weird/dumb stuff).
1438 .Sp
1439 This is useful when you want to do the encoding yourself (e.g. when you
1440 want to have UTF\-16 encoded JSON texts) or when some other layer does
1441 the encoding for you (for example, when printing to a terminal using a
1442 filehandle that transparently encodes to UTF\-8 you certainly do NOT want
1443 to UTF\-8 encode your data first and have Perl encode it another time).
1444 .ie n .IP """utf8"" flag enabled" 4
1445 .el .IP "\f(CWutf8\fR flag enabled" 4
1446 .IX Item "utf8 flag enabled"
1447 If the \f(CW\*(C`utf8\*(C'\fR\-flag is enabled, \f(CW\*(C`encode\*(C'\fR/\f(CW\*(C`decode\*(C'\fR will encode all
1448 characters using the corresponding UTF\-8 multi\-byte sequence, and will
1449 expect your input strings to be encoded as UTF\-8, that is, no "character"
1450 of the input string must have any value > 255, as UTF\-8 does not allow
1451 that.
1452 .Sp
1453 The \f(CW\*(C`utf8\*(C'\fR flag therefore switches between two modes: disabled means you
1454 will get a Unicode string in Perl, enabled means you get an UTF\-8 encoded
1455 octet/binary string in Perl.
1456 .ie n .IP """latin1"" or ""ascii"" flags enabled" 4
1457 .el .IP "\f(CWlatin1\fR or \f(CWascii\fR flags enabled" 4
1458 .IX Item "latin1 or ascii flags enabled"
1459 With \f(CW\*(C`latin1\*(C'\fR (or \f(CW\*(C`ascii\*(C'\fR) enabled, \f(CW\*(C`encode\*(C'\fR will escape characters
1460 with ordinal values > 255 (> 127 with \f(CW\*(C`ascii\*(C'\fR) and encode the remaining
1461 characters as specified by the \f(CW\*(C`utf8\*(C'\fR flag.
1462 .Sp
1463 If \f(CW\*(C`utf8\*(C'\fR is disabled, then the result is also correctly encoded in those
1464 character sets (as both are proper subsets of Unicode, meaning that a
1465 Unicode string with all character values < 256 is the same thing as a
1466 ISO\-8859\-1 string, and a Unicode string with all character values < 128 is
1467 the same thing as an ASCII string in Perl).
1468 .Sp
1469 If \f(CW\*(C`utf8\*(C'\fR is enabled, you still get a correct UTF\-8\-encoded string,
1470 regardless of these flags, just some more characters will be escaped using
1471 \&\f(CW\*(C`\euXXXX\*(C'\fR then before.
1472 .Sp
1473 Note that ISO\-8859\-1\-\fIencoded\fR strings are not compatible with UTF\-8
1474 encoding, while ASCII\-encoded strings are. That is because the ISO\-8859\-1
1475 encoding is NOT a subset of UTF\-8 (despite the ISO\-8859\-1 \fIcodeset\fR being
1476 a subset of Unicode), while ASCII is.
1477 .Sp
1478 Surprisingly, \f(CW\*(C`decode\*(C'\fR will ignore these flags and so treat all input
1479 values as governed by the \f(CW\*(C`utf8\*(C'\fR flag. If it is disabled, this allows you
1480 to decode ISO\-8859\-1\- and ASCII\-encoded strings, as both strict subsets of
1481 Unicode. If it is enabled, you can correctly decode UTF\-8 encoded strings.
1482 .Sp
1483 So neither \f(CW\*(C`latin1\*(C'\fR nor \f(CW\*(C`ascii\*(C'\fR are incompatible with the \f(CW\*(C`utf8\*(C'\fR flag \-
1484 they only govern when the JSON output engine escapes a character or not.
1485 .Sp
1486 The main use for \f(CW\*(C`latin1\*(C'\fR is to relatively efficiently store binary data
1487 as JSON, at the expense of breaking compatibility with most JSON decoders.
1488 .Sp
1489 The main use for \f(CW\*(C`ascii\*(C'\fR is to force the output to not contain characters
1490 with values > 127, which means you can interpret the resulting string
1491 as UTF\-8, ISO\-8859\-1, ASCII, KOI8\-R or most about any character set and
1492 8\-bit\-encoding, and still get the same data structure back. This is useful
1493 when your channel for JSON transfer is not 8\-bit clean or the encoding
1494 might be mangled in between (e.g. in mail), and works because ASCII is a
1495 proper subset of most 8\-bit and multibyte encodings in use in the world.
1496 .SH BUGS
1497 .IX Header "BUGS"
1498 Please report bugs on a specific behavior of this module to RT or GitHub
1499 issues (preferred):
1500 .PP
1501 <https://github.com/makamaka/JSON\-PP/issues>
1502 .PP
1503 <https://rt.cpan.org/Public/Dist/Display.html?Queue=JSON\-PP>
1504 .PP
1505 As for new features and requests to change common behaviors, please
1506 ask the author of JSON::XS (Marc Lehmann, <schmorp[at]schmorp.de>)
1507 first, by email (important!), to keep compatibility among JSON.pm backends.
1508 .PP
1509 Generally speaking, if you need something special for you, you are advised
1510 to create a new module, maybe based on JSON::Tiny, which is smaller and
1511 written in a much cleaner way than this module.
1512 .SH "SEE ALSO"
1513 .IX Header "SEE ALSO"
1514 The \fIjson_pp\fR command line utility for quick experiments.
1515 .PP
1516 JSON::XS, Cpanel::JSON::XS, and JSON::Tiny for faster alternatives.
1517 JSON and JSON::MaybeXS for easy migration.
1518 .PP
1519 JSON::PP::Compat5005 and JSON::PP::Compat5006 for older perl users.
1520 .PP
1521 RFC4627 (<http://www.ietf.org/rfc/rfc4627.txt>)
1522 .PP
1523 RFC7159 (<http://www.ietf.org/rfc/rfc7159.txt>)
1524 .PP
1525 RFC8259 (<http://www.ietf.org/rfc/rfc8259.txt>)
1526 .SH AUTHOR
1527 .IX Header "AUTHOR"
1528 Makamaka Hannyaharamitu, <makamaka[at]cpan.org>
1529 .SH "CURRENT MAINTAINER"
1530 .IX Header "CURRENT MAINTAINER"
1531 Kenichi Ishigaki, <ishigaki[at]cpan.org>
1532 .SH "COPYRIGHT AND LICENSE"
1533 .IX Header "COPYRIGHT AND LICENSE"
1534 Copyright 2007\-2016 by Makamaka Hannyaharamitu
1535 .PP
1536 Most of the documentation is taken from JSON::XS by Marc Lehmann
1537 .PP
1538 This library is free software; you can redistribute it and/or modify
1539 it under the same terms as Perl itself.