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 4.02
31
33 JSON::PP is a pure perl JSON decoder/encoder, and (almost) compatible
34 to much faster JSON::XS written by Marc Lehmann in C. JSON::PP works as
35 a fallback module when you use JSON module without having installed
36 JSON::XS.
37 Because of this fallback feature of JSON.pm, JSON::PP tries not to be
39 more JavaScript-friendly than JSON::XS (i.e. not to escape extra
40 characters such as U+2028 and U+2029, etc), in order for you not to
41 lose such JavaScript-friendliness silently when you use JSON.pm and
42 install JSON::XS for speed or by accident. If you need JavaScript-
43 friendly RFC7159-compliant pure perl module, try JSON::Tiny, which is
44 derived from Mojolicious web framework and is also smaller and faster
45 than JSON::PP.
46 JSON::PP has been in the Perl core since Perl 5.14, mainly for CPAN
48 toolchain modules to parse META.json.
49
51 This section is taken from JSON::XS almost verbatim. "encode_json" and
52 "decode_json" are exported by default.
53 encode_json
55 $json_text = encode_json $perl_scalar
56 Converts the given Perl data structure to a UTF-8 encoded, binary
58 string (that is, the string contains octets only). Croaks on error.
59 This function call is functionally identical to:
61 $json_text = JSON::PP->new->utf8->encode($perl_scalar)
63 Except being faster.
65 decode_json
67 $perl_scalar = decode_json $json_text
68 The opposite of "encode_json": expects an UTF-8 (binary) string and
70 tries to parse that as an UTF-8 encoded JSON text, returning the
71 resulting reference. Croaks on error.
72 This function call is functionally identical to:
74 $perl_scalar = JSON::PP->new->utf8->decode($json_text)
76 Except being faster.
78 JSON::PP::is_bool
80 $is_boolean = JSON::PP::is_bool($scalar)
81 Returns true if the passed scalar represents either JSON::PP::true or
83 JSON::PP::false, two constants that act like 1 and 0 respectively and
84 are also used to represent JSON "true" and "false" in Perl strings.
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 filter_json_object
493 $json = $json->filter_json_object([$coderef])
494 When $coderef is specified, it will be called from "decode" each time
496 it decodes a JSON object. The only argument is a reference to the
497 newly-created hash. If the code references returns a single scalar
498 (which need not be a reference), this value (or rather a copy of it) is
499 inserted into the deserialised data structure. If it returns an empty
500 list (NOTE: not "undef", which is a valid scalar), the original
501 deserialised hash will be inserted. This setting can slow down decoding
502 considerably.
503 When $coderef is omitted or undefined, any existing callback will be
505 removed and "decode" will not change the deserialised hash in any way.
506 Example, convert all JSON objects into the integer 5:
508 my $js = JSON::PP->new->filter_json_object(sub { 5 });
510 # returns [5]
511 $js->decode('[{}]');
512 # returns 5
513 $js->decode('{"a":1, "b":2}');
514 filter_json_single_key_object
516 $json = $json->filter_json_single_key_object($key [=> $coderef])
517 Works remotely similar to "filter_json_object", but is only called for
519 JSON objects having a single key named $key.
520 This $coderef is called before the one specified via
522 "filter_json_object", if any. It gets passed the single value in the
523 JSON object. If it returns a single value, it will be inserted into the
524 data structure. If it returns nothing (not even "undef" but the empty
525 list), the callback from "filter_json_object" will be called next, as
526 if no single-key callback were specified.
527 If $coderef is omitted or undefined, the corresponding callback will be
529 disabled. There can only ever be one callback for a given key.
530 As this callback gets called less often then the "filter_json_object"
532 one, decoding speed will not usually suffer as much. Therefore, single-
533 key objects make excellent targets to serialise Perl objects into,
534 especially as single-key JSON objects are as close to the type-tagged
535 value concept as JSON gets (it's basically an ID/VALUE tuple). Of
536 course, JSON does not support this in any way, so you need to make sure
537 your data never looks like a serialised Perl hash.
538 Typical names for the single object key are "__class_whatever__", or
540 "$__dollars_are_rarely_used__$" or "}ugly_brace_placement", or even
541 things like "__class_md5sum(classname)__", to reduce the risk of
542 clashing with real hashes.
543 Example, decode JSON objects of the form "{ "__widget__" => <id> }"
545 into the corresponding $WIDGET{<id>} object:
546 # return whatever is in $WIDGET{5}:
548 JSON::PP
549 ->new
550 ->filter_json_single_key_object (__widget__ => sub {
551 $WIDGET{ $_[0] }
552 })
553 ->decode ('{"__widget__": 5')
554 # this can be used with a TO_JSON method in some "widget" class
556 # for serialisation to json:
557 sub WidgetBase::TO_JSON {
558 my ($self) = @_;
559 unless ($self->{id}) {
561 $self->{id} = ..get..some..id..;
562 $WIDGET{$self->{id}} = $self;
563 }
564 { __widget__ => $self->{id} }
566 }
567 shrink
569 $json = $json->shrink([$enable])
570 $enabled = $json->get_shrink
572 If $enable is true (or missing), the string returned by "encode" will
574 be shrunk (i.e. downgraded if possible).
575 The actual definition of what shrink does might change in future
577 versions, but it will always try to save space at the expense of time.
578 If $enable is false, then JSON::PP does nothing.
580 max_depth
582 $json = $json->max_depth([$maximum_nesting_depth])
583 $max_depth = $json->get_max_depth
585 Sets the maximum nesting level (default 512) accepted while encoding or
587 decoding. If a higher nesting level is detected in JSON text or a Perl
588 data structure, then the encoder and decoder will stop and croak at
589 that point.
590 Nesting level is defined by number of hash- or arrayrefs that the
592 encoder needs to traverse to reach a given point or the number of "{"
593 or "[" characters without their matching closing parenthesis crossed to
594 reach a given character in a string.
595 Setting the maximum depth to one disallows any nesting, so that ensures
597 that the object is only a single hash/object or array.
598 If no argument is given, the highest possible setting will be used,
600 which is rarely useful.
601 See "SECURITY CONSIDERATIONS" in JSON::XS for more info on why this is
603 useful.
604 max_size
606 $json = $json->max_size([$maximum_string_size])
607 $max_size = $json->get_max_size
609 Set the maximum length a JSON text may have (in bytes) where decoding
611 is being attempted. The default is 0, meaning no limit. When "decode"
612 is called on a string that is longer then this many bytes, it will not
613 attempt to decode the string but throw an exception. This setting has
614 no effect on "encode" (yet).
615 If no argument is given, the limit check will be deactivated (same as
617 when 0 is specified).
618 See "SECURITY CONSIDERATIONS" in JSON::XS for more info on why this is
620 useful.
621 encode
623 $json_text = $json->encode($perl_scalar)
624 Converts the given Perl value or data structure to its JSON
626 representation. Croaks on error.
627 decode
629 $perl_scalar = $json->decode($json_text)
630 The opposite of "encode": expects a JSON text and tries to parse it,
632 returning the resulting simple scalar or reference. Croaks on error.
633 decode_prefix
635 ($perl_scalar, $characters) = $json->decode_prefix($json_text)
636 This works like the "decode" method, but instead of raising an
638 exception when there is trailing garbage after the first JSON object,
639 it will silently stop parsing there and return the number of characters
640 consumed so far.
641 This is useful if your JSON texts are not delimited by an outer
643 protocol and you need to know where the JSON text ends.
644 JSON::PP->new->decode_prefix ("[1] the tail")
646 => ([1], 3)
647
649 The following flags and properties are for JSON::PP only. If you use
650 any of these, you can't make your application run faster by replacing
651 JSON::PP with JSON::XS. If you need these and also speed boost, you
652 might want to try Cpanel::JSON::XS, a fork of JSON::XS by Reini Urban,
653 which supports some of these (with a different set of
654 incompatibilities). Most of these historical flags are only kept for
655 backward compatibility, and should not be used in a new application.
656 allow_singlequote
658 $json = $json->allow_singlequote([$enable])
659 $enabled = $json->get_allow_singlequote
660 If $enable is true (or missing), then "decode" will accept invalid JSON
662 texts that contain strings that begin and end with single quotation
663 marks. "encode" will not be affected in any way. Be aware that this
664 option makes you accept invalid JSON texts as if they were valid!. I
665 suggest only to use this option to parse application-specific files
666 written by humans (configuration files, resource files etc.)
667 If $enable is false (the default), then "decode" will only accept valid
669 JSON texts.
670 $json->allow_singlequote->decode(qq|{"foo":'bar'}|);
672 $json->allow_singlequote->decode(qq|{'foo':"bar"}|);
673 $json->allow_singlequote->decode(qq|{'foo':'bar'}|);
674 allow_barekey
676 $json = $json->allow_barekey([$enable])
677 $enabled = $json->get_allow_barekey
678 If $enable is true (or missing), then "decode" will accept invalid JSON
680 texts that contain JSON objects whose names don't begin and end with
681 quotation marks. "encode" will not be affected in any way. Be aware
682 that this option makes you accept invalid JSON texts as if they were
683 valid!. I suggest only to use this option to parse application-specific
684 files written by humans (configuration files, resource files etc.)
685 If $enable is false (the default), then "decode" will only accept valid
687 JSON texts.
688 $json->allow_barekey->decode(qq|{foo:"bar"}|);
690 allow_bignum
692 $json = $json->allow_bignum([$enable])
693 $enabled = $json->get_allow_bignum
694 If $enable is true (or missing), then "decode" will convert big
696 integers Perl cannot handle as integer into Math::BigInt objects and
697 convert floating numbers into Math::BigFloat objects. "encode" will
698 convert "Math::BigInt" and "Math::BigFloat" objects into JSON numbers.
699 $json->allow_nonref->allow_bignum;
701 $bigfloat = $json->decode('2.000000000000000000000000001');
702 print $json->encode($bigfloat);
703 # => 2.000000000000000000000000001
704 See also MAPPING.
706 loose
708 $json = $json->loose([$enable])
709 $enabled = $json->get_loose
710 If $enable is true (or missing), then "decode" will accept invalid JSON
712 texts that contain unescaped [\x00-\x1f\x22\x5c] characters. "encode"
713 will not be affected in any way. Be aware that this option makes you
714 accept invalid JSON texts as if they were valid!. I suggest only to use
715 this option to parse application-specific files written by humans
716 (configuration files, resource files etc.)
717 If $enable is false (the default), then "decode" will only accept valid
719 JSON texts.
720 $json->loose->decode(qq|["abc
722 def"]|);
723 escape_slash
725 $json = $json->escape_slash([$enable])
726 $enabled = $json->get_escape_slash
727 If $enable is true (or missing), then "encode" will explicitly escape
729 slash (solidus; "U+002F") characters to reduce the risk of XSS (cross
730 site scripting) that may be caused by "</script>" in a JSON text, with
731 the cost of bloating the size of JSON texts.
732 This option may be useful when you embed JSON in HTML, but embedding
734 arbitrary JSON in HTML (by some HTML template toolkit or by string
735 interpolation) is risky in general. You must escape necessary
736 characters in correct order, depending on the context.
737 "decode" will not be affected in any way.
739 indent_length
741 $json = $json->indent_length($number_of_spaces)
742 $length = $json->get_indent_length
743 This option is only useful when you also enable "indent" or "pretty".
745 JSON::XS indents with three spaces when you "encode" (if requested by
747 "indent" or "pretty"), and the number cannot be changed. JSON::PP
748 allows you to change/get the number of indent spaces with these
749 mutator/accessor. The default number of spaces is three (the same as
750 JSON::XS), and the acceptable range is from 0 (no indentation; it'd be
751 better to disable indentation by indent(0)) to 15.
752 sort_by
754 $json = $json->sort_by($code_ref)
755 $json = $json->sort_by($subroutine_name)
756 If you just want to sort keys (names) in JSON objects when you
758 "encode", enable "canonical" option (see above) that allows you to sort
759 object keys alphabetically.
760 If you do need to sort non-alphabetically for whatever reasons, you can
762 give a code reference (or a subroutine name) to "sort_by", then the
763 argument will be passed to Perl's "sort" built-in function.
764 As the sorting is done in the JSON::PP scope, you usually need to
766 prepend "JSON::PP::" to the subroutine name, and the special variables
767 $a and $b used in the subrontine used by "sort" function.
768 Example:
770 my %ORDER = (id => 1, class => 2, name => 3);
772 $json->sort_by(sub {
773 ($ORDER{$JSON::PP::a} // 999) <=> ($ORDER{$JSON::PP::b} // 999)
774 or $JSON::PP::a cmp $JSON::PP::b
775 });
776 print $json->encode([
777 {name => 'CPAN', id => 1, href => 'http://cpan.org'}
778 ]);
779 # [{"id":1,"name":"CPAN","href":"http://cpan.org"}]
780 Note that "sort_by" affects all the plain hashes in the data structure.
782 If you need finer control, "tie" necessary hashes with a module that
783 implements ordered hash (such as Hash::Ordered and Tie::IxHash).
784 "canonical" and "sort_by" don't affect the key order in "tie"d hashes.
785 use Hash::Ordered;
787 tie my %hash, 'Hash::Ordered',
788 (name => 'CPAN', id => 1, href => 'http://cpan.org');
789 print $json->encode([\%hash]);
790 # [{"name":"CPAN","id":1,"href":"http://cpan.org"}] # order is kept
791
793 This section is also taken from JSON::XS.
794 In some cases, there is the need for incremental parsing of JSON texts.
796 While this module always has to keep both JSON text and resulting Perl
797 data structure in memory at one time, it does allow you to parse a JSON
798 stream incrementally. It does so by accumulating text until it has a
799 full JSON object, which it then can decode. This process is similar to
800 using "decode_prefix" to see if a full JSON object is available, but is
801 much more efficient (and can be implemented with a minimum of method
802 calls).
803 JSON::PP will only attempt to parse the JSON text once it is sure it
805 has enough text to get a decisive result, using a very simple but truly
806 incremental parser. This means that it sometimes won't stop as early as
807 the full parser, for example, it doesn't detect mismatched parentheses.
808 The only thing it guarantees is that it starts decoding as soon as a
809 syntactically valid JSON text has been seen. This means you need to set
810 resource limits (e.g. "max_size") to ensure the parser will stop
811 parsing in the presence if syntax errors.
812 The following methods implement this incremental parser.
814 incr_parse
816 $json->incr_parse( [$string] ) # void context
817 $obj_or_undef = $json->incr_parse( [$string] ) # scalar context
819 @obj_or_empty = $json->incr_parse( [$string] ) # list context
821 This is the central parsing function. It can both append new text and
823 extract objects from the stream accumulated so far (both of these
824 functions are optional).
825 If $string is given, then this string is appended to the already
827 existing JSON fragment stored in the $json object.
828 After that, if the function is called in void context, it will simply
830 return without doing anything further. This can be used to add more
831 text in as many chunks as you want.
832 If the method is called in scalar context, then it will try to extract
834 exactly one JSON object. If that is successful, it will return this
835 object, otherwise it will return "undef". If there is a parse error,
836 this method will croak just as "decode" would do (one can then use
837 "incr_skip" to skip the erroneous part). This is the most common way of
838 using the method.
839 And finally, in list context, it will try to extract as many objects
841 from the stream as it can find and return them, or the empty list
842 otherwise. For this to work, there must be no separators (other than
843 whitespace) between the JSON objects or arrays, instead they must be
844 concatenated back-to-back. If an error occurs, an exception will be
845 raised as in the scalar context case. Note that in this case, any
846 previously-parsed JSON texts will be lost.
847 Example: Parse some JSON arrays/objects in a given string and return
849 them.
850 my @objs = JSON::PP->new->incr_parse ("[5][7][1,2]");
852 incr_text
854 $lvalue_string = $json->incr_text
855 This method returns the currently stored JSON fragment as an lvalue,
857 that is, you can manipulate it. This only works when a preceding call
858 to "incr_parse" in scalar context successfully returned an object.
859 Under all other circumstances you must not call this function (I mean
860 it. although in simple tests it might actually work, it will fail
861 under real world conditions). As a special exception, you can also call
862 this method before having parsed anything.
863 That means you can only use this function to look at or manipulate text
865 before or after complete JSON objects, not while the parser is in the
866 middle of parsing a JSON object.
867 This function is useful in two cases: a) finding the trailing text
869 after a JSON object or b) parsing multiple JSON objects separated by
870 non-JSON text (such as commas).
871 incr_skip
873 $json->incr_skip
874 This will reset the state of the incremental parser and will remove the
876 parsed text from the input buffer so far. This is useful after
877 "incr_parse" died, in which case the input buffer and incremental
878 parser state is left unchanged, to skip the text parsed so far and to
879 reset the parse state.
880 The difference to "incr_reset" is that only text until the parse error
882 occurred is removed.
883 incr_reset
885 $json->incr_reset
886 This completely resets the incremental parser, that is, after this
888 call, it will be as if the parser had never parsed anything.
889 This is useful if you want to repeatedly parse JSON objects and want to
891 ignore any trailing data, which means you have to reset the parser
892 after each successful decode.
893
895 Most of this section is also taken from JSON::XS.
896 This section describes how JSON::PP maps Perl values to JSON values and
898 vice versa. These mappings are designed to "do the right thing" in most
899 circumstances automatically, preserving round-tripping characteristics
900 (what you put in comes out as something equivalent).
901 For the more enlightened: note that in the following descriptions,
903 lowercase perl refers to the Perl interpreter, while uppercase Perl
904 refers to the abstract Perl language itself.
905 JSON -> PERL
907 object
908 A JSON object becomes a reference to a hash in Perl. No ordering of
909 object keys is preserved (JSON does not preserve object key
910 ordering itself).
911 array
913 A JSON array becomes a reference to an array in Perl.
914 string
916 A JSON string becomes a string scalar in Perl - Unicode codepoints
917 in JSON are represented by the same codepoints in the Perl string,
918 so no manual decoding is necessary.
919 number
921 A JSON number becomes either an integer, numeric (floating point)
922 or string scalar in perl, depending on its range and any fractional
923 parts. On the Perl level, there is no difference between those as
924 Perl handles all the conversion details, but an integer may take
925 slightly less memory and might represent more values exactly than
926 floating point numbers.
927 If the number consists of digits only, JSON::PP will try to
929 represent it as an integer value. If that fails, it will try to
930 represent it as a numeric (floating point) value if that is
931 possible without loss of precision. Otherwise it will preserve the
932 number as a string value (in which case you lose roundtripping
933 ability, as the JSON number will be re-encoded to a JSON string).
934 Numbers containing a fractional or exponential part will always be
936 represented as numeric (floating point) values, possibly at a loss
937 of precision (in which case you might lose perfect roundtripping
938 ability, but the JSON number will still be re-encoded as a JSON
939 number).
940 Note that precision is not accuracy - binary floating point values
942 cannot represent most decimal fractions exactly, and when
943 converting from and to floating point, JSON::PP only guarantees
944 precision up to but not including the least significant bit.
945 When "allow_bignum" is enabled, big integer values and any numeric
947 values will be converted into Math::BigInt and Math::BigFloat
948 objects respectively, without becoming string scalars or losing
949 precision.
950 true, false
952 These JSON atoms become "JSON::PP::true" and "JSON::PP::false",
953 respectively. They are overloaded to act almost exactly like the
954 numbers 1 and 0. You can check whether a scalar is a JSON boolean
955 by using the "JSON::PP::is_bool" function.
956 null
958 A JSON null atom becomes "undef" in Perl.
959 shell-style comments ("# text")
961 As a nonstandard extension to the JSON syntax that is enabled by
962 the "relaxed" setting, shell-style comments are allowed. They can
963 start anywhere outside strings and go till the end of the line.
964 tagged values ("(tag)value").
966 Another nonstandard extension to the JSON syntax, enabled with the
967 "allow_tags" setting, are tagged values. In this implementation,
968 the tag must be a perl package/class name encoded as a JSON string,
969 and the value must be a JSON array encoding optional constructor
970 arguments.
971 See "OBJECT SERIALISATION", below, for details.
973 PERL -> JSON
975 The mapping from Perl to JSON is slightly more difficult, as Perl is a
976 truly typeless language, so we can only guess which JSON type is meant
977 by a Perl value.
978 hash references
980 Perl hash references become JSON objects. As there is no inherent
981 ordering in hash keys (or JSON objects), they will usually be
982 encoded in a pseudo-random order. JSON::PP can optionally sort the
983 hash keys (determined by the canonical flag and/or sort_by
984 property), so the same data structure will serialise to the same
985 JSON text (given same settings and version of JSON::PP), but this
986 incurs a runtime overhead and is only rarely useful, e.g. when you
987 want to compare some JSON text against another for equality.
988 array references
990 Perl array references become JSON arrays.
991 other references
993 Other unblessed references are generally not allowed and will cause
994 an exception to be thrown, except for references to the integers 0
995 and 1, which get turned into "false" and "true" atoms in JSON. You
996 can also use "JSON::PP::false" and "JSON::PP::true" to improve
997 readability.
998 to_json [\0, JSON::PP::true] # yields [false,true]
1000 JSON::PP::true, JSON::PP::false
1002 These special values become JSON true and JSON false values,
1003 respectively. You can also use "\1" and "\0" directly if you want.
1004 JSON::PP::null
1006 This special value becomes JSON null.
1007 blessed objects
1009 Blessed objects are not directly representable in JSON, but
1010 "JSON::PP" allows various ways of handling objects. See "OBJECT
1011 SERIALISATION", below, for details.
1012 simple scalars
1014 Simple Perl scalars (any scalar that is not a reference) are the
1015 most difficult objects to encode: JSON::PP will encode undefined
1016 scalars as JSON "null" values, scalars that have last been used in
1017 a string context before encoding as JSON strings, and anything else
1018 as number value:
1019 # dump as number
1021 encode_json [2] # yields [2]
1022 encode_json [-3.0e17] # yields [-3e+17]
1023 my $value = 5; encode_json [$value] # yields [5]
1024 # used as string, so dump as string
1026 print $value;
1027 encode_json [$value] # yields ["5"]
1028 # undef becomes null
1030 encode_json [undef] # yields [null]
1031 You can force the type to be a JSON string by stringifying it:
1033 my $x = 3.1; # some variable containing a number
1035 "$x"; # stringified
1036 $x .= ""; # another, more awkward way to stringify
1037 print $x; # perl does it for you, too, quite often
1038 # (but for older perls)
1039 You can force the type to be a JSON number by numifying it:
1041 my $x = "3"; # some variable containing a string
1043 $x += 0; # numify it, ensuring it will be dumped as a number
1044 $x *= 1; # same thing, the choice is yours.
1045 You can not currently force the type in other, less obscure, ways.
1047 Since version 2.91_01, JSON::PP uses a different number detection
1049 logic that converts a scalar that is possible to turn into a number
1050 safely. The new logic is slightly faster, and tends to help people
1051 who use older perl or who want to encode complicated data
1052 structure. However, this may results in a different JSON text from
1053 the one JSON::XS encodes (and thus may break tests that compare
1054 entire JSON texts). If you do need the previous behavior for
1055 compatibility or for finer control, set PERL_JSON_PP_USE_B
1056 environmental variable to true before you "use" JSON::PP (or
1057 JSON.pm).
1058 Note that numerical precision has the same meaning as under Perl
1060 (so binary to decimal conversion follows the same rules as in Perl,
1061 which can differ to other languages). Also, your perl interpreter
1062 might expose extensions to the floating point numbers of your
1063 platform, such as infinities or NaN's - these cannot be represented
1064 in JSON, and it is an error to pass those in.
1065 JSON::PP (and JSON::XS) trusts what you pass to "encode" method (or
1067 "encode_json" function) is a clean, validated data structure with
1068 values that can be represented as valid JSON values only, because
1069 it's not from an external data source (as opposed to JSON texts you
1070 pass to "decode" or "decode_json", which JSON::PP considers tainted
1071 and doesn't trust). As JSON::PP doesn't know exactly what you and
1072 consumers of your JSON texts want the unexpected values to be (you
1073 may want to convert them into null, or to stringify them with or
1074 without normalisation (string representation of infinities/NaN may
1075 vary depending on platforms), or to croak without conversion),
1076 you're advised to do what you and your consumers need before you
1077 encode, and also not to numify values that may start with values
1078 that look like a number (including infinities/NaN), without
1079 validating.
1080 OBJECT SERIALISATION
1082 As JSON cannot directly represent Perl objects, you have to choose
1083 between a pure JSON representation (without the ability to deserialise
1084 the object automatically again), and a nonstandard extension to the
1085 JSON syntax, tagged values.
1086 SERIALISATION
1088 What happens when "JSON::PP" encounters a Perl object depends on the
1090 "allow_blessed", "convert_blessed", "allow_tags" and "allow_bignum"
1091 settings, which are used in this order:
1092 1. "allow_tags" is enabled and the object has a "FREEZE" method.
1094 In this case, "JSON::PP" creates a tagged JSON value, using a
1095 nonstandard extension to the JSON syntax.
1096 This works by invoking the "FREEZE" method on the object, with the
1098 first argument being the object to serialise, and the second
1099 argument being the constant string "JSON" to distinguish it from
1100 other serialisers.
1101 The "FREEZE" method can return any number of values (i.e. zero or
1103 more). These values and the paclkage/classname of the object will
1104 then be encoded as a tagged JSON value in the following format:
1105 ("classname")[FREEZE return values...]
1107 e.g.:
1109 ("URI")["http://www.google.com/"]
1111 ("MyDate")[2013,10,29]
1112 ("ImageData::JPEG")["Z3...VlCg=="]
1113 For example, the hypothetical "My::Object" "FREEZE" method might
1115 use the objects "type" and "id" members to encode the object:
1116 sub My::Object::FREEZE {
1118 my ($self, $serialiser) = @_;
1119 ($self->{type}, $self->{id})
1121 }
1122 2. "convert_blessed" is enabled and the object has a "TO_JSON" method.
1124 In this case, the "TO_JSON" method of the object is invoked in
1125 scalar context. It must return a single scalar that can be directly
1126 encoded into JSON. This scalar replaces the object in the JSON
1127 text.
1128 For example, the following "TO_JSON" method will convert all URI
1130 objects to JSON strings when serialised. The fact that these values
1131 originally were URI objects is lost.
1132 sub URI::TO_JSON {
1134 my ($uri) = @_;
1135 $uri->as_string
1136 }
1137 3. "allow_bignum" is enabled and the object is a "Math::BigInt" or
1139 "Math::BigFloat".
1140 The object will be serialised as a JSON number value.
1141 4. "allow_blessed" is enabled.
1143 The object will be serialised as a JSON null value.
1144 5. none of the above
1146 If none of the settings are enabled or the respective methods are
1147 missing, "JSON::PP" throws an exception.
1148 DESERIALISATION
1150 For deserialisation there are only two cases to consider: either
1152 nonstandard tagging was used, in which case "allow_tags" decides, or
1153 objects cannot be automatically be deserialised, in which case you can
1154 use postprocessing or the "filter_json_object" or
1155 "filter_json_single_key_object" callbacks to get some real objects our
1156 of your JSON.
1157 This section only considers the tagged value case: a tagged JSON object
1159 is encountered during decoding and "allow_tags" is disabled, a parse
1160 error will result (as if tagged values were not part of the grammar).
1161 If "allow_tags" is enabled, "JSON::PP" will look up the "THAW" method
1163 of the package/classname used during serialisation (it will not attempt
1164 to load the package as a Perl module). If there is no such method, the
1165 decoding will fail with an error.
1166 Otherwise, the "THAW" method is invoked with the classname as first
1168 argument, the constant string "JSON" as second argument, and all the
1169 values from the JSON array (the values originally returned by the
1170 "FREEZE" method) as remaining arguments.
1171 The method must then return the object. While technically you can
1173 return any Perl scalar, you might have to enable the "allow_nonref"
1174 setting to make that work in all cases, so better return an actual
1175 blessed reference.
1176 As an example, let's implement a "THAW" function that regenerates the
1178 "My::Object" from the "FREEZE" example earlier:
1179 sub My::Object::THAW {
1181 my ($class, $serialiser, $type, $id) = @_;
1182 $class->new (type => $type, id => $id)
1184 }
1185
1187 This section is taken from JSON::XS.
1188 The interested reader might have seen a number of flags that signify
1190 encodings or codesets - "utf8", "latin1" and "ascii". There seems to be
1191 some confusion on what these do, so here is a short comparison:
1192 "utf8" controls whether the JSON text created by "encode" (and expected
1194 by "decode") is UTF-8 encoded or not, while "latin1" and "ascii" only
1195 control whether "encode" escapes character values outside their
1196 respective codeset range. Neither of these flags conflict with each
1197 other, although some combinations make less sense than others.
1198 Care has been taken to make all flags symmetrical with respect to
1200 "encode" and "decode", that is, texts encoded with any combination of
1201 these flag values will be correctly decoded when the same flags are
1202 used - in general, if you use different flag settings while encoding
1203 vs. when decoding you likely have a bug somewhere.
1204 Below comes a verbose discussion of these flags. Note that a "codeset"
1206 is simply an abstract set of character-codepoint pairs, while an
1207 encoding takes those codepoint numbers and encodes them, in our case
1208 into octets. Unicode is (among other things) a codeset, UTF-8 is an
1209 encoding, and ISO-8859-1 (= latin 1) and ASCII are both codesets and
1210 encodings at the same time, which can be confusing.
1211 "utf8" flag disabled
1213 When "utf8" is disabled (the default), then "encode"/"decode"
1214 generate and expect Unicode strings, that is, characters with high
1215 ordinal Unicode values (> 255) will be encoded as such characters,
1216 and likewise such characters are decoded as-is, no changes to them
1217 will be done, except "(re-)interpreting" them as Unicode codepoints
1218 or Unicode characters, respectively (to Perl, these are the same
1219 thing in strings unless you do funny/weird/dumb stuff).
1220 This is useful when you want to do the encoding yourself (e.g. when
1222 you want to have UTF-16 encoded JSON texts) or when some other
1223 layer does the encoding for you (for example, when printing to a
1224 terminal using a filehandle that transparently encodes to UTF-8 you
1225 certainly do NOT want to UTF-8 encode your data first and have Perl
1226 encode it another time).
1227 "utf8" flag enabled
1229 If the "utf8"-flag is enabled, "encode"/"decode" will encode all
1230 characters using the corresponding UTF-8 multi-byte sequence, and
1231 will expect your input strings to be encoded as UTF-8, that is, no
1232 "character" of the input string must have any value > 255, as UTF-8
1233 does not allow that.
1234 The "utf8" flag therefore switches between two modes: disabled
1236 means you will get a Unicode string in Perl, enabled means you get
1237 an UTF-8 encoded octet/binary string in Perl.
1238 "latin1" or "ascii" flags enabled
1240 With "latin1" (or "ascii") enabled, "encode" will escape characters
1241 with ordinal values > 255 (> 127 with "ascii") and encode the
1242 remaining characters as specified by the "utf8" flag.
1243 If "utf8" is disabled, then the result is also correctly encoded in
1245 those character sets (as both are proper subsets of Unicode,
1246 meaning that a Unicode string with all character values < 256 is
1247 the same thing as a ISO-8859-1 string, and a Unicode string with
1248 all character values < 128 is the same thing as an ASCII string in
1249 Perl).
1250 If "utf8" is enabled, you still get a correct UTF-8-encoded string,
1252 regardless of these flags, just some more characters will be
1253 escaped using "\uXXXX" then before.
1254 Note that ISO-8859-1-encoded strings are not compatible with UTF-8
1256 encoding, while ASCII-encoded strings are. That is because the
1257 ISO-8859-1 encoding is NOT a subset of UTF-8 (despite the
1258 ISO-8859-1 codeset being a subset of Unicode), while ASCII is.
1259 Surprisingly, "decode" will ignore these flags and so treat all
1261 input values as governed by the "utf8" flag. If it is disabled,
1262 this allows you to decode ISO-8859-1- and ASCII-encoded strings, as
1263 both strict subsets of Unicode. If it is enabled, you can correctly
1264 decode UTF-8 encoded strings.
1265 So neither "latin1" nor "ascii" are incompatible with the "utf8"
1267 flag - they only govern when the JSON output engine escapes a
1268 character or not.
1269 The main use for "latin1" is to relatively efficiently store binary
1271 data as JSON, at the expense of breaking compatibility with most
1272 JSON decoders.
1273 The main use for "ascii" is to force the output to not contain
1275 characters with values > 127, which means you can interpret the
1276 resulting string as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about
1277 any character set and 8-bit-encoding, and still get the same data
1278 structure back. This is useful when your channel for JSON transfer
1279 is not 8-bit clean or the encoding might be mangled in between
1280 (e.g. in mail), and works because ASCII is a proper subset of most
1281 8-bit and multibyte encodings in use in the world.
1282
1284 Please report bugs on a specific behavior of this module to RT or
1285 GitHub issues (preferred):
1286 <https://github.com/makamaka/JSON-PP/issues>
1288 <https://rt.cpan.org/Public/Dist/Display.html?Queue=JSON-PP>
1290 As for new features and requests to change common behaviors, please ask
1292 the author of JSON::XS (Marc Lehmann, <schmorp[at]schmorp.de>) first,
1293 by email (important!), to keep compatibility among JSON.pm backends.
1294 Generally speaking, if you need something special for you, you are
1296 advised to create a new module, maybe based on JSON::Tiny, which is
1297 smaller and written in a much cleaner way than this module.
1298
1300 The json_pp command line utility for quick experiments.
1301 JSON::XS, Cpanel::JSON::XS, and JSON::Tiny for faster alternatives.
1303 JSON and JSON::MaybeXS for easy migration.
1304 JSON::backportPP::Compat5005 and JSON::backportPP::Compat5006 for older
1306 perl users.
1307 RFC4627 (<http://www.ietf.org/rfc/rfc4627.txt>)
1309 RFC7159 (<http://www.ietf.org/rfc/rfc7159.txt>)
1311 RFC8259 (<http://www.ietf.org/rfc/rfc8259.txt>)
1313
1315 Makamaka Hannyaharamitu, <makamaka[at]cpan.org>
1316
1318 Kenichi Ishigaki, <ishigaki[at]cpan.org>
1319
1321 Copyright 2007-2016 by Makamaka Hannyaharamitu
1322 Most of the documentation is taken from JSON::XS by Marc Lehmann
1324 This library is free software; you can redistribute it and/or modify it
1326 under the same terms as Perl itself.
1327perl v5.32.0 2020-07-28 JSON::backportPP(3)