1JSON::PP(3) User Contributed Perl Documentation JSON::PP(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 See MAPPING, below, for more information on how JSON values are mapped
84 to Perl.
85
87 This section is also taken from JSON::XS.
88 The object oriented interface lets you configure your own encoding or
90 decoding style, within the limits of supported formats.
91 new
93 $json = JSON::PP->new
94 Creates a new JSON::PP object that can be used to de/encode JSON
96 strings. All boolean flags described below are by default disabled
97 (with the exception of "allow_nonref", which defaults to enabled since
98 version 4.0).
99 The mutators for flags all return the JSON::PP object again and thus
101 calls can be chained:
102 my $json = JSON::PP->new->utf8->space_after->encode({a => [1,2]})
104 => {"a": [1, 2]}
105 ascii
107 $json = $json->ascii([$enable])
108 $enabled = $json->get_ascii
110 If $enable is true (or missing), then the "encode" method will not
112 generate characters outside the code range 0..127 (which is ASCII). Any
113 Unicode characters outside that range will be escaped using either a
114 single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape
115 sequence, as per RFC4627. The resulting encoded JSON text can be
116 treated as a native Unicode string, an ascii-encoded, latin1-encoded or
117 UTF-8 encoded string, or any other superset of ASCII.
118 If $enable is false, then the "encode" method will not escape Unicode
120 characters unless required by the JSON syntax or other flags. This
121 results in a faster and more compact format.
122 See also the section ENCODING/CODESET FLAG NOTES later in this
124 document.
125 The main use for this flag is to produce JSON texts that can be
127 transmitted over a 7-bit channel, as the encoded JSON texts will not
128 contain any 8 bit characters.
129 JSON::PP->new->ascii(1)->encode([chr 0x10401])
131 => ["\ud801\udc01"]
132 latin1
134 $json = $json->latin1([$enable])
135 $enabled = $json->get_latin1
137 If $enable is true (or missing), then the "encode" method will encode
139 the resulting JSON text as latin1 (or iso-8859-1), escaping any
140 characters outside the code range 0..255. The resulting string can be
141 treated as a latin1-encoded JSON text or a native Unicode string. The
142 "decode" method will not be affected in any way by this flag, as
143 "decode" by default expects Unicode, which is a strict superset of
144 latin1.
145 If $enable is false, then the "encode" method will not escape Unicode
147 characters unless required by the JSON syntax or other flags.
148 See also the section ENCODING/CODESET FLAG NOTES later in this
150 document.
151 The main use for this flag is efficiently encoding binary data as JSON
153 text, as most octets will not be escaped, resulting in a smaller
154 encoded size. The disadvantage is that the resulting JSON text is
155 encoded in latin1 (and must correctly be treated as such when storing
156 and transferring), a rare encoding for JSON. It is therefore most
157 useful when you want to store data structures known to contain binary
158 data efficiently in files or databases, not when talking to other JSON
159 encoders/decoders.
160 JSON::PP->new->latin1->encode (["\x{89}\x{abc}"]
162 => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not)
163 utf8
165 $json = $json->utf8([$enable])
166 $enabled = $json->get_utf8
168 If $enable is true (or missing), then the "encode" method will encode
170 the JSON result into UTF-8, as required by many protocols, while the
171 "decode" method expects to be handled an UTF-8-encoded string. Please
172 note that UTF-8-encoded strings do not contain any characters outside
173 the range 0..255, they are thus useful for bytewise/binary I/O. In
174 future versions, enabling this option might enable autodetection of the
175 UTF-16 and UTF-32 encoding families, as described in RFC4627.
176 If $enable is false, then the "encode" method will return the JSON
178 string as a (non-encoded) Unicode string, while "decode" expects thus a
179 Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16)
180 needs to be done yourself, e.g. using the Encode module.
181 See also the section ENCODING/CODESET FLAG NOTES later in this
183 document.
184 Example, output UTF-16BE-encoded JSON:
186 use Encode;
188 $jsontext = encode "UTF-16BE", JSON::PP->new->encode ($object);
189 Example, decode UTF-32LE-encoded JSON:
191 use Encode;
193 $object = JSON::PP->new->decode (decode "UTF-32LE", $jsontext);
194 pretty
196 $json = $json->pretty([$enable])
197 This enables (or disables) all of the "indent", "space_before" and
199 "space_after" (and in the future possibly more) flags in one call to
200 generate the most readable (or most compact) form possible.
201 indent
203 $json = $json->indent([$enable])
204 $enabled = $json->get_indent
206 If $enable is true (or missing), then the "encode" method will use a
208 multiline format as output, putting every array member or object/hash
209 key-value pair into its own line, indenting them properly.
210 If $enable is false, no newlines or indenting will be produced, and the
212 resulting JSON text is guaranteed not to contain any "newlines".
213 This setting has no effect when decoding JSON texts.
215 The default indent space length is three. You can use "indent_length"
217 to change the length.
218 space_before
220 $json = $json->space_before([$enable])
221 $enabled = $json->get_space_before
223 If $enable is true (or missing), then the "encode" method will add an
225 extra optional space before the ":" separating keys from values in JSON
226 objects.
227 If $enable is false, then the "encode" method will not add any extra
229 space at those places.
230 This setting has no effect when decoding JSON texts. You will also most
232 likely combine this setting with "space_after".
233 Example, space_before enabled, space_after and indent disabled:
235 {"key" :"value"}
237 space_after
239 $json = $json->space_after([$enable])
240 $enabled = $json->get_space_after
242 If $enable is true (or missing), then the "encode" method will add an
244 extra optional space after the ":" separating keys from values in JSON
245 objects and extra whitespace after the "," separating key-value pairs
246 and array members.
247 If $enable is false, then the "encode" method will not add any extra
249 space at those places.
250 This setting has no effect when decoding JSON texts.
252 Example, space_before and indent disabled, space_after enabled:
254 {"key": "value"}
256 relaxed
258 $json = $json->relaxed([$enable])
259 $enabled = $json->get_relaxed
261 If $enable is true (or missing), then "decode" will accept some
263 extensions to normal JSON syntax (see below). "encode" will not be
264 affected in anyway. Be aware that this option makes you accept invalid
265 JSON texts as if they were valid!. I suggest only to use this option to
266 parse application-specific files written by humans (configuration
267 files, resource files etc.)
268 If $enable is false (the default), then "decode" will only accept valid
270 JSON texts.
271 Currently accepted extensions are:
273 • list items can have an end-comma
275 JSON separates array elements and key-value pairs with commas. This
277 can be annoying if you write JSON texts manually and want to be
278 able to quickly append elements, so this extension accepts comma at
279 the end of such items not just between them:
280 [
282 1,
283 2, <- this comma not normally allowed
284 ]
285 {
286 "k1": "v1",
287 "k2": "v2", <- this comma not normally allowed
288 }
289 • shell-style '#'-comments
291 Whenever JSON allows whitespace, shell-style comments are
293 additionally allowed. They are terminated by the first carriage-
294 return or line-feed character, after which more white-space and
295 comments are allowed.
296 [
298 1, # this comment not allowed in JSON
299 # neither this one...
300 ]
301 • C-style multiple-line '/* */'-comments (JSON::PP only)
303 Whenever JSON allows whitespace, C-style multiple-line comments are
305 additionally allowed. Everything between "/*" and "*/" is a
306 comment, after which more white-space and comments are allowed.
307 [
309 1, /* this comment not allowed in JSON */
310 /* neither this one... */
311 ]
312 • C++-style one-line '//'-comments (JSON::PP only)
314 Whenever JSON allows whitespace, C++-style one-line comments are
316 additionally allowed. They are terminated by the first carriage-
317 return or line-feed character, after which more white-space and
318 comments are allowed.
319 [
321 1, // this comment not allowed in JSON
322 // neither this one...
323 ]
324 • literal ASCII TAB characters in strings
326 Literal ASCII TAB characters are now allowed in strings (and
328 treated as "\t").
329 [
331 "Hello\tWorld",
332 "Hello<TAB>World", # literal <TAB> would not normally be allowed
333 ]
334 canonical
336 $json = $json->canonical([$enable])
337 $enabled = $json->get_canonical
339 If $enable is true (or missing), then the "encode" method will output
341 JSON objects by sorting their keys. This is adding a comparatively high
342 overhead.
343 If $enable is false, then the "encode" method will output key-value
345 pairs in the order Perl stores them (which will likely change between
346 runs of the same script, and can change even within the same run from
347 5.18 onwards).
348 This option is useful if you want the same data structure to be encoded
350 as the same JSON text (given the same overall settings). If it is
351 disabled, the same hash might be encoded differently even if contains
352 the same data, as key-value pairs have no inherent ordering in Perl.
353 This setting has no effect when decoding JSON texts.
355 This setting has currently no effect on tied hashes.
357 allow_nonref
359 $json = $json->allow_nonref([$enable])
360 $enabled = $json->get_allow_nonref
362 Unlike other boolean options, this opotion is enabled by default
364 beginning with version 4.0.
365 If $enable is true (or missing), then the "encode" method can convert a
367 non-reference into its corresponding string, number or null JSON value,
368 which is an extension to RFC4627. Likewise, "decode" will accept those
369 JSON values instead of croaking.
370 If $enable is false, then the "encode" method will croak if it isn't
372 passed an arrayref or hashref, as JSON texts must either be an object
373 or array. Likewise, "decode" will croak if given something that is not
374 a JSON object or array.
375 Example, encode a Perl scalar as JSON value without enabled
377 "allow_nonref", resulting in an error:
378 JSON::PP->new->allow_nonref(0)->encode ("Hello, World!")
380 => hash- or arrayref expected...
381 allow_unknown
383 $json = $json->allow_unknown([$enable])
384 $enabled = $json->get_allow_unknown
386 If $enable is true (or missing), then "encode" will not throw an
388 exception when it encounters values it cannot represent in JSON (for
389 example, filehandles) but instead will encode a JSON "null" value. Note
390 that blessed objects are not included here and are handled separately
391 by c<allow_blessed>.
392 If $enable is false (the default), then "encode" will throw an
394 exception when it encounters anything it cannot encode as JSON.
395 This option does not affect "decode" in any way, and it is recommended
397 to leave it off unless you know your communications partner.
398 allow_blessed
400 $json = $json->allow_blessed([$enable])
401 $enabled = $json->get_allow_blessed
403 See "OBJECT SERIALISATION" for details.
405 If $enable is true (or missing), then the "encode" method will not barf
407 when it encounters a blessed reference that it cannot convert
408 otherwise. Instead, a JSON "null" value is encoded instead of the
409 object.
410 If $enable is false (the default), then "encode" will throw an
412 exception when it encounters a blessed object that it cannot convert
413 otherwise.
414 This setting has no effect on "decode".
416 convert_blessed
418 $json = $json->convert_blessed([$enable])
419 $enabled = $json->get_convert_blessed
421 See "OBJECT SERIALISATION" for details.
423 If $enable is true (or missing), then "encode", upon encountering a
425 blessed object, will check for the availability of the "TO_JSON" method
426 on the object's class. If found, it will be called in scalar context
427 and the resulting scalar will be encoded instead of the object.
428 The "TO_JSON" method may safely call die if it wants. If "TO_JSON"
430 returns other blessed objects, those will be handled in the same way.
431 "TO_JSON" must take care of not causing an endless recursion cycle (==
432 crash) in this case. The name of "TO_JSON" was chosen because other
433 methods called by the Perl core (== not by the user of the object) are
434 usually in upper case letters and to avoid collisions with any
435 "to_json" function or method.
436 If $enable is false (the default), then "encode" will not consider this
438 type of conversion.
439 This setting has no effect on "decode".
441 allow_tags
443 $json = $json->allow_tags([$enable])
444 $enabled = $json->get_allow_tags
446 See "OBJECT SERIALISATION" for details.
448 If $enable is true (or missing), then "encode", upon encountering a
450 blessed object, will check for the availability of the "FREEZE" method
451 on the object's class. If found, it will be used to serialise the
452 object into a nonstandard tagged JSON value (that JSON decoders cannot
453 decode).
454 It also causes "decode" to parse such tagged JSON values and
456 deserialise them via a call to the "THAW" method.
457 If $enable is false (the default), then "encode" will not consider this
459 type of conversion, and tagged JSON values will cause a parse error in
460 "decode", as if tags were not part of the grammar.
461 boolean_values
463 $json->boolean_values([$false, $true])
464 ($false, $true) = $json->get_boolean_values
466 By default, JSON booleans will be decoded as overloaded
468 $JSON::PP::false and $JSON::PP::true objects.
469 With this method you can specify your own boolean values for decoding -
471 on decode, JSON "false" will be decoded as a copy of $false, and JSON
472 "true" will be decoded as $true ("copy" here is the same thing as
473 assigning a value to another variable, i.e. "$copy = $false").
474 This is useful when you want to pass a decoded data structure directly
476 to other serialisers like YAML, Data::MessagePack and so on.
477 Note that this works only when you "decode". You can set incompatible
479 boolean objects (like boolean), but when you "encode" a data structure
480 with such boolean objects, you still need to enable "convert_blessed"
481 (and add a "TO_JSON" method if necessary).
482 Calling this method without any arguments will reset the booleans to
484 their default values.
485 "get_boolean_values" will return both $false and $true values, or the
487 empty list when they are set to the default.
488 filter_json_object
490 $json = $json->filter_json_object([$coderef])
491 When $coderef is specified, it will be called from "decode" each time
493 it decodes a JSON object. The only argument is a reference to the
494 newly-created hash. If the code references returns a single scalar
495 (which need not be a reference), this value (or rather a copy of it) is
496 inserted into the deserialised data structure. If it returns an empty
497 list (NOTE: not "undef", which is a valid scalar), the original
498 deserialised hash will be inserted. This setting can slow down decoding
499 considerably.
500 When $coderef is omitted or undefined, any existing callback will be
502 removed and "decode" will not change the deserialised hash in any way.
503 Example, convert all JSON objects into the integer 5:
505 my $js = JSON::PP->new->filter_json_object(sub { 5 });
507 # returns [5]
508 $js->decode('[{}]');
509 # returns 5
510 $js->decode('{"a":1, "b":2}');
511 filter_json_single_key_object
513 $json = $json->filter_json_single_key_object($key [=> $coderef])
514 Works remotely similar to "filter_json_object", but is only called for
516 JSON objects having a single key named $key.
517 This $coderef is called before the one specified via
519 "filter_json_object", if any. It gets passed the single value in the
520 JSON object. If it returns a single value, it will be inserted into the
521 data structure. If it returns nothing (not even "undef" but the empty
522 list), the callback from "filter_json_object" will be called next, as
523 if no single-key callback were specified.
524 If $coderef is omitted or undefined, the corresponding callback will be
526 disabled. There can only ever be one callback for a given key.
527 As this callback gets called less often then the "filter_json_object"
529 one, decoding speed will not usually suffer as much. Therefore, single-
530 key objects make excellent targets to serialise Perl objects into,
531 especially as single-key JSON objects are as close to the type-tagged
532 value concept as JSON gets (it's basically an ID/VALUE tuple). Of
533 course, JSON does not support this in any way, so you need to make sure
534 your data never looks like a serialised Perl hash.
535 Typical names for the single object key are "__class_whatever__", or
537 "$__dollars_are_rarely_used__$" or "}ugly_brace_placement", or even
538 things like "__class_md5sum(classname)__", to reduce the risk of
539 clashing with real hashes.
540 Example, decode JSON objects of the form "{ "__widget__" => <id> }"
542 into the corresponding $WIDGET{<id>} object:
543 # return whatever is in $WIDGET{5}:
545 JSON::PP
546 ->new
547 ->filter_json_single_key_object (__widget__ => sub {
548 $WIDGET{ $_[0] }
549 })
550 ->decode ('{"__widget__": 5')
551 # this can be used with a TO_JSON method in some "widget" class
553 # for serialisation to json:
554 sub WidgetBase::TO_JSON {
555 my ($self) = @_;
556 unless ($self->{id}) {
558 $self->{id} = ..get..some..id..;
559 $WIDGET{$self->{id}} = $self;
560 }
561 { __widget__ => $self->{id} }
563 }
564 shrink
566 $json = $json->shrink([$enable])
567 $enabled = $json->get_shrink
569 If $enable is true (or missing), the string returned by "encode" will
571 be shrunk (i.e. downgraded if possible).
572 The actual definition of what shrink does might change in future
574 versions, but it will always try to save space at the expense of time.
575 If $enable is false, then JSON::PP does nothing.
577 max_depth
579 $json = $json->max_depth([$maximum_nesting_depth])
580 $max_depth = $json->get_max_depth
582 Sets the maximum nesting level (default 512) accepted while encoding or
584 decoding. If a higher nesting level is detected in JSON text or a Perl
585 data structure, then the encoder and decoder will stop and croak at
586 that point.
587 Nesting level is defined by number of hash- or arrayrefs that the
589 encoder needs to traverse to reach a given point or the number of "{"
590 or "[" characters without their matching closing parenthesis crossed to
591 reach a given character in a string.
592 Setting the maximum depth to one disallows any nesting, so that ensures
594 that the object is only a single hash/object or array.
595 If no argument is given, the highest possible setting will be used,
597 which is rarely useful.
598 See "SECURITY CONSIDERATIONS" in JSON::XS for more info on why this is
600 useful.
601 max_size
603 $json = $json->max_size([$maximum_string_size])
604 $max_size = $json->get_max_size
606 Set the maximum length a JSON text may have (in bytes) where decoding
608 is being attempted. The default is 0, meaning no limit. When "decode"
609 is called on a string that is longer then this many bytes, it will not
610 attempt to decode the string but throw an exception. This setting has
611 no effect on "encode" (yet).
612 If no argument is given, the limit check will be deactivated (same as
614 when 0 is specified).
615 See "SECURITY CONSIDERATIONS" in JSON::XS for more info on why this is
617 useful.
618 encode
620 $json_text = $json->encode($perl_scalar)
621 Converts the given Perl value or data structure to its JSON
623 representation. Croaks on error.
624 decode
626 $perl_scalar = $json->decode($json_text)
627 The opposite of "encode": expects a JSON text and tries to parse it,
629 returning the resulting simple scalar or reference. Croaks on error.
630 decode_prefix
632 ($perl_scalar, $characters) = $json->decode_prefix($json_text)
633 This works like the "decode" method, but instead of raising an
635 exception when there is trailing garbage after the first JSON object,
636 it will silently stop parsing there and return the number of characters
637 consumed so far.
638 This is useful if your JSON texts are not delimited by an outer
640 protocol and you need to know where the JSON text ends.
641 JSON::PP->new->decode_prefix ("[1] the tail")
643 => ([1], 3)
644
646 The following flags and properties are for JSON::PP only. If you use
647 any of these, you can't make your application run faster by replacing
648 JSON::PP with JSON::XS. If you need these and also speed boost, you
649 might want to try Cpanel::JSON::XS, a fork of JSON::XS by Reini Urban,
650 which supports some of these (with a different set of
651 incompatibilities). Most of these historical flags are only kept for
652 backward compatibility, and should not be used in a new application.
653 allow_singlequote
655 $json = $json->allow_singlequote([$enable])
656 $enabled = $json->get_allow_singlequote
657 If $enable is true (or missing), then "decode" will accept invalid JSON
659 texts that contain strings that begin and end with single quotation
660 marks. "encode" will not be affected in any way. Be aware that this
661 option makes you accept invalid JSON texts as if they were valid!. I
662 suggest only to use this option to parse application-specific files
663 written by humans (configuration files, resource files etc.)
664 If $enable is false (the default), then "decode" will only accept valid
666 JSON texts.
667 $json->allow_singlequote->decode(qq|{"foo":'bar'}|);
669 $json->allow_singlequote->decode(qq|{'foo':"bar"}|);
670 $json->allow_singlequote->decode(qq|{'foo':'bar'}|);
671 allow_barekey
673 $json = $json->allow_barekey([$enable])
674 $enabled = $json->get_allow_barekey
675 If $enable is true (or missing), then "decode" will accept invalid JSON
677 texts that contain JSON objects whose names don't begin and end with
678 quotation marks. "encode" will not be affected in any way. Be aware
679 that this option makes you accept invalid JSON texts as if they were
680 valid!. I suggest only to use this option to parse application-specific
681 files 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_barekey->decode(qq|{foo:"bar"}|);
687 allow_bignum
689 $json = $json->allow_bignum([$enable])
690 $enabled = $json->get_allow_bignum
691 If $enable is true (or missing), then "decode" will convert big
693 integers Perl cannot handle as integer into Math::BigInt objects and
694 convert floating numbers into Math::BigFloat objects. "encode" will
695 convert "Math::BigInt" and "Math::BigFloat" objects into JSON numbers.
696 $json->allow_nonref->allow_bignum;
698 $bigfloat = $json->decode('2.000000000000000000000000001');
699 print $json->encode($bigfloat);
700 # => 2.000000000000000000000000001
701 See also MAPPING.
703 loose
705 $json = $json->loose([$enable])
706 $enabled = $json->get_loose
707 If $enable is true (or missing), then "decode" will accept invalid JSON
709 texts that contain unescaped [\x00-\x1f\x22\x5c] characters. "encode"
710 will not be affected in any way. Be aware that this option makes you
711 accept invalid JSON texts as if they were valid!. I suggest only to use
712 this option to parse application-specific files written by humans
713 (configuration files, resource files etc.)
714 If $enable is false (the default), then "decode" will only accept valid
716 JSON texts.
717 $json->loose->decode(qq|["abc
719 def"]|);
720 escape_slash
722 $json = $json->escape_slash([$enable])
723 $enabled = $json->get_escape_slash
724 If $enable is true (or missing), then "encode" will explicitly escape
726 slash (solidus; "U+002F") characters to reduce the risk of XSS (cross
727 site scripting) that may be caused by "</script>" in a JSON text, with
728 the cost of bloating the size of JSON texts.
729 This option may be useful when you embed JSON in HTML, but embedding
731 arbitrary JSON in HTML (by some HTML template toolkit or by string
732 interpolation) is risky in general. You must escape necessary
733 characters in correct order, depending on the context.
734 "decode" will not be affected in any way.
736 indent_length
738 $json = $json->indent_length($number_of_spaces)
739 $length = $json->get_indent_length
740 This option is only useful when you also enable "indent" or "pretty".
742 JSON::XS indents with three spaces when you "encode" (if requested by
744 "indent" or "pretty"), and the number cannot be changed. JSON::PP
745 allows you to change/get the number of indent spaces with these
746 mutator/accessor. The default number of spaces is three (the same as
747 JSON::XS), and the acceptable range is from 0 (no indentation; it'd be
748 better to disable indentation by indent(0)) to 15.
749 sort_by
751 $json = $json->sort_by($code_ref)
752 $json = $json->sort_by($subroutine_name)
753 If you just want to sort keys (names) in JSON objects when you
755 "encode", enable "canonical" option (see above) that allows you to sort
756 object keys alphabetically.
757 If you do need to sort non-alphabetically for whatever reasons, you can
759 give a code reference (or a subroutine name) to "sort_by", then the
760 argument will be passed to Perl's "sort" built-in function.
761 As the sorting is done in the JSON::PP scope, you usually need to
763 prepend "JSON::PP::" to the subroutine name, and the special variables
764 $a and $b used in the subrontine used by "sort" function.
765 Example:
767 my %ORDER = (id => 1, class => 2, name => 3);
769 $json->sort_by(sub {
770 ($ORDER{$JSON::PP::a} // 999) <=> ($ORDER{$JSON::PP::b} // 999)
771 or $JSON::PP::a cmp $JSON::PP::b
772 });
773 print $json->encode([
774 {name => 'CPAN', id => 1, href => 'http://cpan.org'}
775 ]);
776 # [{"id":1,"name":"CPAN","href":"http://cpan.org"}]
777 Note that "sort_by" affects all the plain hashes in the data structure.
779 If you need finer control, "tie" necessary hashes with a module that
780 implements ordered hash (such as Hash::Ordered and Tie::IxHash).
781 "canonical" and "sort_by" don't affect the key order in "tie"d hashes.
782 use Hash::Ordered;
784 tie my %hash, 'Hash::Ordered',
785 (name => 'CPAN', id => 1, href => 'http://cpan.org');
786 print $json->encode([\%hash]);
787 # [{"name":"CPAN","id":1,"href":"http://cpan.org"}] # order is kept
788
790 This section is also taken from JSON::XS.
791 In some cases, there is the need for incremental parsing of JSON texts.
793 While this module always has to keep both JSON text and resulting Perl
794 data structure in memory at one time, it does allow you to parse a JSON
795 stream incrementally. It does so by accumulating text until it has a
796 full JSON object, which it then can decode. This process is similar to
797 using "decode_prefix" to see if a full JSON object is available, but is
798 much more efficient (and can be implemented with a minimum of method
799 calls).
800 JSON::PP will only attempt to parse the JSON text once it is sure it
802 has enough text to get a decisive result, using a very simple but truly
803 incremental parser. This means that it sometimes won't stop as early as
804 the full parser, for example, it doesn't detect mismatched parentheses.
805 The only thing it guarantees is that it starts decoding as soon as a
806 syntactically valid JSON text has been seen. This means you need to set
807 resource limits (e.g. "max_size") to ensure the parser will stop
808 parsing in the presence if syntax errors.
809 The following methods implement this incremental parser.
811 incr_parse
813 $json->incr_parse( [$string] ) # void context
814 $obj_or_undef = $json->incr_parse( [$string] ) # scalar context
816 @obj_or_empty = $json->incr_parse( [$string] ) # list context
818 This is the central parsing function. It can both append new text and
820 extract objects from the stream accumulated so far (both of these
821 functions are optional).
822 If $string is given, then this string is appended to the already
824 existing JSON fragment stored in the $json object.
825 After that, if the function is called in void context, it will simply
827 return without doing anything further. This can be used to add more
828 text in as many chunks as you want.
829 If the method is called in scalar context, then it will try to extract
831 exactly one JSON object. If that is successful, it will return this
832 object, otherwise it will return "undef". If there is a parse error,
833 this method will croak just as "decode" would do (one can then use
834 "incr_skip" to skip the erroneous part). This is the most common way of
835 using the method.
836 And finally, in list context, it will try to extract as many objects
838 from the stream as it can find and return them, or the empty list
839 otherwise. For this to work, there must be no separators (other than
840 whitespace) between the JSON objects or arrays, instead they must be
841 concatenated back-to-back. If an error occurs, an exception will be
842 raised as in the scalar context case. Note that in this case, any
843 previously-parsed JSON texts will be lost.
844 Example: Parse some JSON arrays/objects in a given string and return
846 them.
847 my @objs = JSON::PP->new->incr_parse ("[5][7][1,2]");
849 incr_text
851 $lvalue_string = $json->incr_text
852 This method returns the currently stored JSON fragment as an lvalue,
854 that is, you can manipulate it. This only works when a preceding call
855 to "incr_parse" in scalar context successfully returned an object.
856 Under all other circumstances you must not call this function (I mean
857 it. although in simple tests it might actually work, it will fail
858 under real world conditions). As a special exception, you can also call
859 this method before having parsed anything.
860 That means you can only use this function to look at or manipulate text
862 before or after complete JSON objects, not while the parser is in the
863 middle of parsing a JSON object.
864 This function is useful in two cases: a) finding the trailing text
866 after a JSON object or b) parsing multiple JSON objects separated by
867 non-JSON text (such as commas).
868 incr_skip
870 $json->incr_skip
871 This will reset the state of the incremental parser and will remove the
873 parsed text from the input buffer so far. This is useful after
874 "incr_parse" died, in which case the input buffer and incremental
875 parser state is left unchanged, to skip the text parsed so far and to
876 reset the parse state.
877 The difference to "incr_reset" is that only text until the parse error
879 occurred is removed.
880 incr_reset
882 $json->incr_reset
883 This completely resets the incremental parser, that is, after this
885 call, it will be as if the parser had never parsed anything.
886 This is useful if you want to repeatedly parse JSON objects and want to
888 ignore any trailing data, which means you have to reset the parser
889 after each successful decode.
890
892 Most of this section is also taken from JSON::XS.
893 This section describes how JSON::PP maps Perl values to JSON values and
895 vice versa. These mappings are designed to "do the right thing" in most
896 circumstances automatically, preserving round-tripping characteristics
897 (what you put in comes out as something equivalent).
898 For the more enlightened: note that in the following descriptions,
900 lowercase perl refers to the Perl interpreter, while uppercase Perl
901 refers to the abstract Perl language itself.
902 JSON -> PERL
904 object
905 A JSON object becomes a reference to a hash in Perl. No ordering of
906 object keys is preserved (JSON does not preserve object key
907 ordering itself).
908 array
910 A JSON array becomes a reference to an array in Perl.
911 string
913 A JSON string becomes a string scalar in Perl - Unicode codepoints
914 in JSON are represented by the same codepoints in the Perl string,
915 so no manual decoding is necessary.
916 number
918 A JSON number becomes either an integer, numeric (floating point)
919 or string scalar in perl, depending on its range and any fractional
920 parts. On the Perl level, there is no difference between those as
921 Perl handles all the conversion details, but an integer may take
922 slightly less memory and might represent more values exactly than
923 floating point numbers.
924 If the number consists of digits only, JSON::PP will try to
926 represent it as an integer value. If that fails, it will try to
927 represent it as a numeric (floating point) value if that is
928 possible without loss of precision. Otherwise it will preserve the
929 number as a string value (in which case you lose roundtripping
930 ability, as the JSON number will be re-encoded to a JSON string).
931 Numbers containing a fractional or exponential part will always be
933 represented as numeric (floating point) values, possibly at a loss
934 of precision (in which case you might lose perfect roundtripping
935 ability, but the JSON number will still be re-encoded as a JSON
936 number).
937 Note that precision is not accuracy - binary floating point values
939 cannot represent most decimal fractions exactly, and when
940 converting from and to floating point, JSON::PP only guarantees
941 precision up to but not including the least significant bit.
942 When "allow_bignum" is enabled, big integer values and any numeric
944 values will be converted into Math::BigInt and Math::BigFloat
945 objects respectively, without becoming string scalars or losing
946 precision.
947 true, false
949 These JSON atoms become "JSON::PP::true" and "JSON::PP::false",
950 respectively. They are overloaded to act almost exactly like the
951 numbers 1 and 0. You can check whether a scalar is a JSON boolean
952 by using the "JSON::PP::is_bool" function.
953 null
955 A JSON null atom becomes "undef" in Perl.
956 shell-style comments ("# text")
958 As a nonstandard extension to the JSON syntax that is enabled by
959 the "relaxed" setting, shell-style comments are allowed. They can
960 start anywhere outside strings and go till the end of the line.
961 tagged values ("(tag)value").
963 Another nonstandard extension to the JSON syntax, enabled with the
964 "allow_tags" setting, are tagged values. In this implementation,
965 the tag must be a perl package/class name encoded as a JSON string,
966 and the value must be a JSON array encoding optional constructor
967 arguments.
968 See "OBJECT SERIALISATION", below, for details.
970 PERL -> JSON
972 The mapping from Perl to JSON is slightly more difficult, as Perl is a
973 truly typeless language, so we can only guess which JSON type is meant
974 by a Perl value.
975 hash references
977 Perl hash references become JSON objects. As there is no inherent
978 ordering in hash keys (or JSON objects), they will usually be
979 encoded in a pseudo-random order. JSON::PP can optionally sort the
980 hash keys (determined by the canonical flag and/or sort_by
981 property), so the same data structure will serialise to the same
982 JSON text (given same settings and version of JSON::PP), but this
983 incurs a runtime overhead and is only rarely useful, e.g. when you
984 want to compare some JSON text against another for equality.
985 array references
987 Perl array references become JSON arrays.
988 other references
990 Other unblessed references are generally not allowed and will cause
991 an exception to be thrown, except for references to the integers 0
992 and 1, which get turned into "false" and "true" atoms in JSON. You
993 can also use "JSON::PP::false" and "JSON::PP::true" to improve
994 readability.
995 to_json [\0, JSON::PP::true] # yields [false,true]
997 JSON::PP::true, JSON::PP::false
999 These special values become JSON true and JSON false values,
1000 respectively. You can also use "\1" and "\0" directly if you want.
1001 JSON::PP::null
1003 This special value becomes JSON null.
1004 blessed objects
1006 Blessed objects are not directly representable in JSON, but
1007 "JSON::PP" allows various ways of handling objects. See "OBJECT
1008 SERIALISATION", below, for details.
1009 simple scalars
1011 Simple Perl scalars (any scalar that is not a reference) are the
1012 most difficult objects to encode: JSON::PP will encode undefined
1013 scalars as JSON "null" values, scalars that have last been used in
1014 a string context before encoding as JSON strings, and anything else
1015 as number value:
1016 # dump as number
1018 encode_json [2] # yields [2]
1019 encode_json [-3.0e17] # yields [-3e+17]
1020 my $value = 5; encode_json [$value] # yields [5]
1021 # used as string, so dump as string
1023 print $value;
1024 encode_json [$value] # yields ["5"]
1025 # undef becomes null
1027 encode_json [undef] # yields [null]
1028 You can force the type to be a JSON string by stringifying it:
1030 my $x = 3.1; # some variable containing a number
1032 "$x"; # stringified
1033 $x .= ""; # another, more awkward way to stringify
1034 print $x; # perl does it for you, too, quite often
1035 # (but for older perls)
1036 You can force the type to be a JSON number by numifying it:
1038 my $x = "3"; # some variable containing a string
1040 $x += 0; # numify it, ensuring it will be dumped as a number
1041 $x *= 1; # same thing, the choice is yours.
1042 You can not currently force the type in other, less obscure, ways.
1044 Since version 2.91_01, JSON::PP uses a different number detection
1046 logic that converts a scalar that is possible to turn into a number
1047 safely. The new logic is slightly faster, and tends to help people
1048 who use older perl or who want to encode complicated data
1049 structure. However, this may results in a different JSON text from
1050 the one JSON::XS encodes (and thus may break tests that compare
1051 entire JSON texts). If you do need the previous behavior for
1052 compatibility or for finer control, set PERL_JSON_PP_USE_B
1053 environmental variable to true before you "use" JSON::PP (or
1054 JSON.pm).
1055 Note that numerical precision has the same meaning as under Perl
1057 (so binary to decimal conversion follows the same rules as in Perl,
1058 which can differ to other languages). Also, your perl interpreter
1059 might expose extensions to the floating point numbers of your
1060 platform, such as infinities or NaN's - these cannot be represented
1061 in JSON, and it is an error to pass those in.
1062 JSON::PP (and JSON::XS) trusts what you pass to "encode" method (or
1064 "encode_json" function) is a clean, validated data structure with
1065 values that can be represented as valid JSON values only, because
1066 it's not from an external data source (as opposed to JSON texts you
1067 pass to "decode" or "decode_json", which JSON::PP considers tainted
1068 and doesn't trust). As JSON::PP doesn't know exactly what you and
1069 consumers of your JSON texts want the unexpected values to be (you
1070 may want to convert them into null, or to stringify them with or
1071 without normalisation (string representation of infinities/NaN may
1072 vary depending on platforms), or to croak without conversion),
1073 you're advised to do what you and your consumers need before you
1074 encode, and also not to numify values that may start with values
1075 that look like a number (including infinities/NaN), without
1076 validating.
1077 OBJECT SERIALISATION
1079 As JSON cannot directly represent Perl objects, you have to choose
1080 between a pure JSON representation (without the ability to deserialise
1081 the object automatically again), and a nonstandard extension to the
1082 JSON syntax, tagged values.
1083 SERIALISATION
1085 What happens when "JSON::PP" encounters a Perl object depends on the
1087 "allow_blessed", "convert_blessed", "allow_tags" and "allow_bignum"
1088 settings, which are used in this order:
1089 1. "allow_tags" is enabled and the object has a "FREEZE" method.
1091 In this case, "JSON::PP" creates a tagged JSON value, using a
1092 nonstandard extension to the JSON syntax.
1093 This works by invoking the "FREEZE" method on the object, with the
1095 first argument being the object to serialise, and the second
1096 argument being the constant string "JSON" to distinguish it from
1097 other serialisers.
1098 The "FREEZE" method can return any number of values (i.e. zero or
1100 more). These values and the paclkage/classname of the object will
1101 then be encoded as a tagged JSON value in the following format:
1102 ("classname")[FREEZE return values...]
1104 e.g.:
1106 ("URI")["http://www.google.com/"]
1108 ("MyDate")[2013,10,29]
1109 ("ImageData::JPEG")["Z3...VlCg=="]
1110 For example, the hypothetical "My::Object" "FREEZE" method might
1112 use the objects "type" and "id" members to encode the object:
1113 sub My::Object::FREEZE {
1115 my ($self, $serialiser) = @_;
1116 ($self->{type}, $self->{id})
1118 }
1119 2. "convert_blessed" is enabled and the object has a "TO_JSON" method.
1121 In this case, the "TO_JSON" method of the object is invoked in
1122 scalar context. It must return a single scalar that can be directly
1123 encoded into JSON. This scalar replaces the object in the JSON
1124 text.
1125 For example, the following "TO_JSON" method will convert all URI
1127 objects to JSON strings when serialised. The fact that these values
1128 originally were URI objects is lost.
1129 sub URI::TO_JSON {
1131 my ($uri) = @_;
1132 $uri->as_string
1133 }
1134 3. "allow_bignum" is enabled and the object is a "Math::BigInt" or
1136 "Math::BigFloat".
1137 The object will be serialised as a JSON number value.
1138 4. "allow_blessed" is enabled.
1140 The object will be serialised as a JSON null value.
1141 5. none of the above
1143 If none of the settings are enabled or the respective methods are
1144 missing, "JSON::PP" throws an exception.
1145 DESERIALISATION
1147 For deserialisation there are only two cases to consider: either
1149 nonstandard tagging was used, in which case "allow_tags" decides, or
1150 objects cannot be automatically be deserialised, in which case you can
1151 use postprocessing or the "filter_json_object" or
1152 "filter_json_single_key_object" callbacks to get some real objects our
1153 of your JSON.
1154 This section only considers the tagged value case: a tagged JSON object
1156 is encountered during decoding and "allow_tags" is disabled, a parse
1157 error will result (as if tagged values were not part of the grammar).
1158 If "allow_tags" is enabled, "JSON::PP" will look up the "THAW" method
1160 of the package/classname used during serialisation (it will not attempt
1161 to load the package as a Perl module). If there is no such method, the
1162 decoding will fail with an error.
1163 Otherwise, the "THAW" method is invoked with the classname as first
1165 argument, the constant string "JSON" as second argument, and all the
1166 values from the JSON array (the values originally returned by the
1167 "FREEZE" method) as remaining arguments.
1168 The method must then return the object. While technically you can
1170 return any Perl scalar, you might have to enable the "allow_nonref"
1171 setting to make that work in all cases, so better return an actual
1172 blessed reference.
1173 As an example, let's implement a "THAW" function that regenerates the
1175 "My::Object" from the "FREEZE" example earlier:
1176 sub My::Object::THAW {
1178 my ($class, $serialiser, $type, $id) = @_;
1179 $class->new (type => $type, id => $id)
1181 }
1182
1184 This section is taken from JSON::XS.
1185 The interested reader might have seen a number of flags that signify
1187 encodings or codesets - "utf8", "latin1" and "ascii". There seems to be
1188 some confusion on what these do, so here is a short comparison:
1189 "utf8" controls whether the JSON text created by "encode" (and expected
1191 by "decode") is UTF-8 encoded or not, while "latin1" and "ascii" only
1192 control whether "encode" escapes character values outside their
1193 respective codeset range. Neither of these flags conflict with each
1194 other, although some combinations make less sense than others.
1195 Care has been taken to make all flags symmetrical with respect to
1197 "encode" and "decode", that is, texts encoded with any combination of
1198 these flag values will be correctly decoded when the same flags are
1199 used - in general, if you use different flag settings while encoding
1200 vs. when decoding you likely have a bug somewhere.
1201 Below comes a verbose discussion of these flags. Note that a "codeset"
1203 is simply an abstract set of character-codepoint pairs, while an
1204 encoding takes those codepoint numbers and encodes them, in our case
1205 into octets. Unicode is (among other things) a codeset, UTF-8 is an
1206 encoding, and ISO-8859-1 (= latin 1) and ASCII are both codesets and
1207 encodings at the same time, which can be confusing.
1208 "utf8" flag disabled
1210 When "utf8" is disabled (the default), then "encode"/"decode"
1211 generate and expect Unicode strings, that is, characters with high
1212 ordinal Unicode values (> 255) will be encoded as such characters,
1213 and likewise such characters are decoded as-is, no changes to them
1214 will be done, except "(re-)interpreting" them as Unicode codepoints
1215 or Unicode characters, respectively (to Perl, these are the same
1216 thing in strings unless you do funny/weird/dumb stuff).
1217 This is useful when you want to do the encoding yourself (e.g. when
1219 you want to have UTF-16 encoded JSON texts) or when some other
1220 layer does the encoding for you (for example, when printing to a
1221 terminal using a filehandle that transparently encodes to UTF-8 you
1222 certainly do NOT want to UTF-8 encode your data first and have Perl
1223 encode it another time).
1224 "utf8" flag enabled
1226 If the "utf8"-flag is enabled, "encode"/"decode" will encode all
1227 characters using the corresponding UTF-8 multi-byte sequence, and
1228 will expect your input strings to be encoded as UTF-8, that is, no
1229 "character" of the input string must have any value > 255, as UTF-8
1230 does not allow that.
1231 The "utf8" flag therefore switches between two modes: disabled
1233 means you will get a Unicode string in Perl, enabled means you get
1234 an UTF-8 encoded octet/binary string in Perl.
1235 "latin1" or "ascii" flags enabled
1237 With "latin1" (or "ascii") enabled, "encode" will escape characters
1238 with ordinal values > 255 (> 127 with "ascii") and encode the
1239 remaining characters as specified by the "utf8" flag.
1240 If "utf8" is disabled, then the result is also correctly encoded in
1242 those character sets (as both are proper subsets of Unicode,
1243 meaning that a Unicode string with all character values < 256 is
1244 the same thing as a ISO-8859-1 string, and a Unicode string with
1245 all character values < 128 is the same thing as an ASCII string in
1246 Perl).
1247 If "utf8" is enabled, you still get a correct UTF-8-encoded string,
1249 regardless of these flags, just some more characters will be
1250 escaped using "\uXXXX" then before.
1251 Note that ISO-8859-1-encoded strings are not compatible with UTF-8
1253 encoding, while ASCII-encoded strings are. That is because the
1254 ISO-8859-1 encoding is NOT a subset of UTF-8 (despite the
1255 ISO-8859-1 codeset being a subset of Unicode), while ASCII is.
1256 Surprisingly, "decode" will ignore these flags and so treat all
1258 input values as governed by the "utf8" flag. If it is disabled,
1259 this allows you to decode ISO-8859-1- and ASCII-encoded strings, as
1260 both strict subsets of Unicode. If it is enabled, you can correctly
1261 decode UTF-8 encoded strings.
1262 So neither "latin1" nor "ascii" are incompatible with the "utf8"
1264 flag - they only govern when the JSON output engine escapes a
1265 character or not.
1266 The main use for "latin1" is to relatively efficiently store binary
1268 data as JSON, at the expense of breaking compatibility with most
1269 JSON decoders.
1270 The main use for "ascii" is to force the output to not contain
1272 characters with values > 127, which means you can interpret the
1273 resulting string as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about
1274 any character set and 8-bit-encoding, and still get the same data
1275 structure back. This is useful when your channel for JSON transfer
1276 is not 8-bit clean or the encoding might be mangled in between
1277 (e.g. in mail), and works because ASCII is a proper subset of most
1278 8-bit and multibyte encodings in use in the world.
1279
1281 Please report bugs on a specific behavior of this module to RT or
1282 GitHub issues (preferred):
1283 <https://github.com/makamaka/JSON-PP/issues>
1285 <https://rt.cpan.org/Public/Dist/Display.html?Queue=JSON-PP>
1287 As for new features and requests to change common behaviors, please ask
1289 the author of JSON::XS (Marc Lehmann, <schmorp[at]schmorp.de>) first,
1290 by email (important!), to keep compatibility among JSON.pm backends.
1291 Generally speaking, if you need something special for you, you are
1293 advised to create a new module, maybe based on JSON::Tiny, which is
1294 smaller and written in a much cleaner way than this module.
1295
1297 The json_pp command line utility for quick experiments.
1298 JSON::XS, Cpanel::JSON::XS, and JSON::Tiny for faster alternatives.
1300 JSON and JSON::MaybeXS for easy migration.
1301 JSON::PP::Compat5005 and JSON::PP::Compat5006 for older perl users.
1303 RFC4627 (<http://www.ietf.org/rfc/rfc4627.txt>)
1305 RFC7159 (<http://www.ietf.org/rfc/rfc7159.txt>)
1307 RFC8259 (<http://www.ietf.org/rfc/rfc8259.txt>)
1309
1311 Makamaka Hannyaharamitu, <makamaka[at]cpan.org>
1312
1314 Kenichi Ishigaki, <ishigaki[at]cpan.org>
1315
1317 Copyright 2007-2016 by Makamaka Hannyaharamitu
1318 Most of the documentation is taken from JSON::XS by Marc Lehmann
1320 This library is free software; you can redistribute it and/or modify it
1322 under the same terms as Perl itself.
1323perl v5.34.0 2022-01-21 JSON::PP(3)