Debian Codegraph @

upstream/debian-unstable/man3/JSON::PP.3perl

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