1JSON::backportPP(3) User Contributed Perl Documentation JSON::backportPP(3)
2
6 JSON::PP - JSON::XS compatible pure-Perl module.
7
9 use JSON::PP;
10 # exported functions, they croak on error
12 # and expect/generate UTF-8
13 $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
15 $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text;
16 # OO-interface
18 $json = JSON::PP->new->ascii->pretty->allow_nonref;
20 $pretty_printed_json_text = $json->encode( $perl_scalar );
22 $perl_scalar = $json->decode( $json_text );
23 # Note that JSON version 2.0 and above will automatically use
25 # JSON::XS or JSON::PP, so you should be able to just:
26 use JSON;
28
30 JSON::PP is a pure perl JSON decoder/encoder, and (almost) compatible
31 to much faster JSON::XS written by Marc Lehmann in C. JSON::PP works as
32 a fallback module when you use JSON module without having installed
33 JSON::XS.
34 Because of this fallback feature of JSON.pm, JSON::PP tries not to be
36 more JavaScript-friendly than JSON::XS (i.e. not to escape extra
37 characters such as U+2028 and U+2029, etc), in order for you not to
38 lose such JavaScript-friendliness silently when you use JSON.pm and
39 install JSON::XS for speed or by accident. If you need JavaScript-
40 friendly RFC7159-compliant pure perl module, try JSON::Tiny, which is
41 derived from Mojolicious web framework and is also smaller and faster
42 than JSON::PP.
43 JSON::PP has been in the Perl core since Perl 5.14, mainly for CPAN
45 toolchain modules to parse META.json.
46
48 This section is taken from JSON::XS almost verbatim. "encode_json" and
49 "decode_json" are exported by default.
50 encode_json
52 $json_text = encode_json $perl_scalar
53 Converts the given Perl data structure to a UTF-8 encoded, binary
55 string (that is, the string contains octets only). Croaks on error.
56 This function call is functionally identical to:
58 $json_text = JSON::PP->new->utf8->encode($perl_scalar)
60 Except being faster.
62 decode_json
64 $perl_scalar = decode_json $json_text
65 The opposite of "encode_json": expects an UTF-8 (binary) string and
67 tries to parse that as an UTF-8 encoded JSON text, returning the
68 resulting reference. Croaks on error.
69 This function call is functionally identical to:
71 $perl_scalar = JSON::PP->new->utf8->decode($json_text)
73 Except being faster.
75 JSON::PP::is_bool
77 $is_boolean = JSON::PP::is_bool($scalar)
78 Returns true if the passed scalar represents either JSON::PP::true or
80 JSON::PP::false, two constants that act like 1 and 0 respectively and
81 are also used to represent JSON "true" and "false" in Perl strings.
82 On perl 5.36 and above, will also return true when given one of perl's
84 standard boolean values, such as the result of a comparison.
85 See MAPPING, below, for more information on how JSON values are mapped
87 to Perl.
88
90 This section is also taken from JSON::XS.
91 The object oriented interface lets you configure your own encoding or
93 decoding style, within the limits of supported formats.
94 new
96 $json = JSON::PP->new
97 Creates a new JSON::PP object that can be used to de/encode JSON
99 strings. All boolean flags described below are by default disabled
100 (with the exception of "allow_nonref", which defaults to enabled since
101 version 4.0).
102 The mutators for flags all return the JSON::PP object again and thus
104 calls can be chained:
105 my $json = JSON::PP->new->utf8->space_after->encode({a => [1,2]})
107 => {"a": [1, 2]}
108 ascii
110 $json = $json->ascii([$enable])
111 $enabled = $json->get_ascii
113 If $enable is true (or missing), then the "encode" method will not
115 generate characters outside the code range 0..127 (which is ASCII). Any
116 Unicode characters outside that range will be escaped using either a
117 single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape
118 sequence, as per RFC4627. The resulting encoded JSON text can be
119 treated as a native Unicode string, an ascii-encoded, latin1-encoded or
120 UTF-8 encoded string, or any other superset of ASCII.
121 If $enable is false, then the "encode" method will not escape Unicode
123 characters unless required by the JSON syntax or other flags. This
124 results in a faster and more compact format.
125 See also the section ENCODING/CODESET FLAG NOTES later in this
127 document.
128 The main use for this flag is to produce JSON texts that can be
130 transmitted over a 7-bit channel, as the encoded JSON texts will not
131 contain any 8 bit characters.
132 JSON::PP->new->ascii(1)->encode([chr 0x10401])
134 => ["\ud801\udc01"]
135 latin1
137 $json = $json->latin1([$enable])
138 $enabled = $json->get_latin1
140 If $enable is true (or missing), then the "encode" method will encode
142 the resulting JSON text as latin1 (or iso-8859-1), escaping any
143 characters outside the code range 0..255. The resulting string can be
144 treated as a latin1-encoded JSON text or a native Unicode string. The
145 "decode" method will not be affected in any way by this flag, as
146 "decode" by default expects Unicode, which is a strict superset of
147 latin1.
148 If $enable is false, then the "encode" method will not escape Unicode
150 characters unless required by the JSON syntax or other flags.
151 See also the section ENCODING/CODESET FLAG NOTES later in this
153 document.
154 The main use for this flag is efficiently encoding binary data as JSON
156 text, as most octets will not be escaped, resulting in a smaller
157 encoded size. The disadvantage is that the resulting JSON text is
158 encoded in latin1 (and must correctly be treated as such when storing
159 and transferring), a rare encoding for JSON. It is therefore most
160 useful when you want to store data structures known to contain binary
161 data efficiently in files or databases, not when talking to other JSON
162 encoders/decoders.
163 JSON::PP->new->latin1->encode (["\x{89}\x{abc}"]
165 => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not)
166 utf8
168 $json = $json->utf8([$enable])
169 $enabled = $json->get_utf8
171 If $enable is true (or missing), then the "encode" method will encode
173 the JSON result into UTF-8, as required by many protocols, while the
174 "decode" method expects to be handled an UTF-8-encoded string. Please
175 note that UTF-8-encoded strings do not contain any characters outside
176 the range 0..255, they are thus useful for bytewise/binary I/O. In
177 future versions, enabling this option might enable autodetection of the
178 UTF-16 and UTF-32 encoding families, as described in RFC4627.
179 If $enable is false, then the "encode" method will return the JSON
181 string as a (non-encoded) Unicode string, while "decode" expects thus a
182 Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16)
183 needs to be done yourself, e.g. using the Encode module.
184 See also the section ENCODING/CODESET FLAG NOTES later in this
186 document.
187 Example, output UTF-16BE-encoded JSON:
189 use Encode;
191 $jsontext = encode "UTF-16BE", JSON::PP->new->encode ($object);
192 Example, decode UTF-32LE-encoded JSON:
194 use Encode;
196 $object = JSON::PP->new->decode (decode "UTF-32LE", $jsontext);
197 pretty
199 $json = $json->pretty([$enable])
200 This enables (or disables) all of the "indent", "space_before" and
202 "space_after" (and in the future possibly more) flags in one call to
203 generate the most readable (or most compact) form possible.
204 indent
206 $json = $json->indent([$enable])
207 $enabled = $json->get_indent
209 If $enable is true (or missing), then the "encode" method will use a
211 multiline format as output, putting every array member or object/hash
212 key-value pair into its own line, indenting them properly.
213 If $enable is false, no newlines or indenting will be produced, and the
215 resulting JSON text is guaranteed not to contain any "newlines".
216 This setting has no effect when decoding JSON texts.
218 The default indent space length is three. You can use "indent_length"
220 to change the length.
221 space_before
223 $json = $json->space_before([$enable])
224 $enabled = $json->get_space_before
226 If $enable is true (or missing), then the "encode" method will add an
228 extra optional space before the ":" separating keys from values in JSON
229 objects.
230 If $enable is false, then the "encode" method will not add any extra
232 space at those places.
233 This setting has no effect when decoding JSON texts. You will also most
235 likely combine this setting with "space_after".
236 Example, space_before enabled, space_after and indent disabled:
238 {"key" :"value"}
240 space_after
242 $json = $json->space_after([$enable])
243 $enabled = $json->get_space_after
245 If $enable is true (or missing), then the "encode" method will add an
247 extra optional space after the ":" separating keys from values in JSON
248 objects and extra whitespace after the "," separating key-value pairs
249 and array members.
250 If $enable is false, then the "encode" method will not add any extra
252 space at those places.
253 This setting has no effect when decoding JSON texts.
255 Example, space_before and indent disabled, space_after enabled:
257 {"key": "value"}
259 relaxed
261 $json = $json->relaxed([$enable])
262 $enabled = $json->get_relaxed
264 If $enable is true (or missing), then "decode" will accept some
266 extensions to normal JSON syntax (see below). "encode" will not be
267 affected in anyway. Be aware that this option makes you accept invalid
268 JSON texts as if they were valid!. I suggest only to use this option to
269 parse application-specific files written by humans (configuration
270 files, resource files etc.)
271 If $enable is false (the default), then "decode" will only accept valid
273 JSON texts.
274 Currently accepted extensions are:
276 • list items can have an end-comma
278 JSON separates array elements and key-value pairs with commas. This
280 can be annoying if you write JSON texts manually and want to be
281 able to quickly append elements, so this extension accepts comma at
282 the end of such items not just between them:
283 [
285 1,
286 2, <- this comma not normally allowed
287 ]
288 {
289 "k1": "v1",
290 "k2": "v2", <- this comma not normally allowed
291 }
292 • shell-style '#'-comments
294 Whenever JSON allows whitespace, shell-style comments are
296 additionally allowed. They are terminated by the first carriage-
297 return or line-feed character, after which more white-space and
298 comments are allowed.
299 [
301 1, # this comment not allowed in JSON
302 # neither this one...
303 ]
304 • C-style multiple-line '/* */'-comments (JSON::PP only)
306 Whenever JSON allows whitespace, C-style multiple-line comments are
308 additionally allowed. Everything between "/*" and "*/" is a
309 comment, after which more white-space and comments are allowed.
310 [
312 1, /* this comment not allowed in JSON */
313 /* neither this one... */
314 ]
315 • C++-style one-line '//'-comments (JSON::PP only)
317 Whenever JSON allows whitespace, C++-style one-line comments are
319 additionally allowed. They are terminated by the first carriage-
320 return or line-feed character, after which more white-space and
321 comments are allowed.
322 [
324 1, // this comment not allowed in JSON
325 // neither this one...
326 ]
327 • literal ASCII TAB characters in strings
329 Literal ASCII TAB characters are now allowed in strings (and
331 treated as "\t").
332 [
334 "Hello\tWorld",
335 "Hello<TAB>World", # literal <TAB> would not normally be allowed
336 ]
337 canonical
339 $json = $json->canonical([$enable])
340 $enabled = $json->get_canonical
342 If $enable is true (or missing), then the "encode" method will output
344 JSON objects by sorting their keys. This is adding a comparatively high
345 overhead.
346 If $enable is false, then the "encode" method will output key-value
348 pairs in the order Perl stores them (which will likely change between
349 runs of the same script, and can change even within the same run from
350 5.18 onwards).
351 This option is useful if you want the same data structure to be encoded
353 as the same JSON text (given the same overall settings). If it is
354 disabled, the same hash might be encoded differently even if contains
355 the same data, as key-value pairs have no inherent ordering in Perl.
356 This setting has no effect when decoding JSON texts.
358 This setting has currently no effect on tied hashes.
360 allow_nonref
362 $json = $json->allow_nonref([$enable])
363 $enabled = $json->get_allow_nonref
365 Unlike other boolean options, this opotion is enabled by default
367 beginning with version 4.0.
368 If $enable is true (or missing), then the "encode" method can convert a
370 non-reference into its corresponding string, number or null JSON value,
371 which is an extension to RFC4627. Likewise, "decode" will accept those
372 JSON values instead of croaking.
373 If $enable is false, then the "encode" method will croak if it isn't
375 passed an arrayref or hashref, as JSON texts must either be an object
376 or array. Likewise, "decode" will croak if given something that is not
377 a JSON object or array.
378 Example, encode a Perl scalar as JSON value without enabled
380 "allow_nonref", resulting in an error:
381 JSON::PP->new->allow_nonref(0)->encode ("Hello, World!")
383 => hash- or arrayref expected...
384 allow_unknown
386 $json = $json->allow_unknown([$enable])
387 $enabled = $json->get_allow_unknown
389 If $enable is true (or missing), then "encode" will not throw an
391 exception when it encounters values it cannot represent in JSON (for
392 example, filehandles) but instead will encode a JSON "null" value. Note
393 that blessed objects are not included here and are handled separately
394 by c<allow_blessed>.
395 If $enable is false (the default), then "encode" will throw an
397 exception when it encounters anything it cannot encode as JSON.
398 This option does not affect "decode" in any way, and it is recommended
400 to leave it off unless you know your communications partner.
401 allow_blessed
403 $json = $json->allow_blessed([$enable])
404 $enabled = $json->get_allow_blessed
406 See "OBJECT SERIALISATION" for details.
408 If $enable is true (or missing), then the "encode" method will not barf
410 when it encounters a blessed reference that it cannot convert
411 otherwise. Instead, a JSON "null" value is encoded instead of the
412 object.
413 If $enable is false (the default), then "encode" will throw an
415 exception when it encounters a blessed object that it cannot convert
416 otherwise.
417 This setting has no effect on "decode".
419 convert_blessed
421 $json = $json->convert_blessed([$enable])
422 $enabled = $json->get_convert_blessed
424 See "OBJECT SERIALISATION" for details.
426 If $enable is true (or missing), then "encode", upon encountering a
428 blessed object, will check for the availability of the "TO_JSON" method
429 on the object's class. If found, it will be called in scalar context
430 and the resulting scalar will be encoded instead of the object.
431 The "TO_JSON" method may safely call die if it wants. If "TO_JSON"
433 returns other blessed objects, those will be handled in the same way.
434 "TO_JSON" must take care of not causing an endless recursion cycle (==
435 crash) in this case. The name of "TO_JSON" was chosen because other
436 methods called by the Perl core (== not by the user of the object) are
437 usually in upper case letters and to avoid collisions with any
438 "to_json" function or method.
439 If $enable is false (the default), then "encode" will not consider this
441 type of conversion.
442 This setting has no effect on "decode".
444 allow_tags
446 $json = $json->allow_tags([$enable])
447 $enabled = $json->get_allow_tags
449 See "OBJECT SERIALISATION" for details.
451 If $enable is true (or missing), then "encode", upon encountering a
453 blessed object, will check for the availability of the "FREEZE" method
454 on the object's class. If found, it will be used to serialise the
455 object into a nonstandard tagged JSON value (that JSON decoders cannot
456 decode).
457 It also causes "decode" to parse such tagged JSON values and
459 deserialise them via a call to the "THAW" method.
460 If $enable is false (the default), then "encode" will not consider this
462 type of conversion, and tagged JSON values will cause a parse error in
463 "decode", as if tags were not part of the grammar.
464 boolean_values
466 $json->boolean_values([$false, $true])
467 ($false, $true) = $json->get_boolean_values
469 By default, JSON booleans will be decoded as overloaded
471 $JSON::PP::false and $JSON::PP::true objects.
472 With this method you can specify your own boolean values for decoding -
474 on decode, JSON "false" will be decoded as a copy of $false, and JSON
475 "true" will be decoded as $true ("copy" here is the same thing as
476 assigning a value to another variable, i.e. "$copy = $false").
477 This is useful when you want to pass a decoded data structure directly
479 to other serialisers like YAML, Data::MessagePack and so on.
480 Note that this works only when you "decode". You can set incompatible
482 boolean objects (like boolean), but when you "encode" a data structure
483 with such boolean objects, you still need to enable "convert_blessed"
484 (and add a "TO_JSON" method if necessary).
485 Calling this method without any arguments will reset the booleans to
487 their default values.
488 "get_boolean_values" will return both $false and $true values, or the
490 empty list when they are set to the default.
491 core_bools
493 $json->core_bools([$enable]);
494 If $enable is true (or missing), then "decode", will produce standard
496 perl boolean values. Equivalent to calling:
497 $json->boolean_values(!!1, !!0)
499 "get_core_bools" will return true if this has been set. On perl 5.36,
501 it will also return true if the boolean values have been set to perl's
502 core booleans using the "boolean_values" method.
503 The methods "unblessed_bool" and "get_unblessed_bool" are provided as
505 aliases for compatibility with Cpanel::JSON::XS.
506 filter_json_object
508 $json = $json->filter_json_object([$coderef])
509 When $coderef is specified, it will be called from "decode" each time
511 it decodes a JSON object. The only argument is a reference to the
512 newly-created hash. If the code references returns a single scalar
513 (which need not be a reference), this value (or rather a copy of it) is
514 inserted into the deserialised data structure. If it returns an empty
515 list (NOTE: not "undef", which is a valid scalar), the original
516 deserialised hash will be inserted. This setting can slow down decoding
517 considerably.
518 When $coderef is omitted or undefined, any existing callback will be
520 removed and "decode" will not change the deserialised hash in any way.
521 Example, convert all JSON objects into the integer 5:
523 my $js = JSON::PP->new->filter_json_object(sub { 5 });
525 # returns [5]
526 $js->decode('[{}]');
527 # returns 5
528 $js->decode('{"a":1, "b":2}');
529 filter_json_single_key_object
531 $json = $json->filter_json_single_key_object($key [=> $coderef])
532 Works remotely similar to "filter_json_object", but is only called for
534 JSON objects having a single key named $key.
535 This $coderef is called before the one specified via
537 "filter_json_object", if any. It gets passed the single value in the
538 JSON object. If it returns a single value, it will be inserted into the
539 data structure. If it returns nothing (not even "undef" but the empty
540 list), the callback from "filter_json_object" will be called next, as
541 if no single-key callback were specified.
542 If $coderef is omitted or undefined, the corresponding callback will be
544 disabled. There can only ever be one callback for a given key.
545 As this callback gets called less often then the "filter_json_object"
547 one, decoding speed will not usually suffer as much. Therefore, single-
548 key objects make excellent targets to serialise Perl objects into,
549 especially as single-key JSON objects are as close to the type-tagged
550 value concept as JSON gets (it's basically an ID/VALUE tuple). Of
551 course, JSON does not support this in any way, so you need to make sure
552 your data never looks like a serialised Perl hash.
553 Typical names for the single object key are "__class_whatever__", or
555 "$__dollars_are_rarely_used__$" or "}ugly_brace_placement", or even
556 things like "__class_md5sum(classname)__", to reduce the risk of
557 clashing with real hashes.
558 Example, decode JSON objects of the form "{ "__widget__" => <id> }"
560 into the corresponding $WIDGET{<id>} object:
561 # return whatever is in $WIDGET{5}:
563 JSON::PP
564 ->new
565 ->filter_json_single_key_object (__widget__ => sub {
566 $WIDGET{ $_[0] }
567 })
568 ->decode ('{"__widget__": 5')
569 # this can be used with a TO_JSON method in some "widget" class
571 # for serialisation to json:
572 sub WidgetBase::TO_JSON {
573 my ($self) = @_;
574 unless ($self->{id}) {
576 $self->{id} = ..get..some..id..;
577 $WIDGET{$self->{id}} = $self;
578 }
579 { __widget__ => $self->{id} }
581 }
582 shrink
584 $json = $json->shrink([$enable])
585 $enabled = $json->get_shrink
587 If $enable is true (or missing), the string returned by "encode" will
589 be shrunk (i.e. downgraded if possible).
590 The actual definition of what shrink does might change in future
592 versions, but it will always try to save space at the expense of time.
593 If $enable is false, then JSON::PP does nothing.
595 max_depth
597 $json = $json->max_depth([$maximum_nesting_depth])
598 $max_depth = $json->get_max_depth
600 Sets the maximum nesting level (default 512) accepted while encoding or
602 decoding. If a higher nesting level is detected in JSON text or a Perl
603 data structure, then the encoder and decoder will stop and croak at
604 that point.
605 Nesting level is defined by number of hash- or arrayrefs that the
607 encoder needs to traverse to reach a given point or the number of "{"
608 or "[" characters without their matching closing parenthesis crossed to
609 reach a given character in a string.
610 Setting the maximum depth to one disallows any nesting, so that ensures
612 that the object is only a single hash/object or array.
613 If no argument is given, the highest possible setting will be used,
615 which is rarely useful.
616 See "SECURITY CONSIDERATIONS" in JSON::XS for more info on why this is
618 useful.
619 max_size
621 $json = $json->max_size([$maximum_string_size])
622 $max_size = $json->get_max_size
624 Set the maximum length a JSON text may have (in bytes) where decoding
626 is being attempted. The default is 0, meaning no limit. When "decode"
627 is called on a string that is longer then this many bytes, it will not
628 attempt to decode the string but throw an exception. This setting has
629 no effect on "encode" (yet).
630 If no argument is given, the limit check will be deactivated (same as
632 when 0 is specified).
633 See "SECURITY CONSIDERATIONS" in JSON::XS for more info on why this is
635 useful.
636 encode
638 $json_text = $json->encode($perl_scalar)
639 Converts the given Perl value or data structure to its JSON
641 representation. Croaks on error.
642 decode
644 $perl_scalar = $json->decode($json_text)
645 The opposite of "encode": expects a JSON text and tries to parse it,
647 returning the resulting simple scalar or reference. Croaks on error.
648 decode_prefix
650 ($perl_scalar, $characters) = $json->decode_prefix($json_text)
651 This works like the "decode" method, but instead of raising an
653 exception when there is trailing garbage after the first JSON object,
654 it will silently stop parsing there and return the number of characters
655 consumed so far.
656 This is useful if your JSON texts are not delimited by an outer
658 protocol and you need to know where the JSON text ends.
659 JSON::PP->new->decode_prefix ("[1] the tail")
661 => ([1], 3)
662
664 The following flags and properties are for JSON::PP only. If you use
665 any of these, you can't make your application run faster by replacing
666 JSON::PP with JSON::XS. If you need these and also speed boost, you
667 might want to try Cpanel::JSON::XS, a fork of JSON::XS by Reini Urban,
668 which supports some of these (with a different set of
669 incompatibilities). Most of these historical flags are only kept for
670 backward compatibility, and should not be used in a new application.
671 allow_singlequote
673 $json = $json->allow_singlequote([$enable])
674 $enabled = $json->get_allow_singlequote
675 If $enable is true (or missing), then "decode" will accept invalid JSON
677 texts that contain strings that begin and end with single quotation
678 marks. "encode" will not be affected in any way. Be aware that this
679 option makes you accept invalid JSON texts as if they were valid!. I
680 suggest only to use this option to parse application-specific files
681 written by humans (configuration files, resource files etc.)
682 If $enable is false (the default), then "decode" will only accept valid
684 JSON texts.
685 $json->allow_singlequote->decode(qq|{"foo":'bar'}|);
687 $json->allow_singlequote->decode(qq|{'foo':"bar"}|);
688 $json->allow_singlequote->decode(qq|{'foo':'bar'}|);
689 allow_barekey
691 $json = $json->allow_barekey([$enable])
692 $enabled = $json->get_allow_barekey
693 If $enable is true (or missing), then "decode" will accept invalid JSON
695 texts that contain JSON objects whose names don't begin and end with
696 quotation marks. "encode" will not be affected in any way. Be aware
697 that this option makes you accept invalid JSON texts as if they were
698 valid!. I suggest only to use this option to parse application-specific
699 files written by humans (configuration files, resource files etc.)
700 If $enable is false (the default), then "decode" will only accept valid
702 JSON texts.
703 $json->allow_barekey->decode(qq|{foo:"bar"}|);
705 allow_bignum
707 $json = $json->allow_bignum([$enable])
708 $enabled = $json->get_allow_bignum
709 If $enable is true (or missing), then "decode" will convert big
711 integers Perl cannot handle as integer into Math::BigInt objects and
712 convert floating numbers into Math::BigFloat objects. "encode" will
713 convert "Math::BigInt" and "Math::BigFloat" objects into JSON numbers.
714 $json->allow_nonref->allow_bignum;
716 $bigfloat = $json->decode('2.000000000000000000000000001');
717 print $json->encode($bigfloat);
718 # => 2.000000000000000000000000001
719 See also MAPPING.
721 loose
723 $json = $json->loose([$enable])
724 $enabled = $json->get_loose
725 If $enable is true (or missing), then "decode" will accept invalid JSON
727 texts that contain unescaped [\x00-\x1f\x22\x5c] characters. "encode"
728 will not be affected in any way. Be aware that this option makes you
729 accept invalid JSON texts as if they were valid!. I suggest only to use
730 this option to parse application-specific files written by humans
731 (configuration files, resource files etc.)
732 If $enable is false (the default), then "decode" will only accept valid
734 JSON texts.
735 $json->loose->decode(qq|["abc
737 def"]|);
738 escape_slash
740 $json = $json->escape_slash([$enable])
741 $enabled = $json->get_escape_slash
742 If $enable is true (or missing), then "encode" will explicitly escape
744 slash (solidus; "U+002F") characters to reduce the risk of XSS (cross
745 site scripting) that may be caused by "</script>" in a JSON text, with
746 the cost of bloating the size of JSON texts.
747 This option may be useful when you embed JSON in HTML, but embedding
749 arbitrary JSON in HTML (by some HTML template toolkit or by string
750 interpolation) is risky in general. You must escape necessary
751 characters in correct order, depending on the context.
752 "decode" will not be affected in any way.
754 indent_length
756 $json = $json->indent_length($number_of_spaces)
757 $length = $json->get_indent_length
758 This option is only useful when you also enable "indent" or "pretty".
760 JSON::XS indents with three spaces when you "encode" (if requested by
762 "indent" or "pretty"), and the number cannot be changed. JSON::PP
763 allows you to change/get the number of indent spaces with these
764 mutator/accessor. The default number of spaces is three (the same as
765 JSON::XS), and the acceptable range is from 0 (no indentation; it'd be
766 better to disable indentation by indent(0)) to 15.
767 sort_by
769 $json = $json->sort_by($code_ref)
770 $json = $json->sort_by($subroutine_name)
771 If you just want to sort keys (names) in JSON objects when you
773 "encode", enable "canonical" option (see above) that allows you to sort
774 object keys alphabetically.
775 If you do need to sort non-alphabetically for whatever reasons, you can
777 give a code reference (or a subroutine name) to "sort_by", then the
778 argument will be passed to Perl's "sort" built-in function.
779 As the sorting is done in the JSON::PP scope, you usually need to
781 prepend "JSON::PP::" to the subroutine name, and the special variables
782 $a and $b used in the subrontine used by "sort" function.
783 Example:
785 my %ORDER = (id => 1, class => 2, name => 3);
787 $json->sort_by(sub {
788 ($ORDER{$JSON::PP::a} // 999) <=> ($ORDER{$JSON::PP::b} // 999)
789 or $JSON::PP::a cmp $JSON::PP::b
790 });
791 print $json->encode([
792 {name => 'CPAN', id => 1, href => 'http://cpan.org'}
793 ]);
794 # [{"id":1,"name":"CPAN","href":"http://cpan.org"}]
795 Note that "sort_by" affects all the plain hashes in the data structure.
797 If you need finer control, "tie" necessary hashes with a module that
798 implements ordered hash (such as Hash::Ordered and Tie::IxHash).
799 "canonical" and "sort_by" don't affect the key order in "tie"d hashes.
800 use Hash::Ordered;
802 tie my %hash, 'Hash::Ordered',
803 (name => 'CPAN', id => 1, href => 'http://cpan.org');
804 print $json->encode([\%hash]);
805 # [{"name":"CPAN","id":1,"href":"http://cpan.org"}] # order is kept
806
808 This section is also taken from JSON::XS.
809 In some cases, there is the need for incremental parsing of JSON texts.
811 While this module always has to keep both JSON text and resulting Perl
812 data structure in memory at one time, it does allow you to parse a JSON
813 stream incrementally. It does so by accumulating text until it has a
814 full JSON object, which it then can decode. This process is similar to
815 using "decode_prefix" to see if a full JSON object is available, but is
816 much more efficient (and can be implemented with a minimum of method
817 calls).
818 JSON::PP will only attempt to parse the JSON text once it is sure it
820 has enough text to get a decisive result, using a very simple but truly
821 incremental parser. This means that it sometimes won't stop as early as
822 the full parser, for example, it doesn't detect mismatched parentheses.
823 The only thing it guarantees is that it starts decoding as soon as a
824 syntactically valid JSON text has been seen. This means you need to set
825 resource limits (e.g. "max_size") to ensure the parser will stop
826 parsing in the presence if syntax errors.
827 The following methods implement this incremental parser.
829 incr_parse
831 $json->incr_parse( [$string] ) # void context
832 $obj_or_undef = $json->incr_parse( [$string] ) # scalar context
834 @obj_or_empty = $json->incr_parse( [$string] ) # list context
836 This is the central parsing function. It can both append new text and
838 extract objects from the stream accumulated so far (both of these
839 functions are optional).
840 If $string is given, then this string is appended to the already
842 existing JSON fragment stored in the $json object.
843 After that, if the function is called in void context, it will simply
845 return without doing anything further. This can be used to add more
846 text in as many chunks as you want.
847 If the method is called in scalar context, then it will try to extract
849 exactly one JSON object. If that is successful, it will return this
850 object, otherwise it will return "undef". If there is a parse error,
851 this method will croak just as "decode" would do (one can then use
852 "incr_skip" to skip the erroneous part). This is the most common way of
853 using the method.
854 And finally, in list context, it will try to extract as many objects
856 from the stream as it can find and return them, or the empty list
857 otherwise. For this to work, there must be no separators (other than
858 whitespace) between the JSON objects or arrays, instead they must be
859 concatenated back-to-back. If an error occurs, an exception will be
860 raised as in the scalar context case. Note that in this case, any
861 previously-parsed JSON texts will be lost.
862 Example: Parse some JSON arrays/objects in a given string and return
864 them.
865 my @objs = JSON::PP->new->incr_parse ("[5][7][1,2]");
867 incr_text
869 $lvalue_string = $json->incr_text
870 This method returns the currently stored JSON fragment as an lvalue,
872 that is, you can manipulate it. This only works when a preceding call
873 to "incr_parse" in scalar context successfully returned an object.
874 Under all other circumstances you must not call this function (I mean
875 it. although in simple tests it might actually work, it will fail
876 under real world conditions). As a special exception, you can also call
877 this method before having parsed anything.
878 That means you can only use this function to look at or manipulate text
880 before or after complete JSON objects, not while the parser is in the
881 middle of parsing a JSON object.
882 This function is useful in two cases: a) finding the trailing text
884 after a JSON object or b) parsing multiple JSON objects separated by
885 non-JSON text (such as commas).
886 incr_skip
888 $json->incr_skip
889 This will reset the state of the incremental parser and will remove the
891 parsed text from the input buffer so far. This is useful after
892 "incr_parse" died, in which case the input buffer and incremental
893 parser state is left unchanged, to skip the text parsed so far and to
894 reset the parse state.
895 The difference to "incr_reset" is that only text until the parse error
897 occurred is removed.
898 incr_reset
900 $json->incr_reset
901 This completely resets the incremental parser, that is, after this
903 call, it will be as if the parser had never parsed anything.
904 This is useful if you want to repeatedly parse JSON objects and want to
906 ignore any trailing data, which means you have to reset the parser
907 after each successful decode.
908
910 Most of this section is also taken from JSON::XS.
911 This section describes how JSON::PP maps Perl values to JSON values and
913 vice versa. These mappings are designed to "do the right thing" in most
914 circumstances automatically, preserving round-tripping characteristics
915 (what you put in comes out as something equivalent).
916 For the more enlightened: note that in the following descriptions,
918 lowercase perl refers to the Perl interpreter, while uppercase Perl
919 refers to the abstract Perl language itself.
920 JSON -> PERL
922 object
923 A JSON object becomes a reference to a hash in Perl. No ordering of
924 object keys is preserved (JSON does not preserve object key
925 ordering itself).
926 array
928 A JSON array becomes a reference to an array in Perl.
929 string
931 A JSON string becomes a string scalar in Perl - Unicode codepoints
932 in JSON are represented by the same codepoints in the Perl string,
933 so no manual decoding is necessary.
934 number
936 A JSON number becomes either an integer, numeric (floating point)
937 or string scalar in perl, depending on its range and any fractional
938 parts. On the Perl level, there is no difference between those as
939 Perl handles all the conversion details, but an integer may take
940 slightly less memory and might represent more values exactly than
941 floating point numbers.
942 If the number consists of digits only, JSON::PP will try to
944 represent it as an integer value. If that fails, it will try to
945 represent it as a numeric (floating point) value if that is
946 possible without loss of precision. Otherwise it will preserve the
947 number as a string value (in which case you lose roundtripping
948 ability, as the JSON number will be re-encoded to a JSON string).
949 Numbers containing a fractional or exponential part will always be
951 represented as numeric (floating point) values, possibly at a loss
952 of precision (in which case you might lose perfect roundtripping
953 ability, but the JSON number will still be re-encoded as a JSON
954 number).
955 Note that precision is not accuracy - binary floating point values
957 cannot represent most decimal fractions exactly, and when
958 converting from and to floating point, JSON::PP only guarantees
959 precision up to but not including the least significant bit.
960 When "allow_bignum" is enabled, big integer values and any numeric
962 values will be converted into Math::BigInt and Math::BigFloat
963 objects respectively, without becoming string scalars or losing
964 precision.
965 true, false
967 These JSON atoms become "JSON::PP::true" and "JSON::PP::false",
968 respectively. They are overloaded to act almost exactly like the
969 numbers 1 and 0. You can check whether a scalar is a JSON boolean
970 by using the "JSON::PP::is_bool" function.
971 null
973 A JSON null atom becomes "undef" in Perl.
974 shell-style comments ("# text")
976 As a nonstandard extension to the JSON syntax that is enabled by
977 the "relaxed" setting, shell-style comments are allowed. They can
978 start anywhere outside strings and go till the end of the line.
979 tagged values ("(tag)value").
981 Another nonstandard extension to the JSON syntax, enabled with the
982 "allow_tags" setting, are tagged values. In this implementation,
983 the tag must be a perl package/class name encoded as a JSON string,
984 and the value must be a JSON array encoding optional constructor
985 arguments.
986 See "OBJECT SERIALISATION", below, for details.
988 PERL -> JSON
990 The mapping from Perl to JSON is slightly more difficult, as Perl is a
991 truly typeless language, so we can only guess which JSON type is meant
992 by a Perl value.
993 hash references
995 Perl hash references become JSON objects. As there is no inherent
996 ordering in hash keys (or JSON objects), they will usually be
997 encoded in a pseudo-random order. JSON::PP can optionally sort the
998 hash keys (determined by the canonical flag and/or sort_by
999 property), so the same data structure will serialise to the same
1000 JSON text (given same settings and version of JSON::PP), but this
1001 incurs a runtime overhead and is only rarely useful, e.g. when you
1002 want to compare some JSON text against another for equality.
1003 array references
1005 Perl array references become JSON arrays.
1006 other references
1008 Other unblessed references are generally not allowed and will cause
1009 an exception to be thrown, except for references to the integers 0
1010 and 1, which get turned into "false" and "true" atoms in JSON. You
1011 can also use "JSON::PP::false" and "JSON::PP::true" to improve
1012 readability.
1013 to_json [\0, JSON::PP::true] # yields [false,true]
1015 JSON::PP::true, JSON::PP::false
1017 These special values become JSON true and JSON false values,
1018 respectively. You can also use "\1" and "\0" directly if you want.
1019 JSON::PP::null
1021 This special value becomes JSON null.
1022 blessed objects
1024 Blessed objects are not directly representable in JSON, but
1025 "JSON::PP" allows various ways of handling objects. See "OBJECT
1026 SERIALISATION", below, for details.
1027 simple scalars
1029 Simple Perl scalars (any scalar that is not a reference) are the
1030 most difficult objects to encode: JSON::PP will encode undefined
1031 scalars as JSON "null" values, scalars that have last been used in
1032 a string context before encoding as JSON strings, and anything else
1033 as number value:
1034 # dump as number
1036 encode_json [2] # yields [2]
1037 encode_json [-3.0e17] # yields [-3e+17]
1038 my $value = 5; encode_json [$value] # yields [5]
1039 # used as string, so dump as string
1041 print $value;
1042 encode_json [$value] # yields ["5"]
1043 # undef becomes null
1045 encode_json [undef] # yields [null]
1046 You can force the type to be a JSON string by stringifying it:
1048 my $x = 3.1; # some variable containing a number
1050 "$x"; # stringified
1051 $x .= ""; # another, more awkward way to stringify
1052 print $x; # perl does it for you, too, quite often
1053 # (but for older perls)
1054 You can force the type to be a JSON number by numifying it:
1056 my $x = "3"; # some variable containing a string
1058 $x += 0; # numify it, ensuring it will be dumped as a number
1059 $x *= 1; # same thing, the choice is yours.
1060 You can not currently force the type in other, less obscure, ways.
1062 Since version 2.91_01, JSON::PP uses a different number detection
1064 logic that converts a scalar that is possible to turn into a number
1065 safely. The new logic is slightly faster, and tends to help people
1066 who use older perl or who want to encode complicated data
1067 structure. However, this may results in a different JSON text from
1068 the one JSON::XS encodes (and thus may break tests that compare
1069 entire JSON texts). If you do need the previous behavior for
1070 compatibility or for finer control, set PERL_JSON_PP_USE_B
1071 environmental variable to true before you "use" JSON::PP (or
1072 JSON.pm).
1073 Note that numerical precision has the same meaning as under Perl
1075 (so binary to decimal conversion follows the same rules as in Perl,
1076 which can differ to other languages). Also, your perl interpreter
1077 might expose extensions to the floating point numbers of your
1078 platform, such as infinities or NaN's - these cannot be represented
1079 in JSON, and it is an error to pass those in.
1080 JSON::PP (and JSON::XS) trusts what you pass to "encode" method (or
1082 "encode_json" function) is a clean, validated data structure with
1083 values that can be represented as valid JSON values only, because
1084 it's not from an external data source (as opposed to JSON texts you
1085 pass to "decode" or "decode_json", which JSON::PP considers tainted
1086 and doesn't trust). As JSON::PP doesn't know exactly what you and
1087 consumers of your JSON texts want the unexpected values to be (you
1088 may want to convert them into null, or to stringify them with or
1089 without normalisation (string representation of infinities/NaN may
1090 vary depending on platforms), or to croak without conversion),
1091 you're advised to do what you and your consumers need before you
1092 encode, and also not to numify values that may start with values
1093 that look like a number (including infinities/NaN), without
1094 validating.
1095 OBJECT SERIALISATION
1097 As JSON cannot directly represent Perl objects, you have to choose
1098 between a pure JSON representation (without the ability to deserialise
1099 the object automatically again), and a nonstandard extension to the
1100 JSON syntax, tagged values.
1101 SERIALISATION
1103 What happens when "JSON::PP" encounters a Perl object depends on the
1105 "allow_blessed", "convert_blessed", "allow_tags" and "allow_bignum"
1106 settings, which are used in this order:
1107 1. "allow_tags" is enabled and the object has a "FREEZE" method.
1109 In this case, "JSON::PP" creates a tagged JSON value, using a
1110 nonstandard extension to the JSON syntax.
1111 This works by invoking the "FREEZE" method on the object, with the
1113 first argument being the object to serialise, and the second
1114 argument being the constant string "JSON" to distinguish it from
1115 other serialisers.
1116 The "FREEZE" method can return any number of values (i.e. zero or
1118 more). These values and the paclkage/classname of the object will
1119 then be encoded as a tagged JSON value in the following format:
1120 ("classname")[FREEZE return values...]
1122 e.g.:
1124 ("URI")["http://www.google.com/"]
1126 ("MyDate")[2013,10,29]
1127 ("ImageData::JPEG")["Z3...VlCg=="]
1128 For example, the hypothetical "My::Object" "FREEZE" method might
1130 use the objects "type" and "id" members to encode the object:
1131 sub My::Object::FREEZE {
1133 my ($self, $serialiser) = @_;
1134 ($self->{type}, $self->{id})
1136 }
1137 2. "convert_blessed" is enabled and the object has a "TO_JSON" method.
1139 In this case, the "TO_JSON" method of the object is invoked in
1140 scalar context. It must return a single scalar that can be directly
1141 encoded into JSON. This scalar replaces the object in the JSON
1142 text.
1143 For example, the following "TO_JSON" method will convert all URI
1145 objects to JSON strings when serialised. The fact that these values
1146 originally were URI objects is lost.
1147 sub URI::TO_JSON {
1149 my ($uri) = @_;
1150 $uri->as_string
1151 }
1152 3. "allow_bignum" is enabled and the object is a "Math::BigInt" or
1154 "Math::BigFloat".
1155 The object will be serialised as a JSON number value.
1156 4. "allow_blessed" is enabled.
1158 The object will be serialised as a JSON null value.
1159 5. none of the above
1161 If none of the settings are enabled or the respective methods are
1162 missing, "JSON::PP" throws an exception.
1163 DESERIALISATION
1165 For deserialisation there are only two cases to consider: either
1167 nonstandard tagging was used, in which case "allow_tags" decides, or
1168 objects cannot be automatically be deserialised, in which case you can
1169 use postprocessing or the "filter_json_object" or
1170 "filter_json_single_key_object" callbacks to get some real objects our
1171 of your JSON.
1172 This section only considers the tagged value case: a tagged JSON object
1174 is encountered during decoding and "allow_tags" is disabled, a parse
1175 error will result (as if tagged values were not part of the grammar).
1176 If "allow_tags" is enabled, "JSON::PP" will look up the "THAW" method
1178 of the package/classname used during serialisation (it will not attempt
1179 to load the package as a Perl module). If there is no such method, the
1180 decoding will fail with an error.
1181 Otherwise, the "THAW" method is invoked with the classname as first
1183 argument, the constant string "JSON" as second argument, and all the
1184 values from the JSON array (the values originally returned by the
1185 "FREEZE" method) as remaining arguments.
1186 The method must then return the object. While technically you can
1188 return any Perl scalar, you might have to enable the "allow_nonref"
1189 setting to make that work in all cases, so better return an actual
1190 blessed reference.
1191 As an example, let's implement a "THAW" function that regenerates the
1193 "My::Object" from the "FREEZE" example earlier:
1194 sub My::Object::THAW {
1196 my ($class, $serialiser, $type, $id) = @_;
1197 $class->new (type => $type, id => $id)
1199 }
1200
1202 This section is taken from JSON::XS.
1203 The interested reader might have seen a number of flags that signify
1205 encodings or codesets - "utf8", "latin1" and "ascii". There seems to be
1206 some confusion on what these do, so here is a short comparison:
1207 "utf8" controls whether the JSON text created by "encode" (and expected
1209 by "decode") is UTF-8 encoded or not, while "latin1" and "ascii" only
1210 control whether "encode" escapes character values outside their
1211 respective codeset range. Neither of these flags conflict with each
1212 other, although some combinations make less sense than others.
1213 Care has been taken to make all flags symmetrical with respect to
1215 "encode" and "decode", that is, texts encoded with any combination of
1216 these flag values will be correctly decoded when the same flags are
1217 used - in general, if you use different flag settings while encoding
1218 vs. when decoding you likely have a bug somewhere.
1219 Below comes a verbose discussion of these flags. Note that a "codeset"
1221 is simply an abstract set of character-codepoint pairs, while an
1222 encoding takes those codepoint numbers and encodes them, in our case
1223 into octets. Unicode is (among other things) a codeset, UTF-8 is an
1224 encoding, and ISO-8859-1 (= latin 1) and ASCII are both codesets and
1225 encodings at the same time, which can be confusing.
1226 "utf8" flag disabled
1228 When "utf8" is disabled (the default), then "encode"/"decode"
1229 generate and expect Unicode strings, that is, characters with high
1230 ordinal Unicode values (> 255) will be encoded as such characters,
1231 and likewise such characters are decoded as-is, no changes to them
1232 will be done, except "(re-)interpreting" them as Unicode codepoints
1233 or Unicode characters, respectively (to Perl, these are the same
1234 thing in strings unless you do funny/weird/dumb stuff).
1235 This is useful when you want to do the encoding yourself (e.g. when
1237 you want to have UTF-16 encoded JSON texts) or when some other
1238 layer does the encoding for you (for example, when printing to a
1239 terminal using a filehandle that transparently encodes to UTF-8 you
1240 certainly do NOT want to UTF-8 encode your data first and have Perl
1241 encode it another time).
1242 "utf8" flag enabled
1244 If the "utf8"-flag is enabled, "encode"/"decode" will encode all
1245 characters using the corresponding UTF-8 multi-byte sequence, and
1246 will expect your input strings to be encoded as UTF-8, that is, no
1247 "character" of the input string must have any value > 255, as UTF-8
1248 does not allow that.
1249 The "utf8" flag therefore switches between two modes: disabled
1251 means you will get a Unicode string in Perl, enabled means you get
1252 an UTF-8 encoded octet/binary string in Perl.
1253 "latin1" or "ascii" flags enabled
1255 With "latin1" (or "ascii") enabled, "encode" will escape characters
1256 with ordinal values > 255 (> 127 with "ascii") and encode the
1257 remaining characters as specified by the "utf8" flag.
1258 If "utf8" is disabled, then the result is also correctly encoded in
1260 those character sets (as both are proper subsets of Unicode,
1261 meaning that a Unicode string with all character values < 256 is
1262 the same thing as a ISO-8859-1 string, and a Unicode string with
1263 all character values < 128 is the same thing as an ASCII string in
1264 Perl).
1265 If "utf8" is enabled, you still get a correct UTF-8-encoded string,
1267 regardless of these flags, just some more characters will be
1268 escaped using "\uXXXX" then before.
1269 Note that ISO-8859-1-encoded strings are not compatible with UTF-8
1271 encoding, while ASCII-encoded strings are. That is because the
1272 ISO-8859-1 encoding is NOT a subset of UTF-8 (despite the
1273 ISO-8859-1 codeset being a subset of Unicode), while ASCII is.
1274 Surprisingly, "decode" will ignore these flags and so treat all
1276 input values as governed by the "utf8" flag. If it is disabled,
1277 this allows you to decode ISO-8859-1- and ASCII-encoded strings, as
1278 both strict subsets of Unicode. If it is enabled, you can correctly
1279 decode UTF-8 encoded strings.
1280 So neither "latin1" nor "ascii" are incompatible with the "utf8"
1282 flag - they only govern when the JSON output engine escapes a
1283 character or not.
1284 The main use for "latin1" is to relatively efficiently store binary
1286 data as JSON, at the expense of breaking compatibility with most
1287 JSON decoders.
1288 The main use for "ascii" is to force the output to not contain
1290 characters with values > 127, which means you can interpret the
1291 resulting string as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about
1292 any character set and 8-bit-encoding, and still get the same data
1293 structure back. This is useful when your channel for JSON transfer
1294 is not 8-bit clean or the encoding might be mangled in between
1295 (e.g. in mail), and works because ASCII is a proper subset of most
1296 8-bit and multibyte encodings in use in the world.
1297
1299 Please report bugs on a specific behavior of this module to RT or
1300 GitHub issues (preferred):
1301 <https://github.com/makamaka/JSON-PP/issues>
1303 <https://rt.cpan.org/Public/Dist/Display.html?Queue=JSON-PP>
1305 As for new features and requests to change common behaviors, please ask
1307 the author of JSON::XS (Marc Lehmann, <schmorp[at]schmorp.de>) first,
1308 by email (important!), to keep compatibility among JSON.pm backends.
1309 Generally speaking, if you need something special for you, you are
1311 advised to create a new module, maybe based on JSON::Tiny, which is
1312 smaller and written in a much cleaner way than this module.
1313
1315 The json_pp command line utility for quick experiments.
1316 JSON::XS, Cpanel::JSON::XS, and JSON::Tiny for faster alternatives.
1318 JSON and JSON::MaybeXS for easy migration.
1319 JSON::backportPP::Compat5005 and JSON::backportPP::Compat5006 for older
1321 perl users.
1322 RFC4627 (<http://www.ietf.org/rfc/rfc4627.txt>)
1324 RFC7159 (<http://www.ietf.org/rfc/rfc7159.txt>)
1326 RFC8259 (<http://www.ietf.org/rfc/rfc8259.txt>)
1328
1330 Makamaka Hannyaharamitu, <makamaka[at]cpan.org>
1331
1333 Kenichi Ishigaki, <ishigaki[at]cpan.org>
1334
1336 Copyright 2007-2016 by Makamaka Hannyaharamitu
1337 Most of the documentation is taken from JSON::XS by Marc Lehmann
1339 This library is free software; you can redistribute it and/or modify it
1341 under the same terms as Perl itself.
1342perl v5.36.0 2022-08-01 JSON::backportPP(3)