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 2.97001
31
33 JSON::PP is a pure perl JSON decoder/encoder (as of RFC4627, which we
34 know is obsolete but we still stick to; see below for an option to
35 support part of RFC7159), and (almost) compatible to much faster
36 JSON::XS written by Marc Lehmann in C. JSON::PP works as a fallback
37 module when you use JSON module without having installed JSON::XS.
38 Because of this fallback feature of JSON.pm, JSON::PP tries not to be
40 more JavaScript-friendly than JSON::XS (i.e. not to escape extra
41 characters such as U+2028 and U+2029 nor support RFC7159/ECMA-404), in
42 order for you not to lose such JavaScript-friendliness silently when
43 you use JSON.pm and install JSON::XS for speed or by accident. If you
44 need JavaScript-friendly RFC7159-compliant pure perl module, try
45 JSON::Tiny, which is derived from Mojolicious web framework and is also
46 smaller and faster than JSON::PP.
47 JSON::PP has been in the Perl core since Perl 5.14, mainly for CPAN
49 toolchain modules to parse META.json.
50
52 This section is taken from JSON::XS almost verbatim. "encode_json" and
53 "decode_json" are exported by default.
54 encode_json
56 $json_text = encode_json $perl_scalar
57 Converts the given Perl data structure to a UTF-8 encoded, binary
59 string (that is, the string contains octets only). Croaks on error.
60 This function call is functionally identical to:
62 $json_text = JSON::PP->new->utf8->encode($perl_scalar)
64 Except being faster.
66 decode_json
68 $perl_scalar = decode_json $json_text
69 The opposite of "encode_json": expects an UTF-8 (binary) string and
71 tries to parse that as an UTF-8 encoded JSON text, returning the
72 resulting reference. Croaks on error.
73 This function call is functionally identical to:
75 $perl_scalar = JSON::PP->new->utf8->decode($json_text)
77 Except being faster.
79 JSON::PP::is_bool
81 $is_boolean = JSON::PP::is_bool($scalar)
82 Returns true if the passed scalar represents either JSON::PP::true or
84 JSON::PP::false, two constants that act like 1 and 0 respectively and
85 are also used to represent JSON "true" and "false" in Perl strings.
86 See MAPPING, below, for more information on how JSON values are mapped
88 to Perl.
89
91 This section is also taken from JSON::XS.
92 The object oriented interface lets you configure your own encoding or
94 decoding style, within the limits of supported formats.
95 new
97 $json = JSON::PP->new
98 Creates a new JSON::PP object that can be used to de/encode JSON
100 strings. All boolean flags described below are by default disabled.
101 The mutators for flags all return the JSON::PP object again and thus
103 calls can be chained:
104 my $json = JSON::PP->new->utf8->space_after->encode({a => [1,2]})
106 => {"a": [1, 2]}
107 ascii
109 $json = $json->ascii([$enable])
110 $enabled = $json->get_ascii
112 If $enable is true (or missing), then the "encode" method will not
114 generate characters outside the code range 0..127 (which is ASCII). Any
115 Unicode characters outside that range will be escaped using either a
116 single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape
117 sequence, as per RFC4627. The resulting encoded JSON text can be
118 treated as a native Unicode string, an ascii-encoded, latin1-encoded or
119 UTF-8 encoded string, or any other superset of ASCII.
120 If $enable is false, then the "encode" method will not escape Unicode
122 characters unless required by the JSON syntax or other flags. This
123 results in a faster and more compact format.
124 See also the section ENCODING/CODESET FLAG NOTES later in this
126 document.
127 The main use for this flag is to produce JSON texts that can be
129 transmitted over a 7-bit channel, as the encoded JSON texts will not
130 contain any 8 bit characters.
131 JSON::PP->new->ascii(1)->encode([chr 0x10401])
133 => ["\ud801\udc01"]
134 latin1
136 $json = $json->latin1([$enable])
137 $enabled = $json->get_latin1
139 If $enable is true (or missing), then the "encode" method will encode
141 the resulting JSON text as latin1 (or iso-8859-1), escaping any
142 characters outside the code range 0..255. The resulting string can be
143 treated as a latin1-encoded JSON text or a native Unicode string. The
144 "decode" method will not be affected in any way by this flag, as
145 "decode" by default expects Unicode, which is a strict superset of
146 latin1.
147 If $enable is false, then the "encode" method will not escape Unicode
149 characters unless required by the JSON syntax or other flags.
150 See also the section ENCODING/CODESET FLAG NOTES later in this
152 document.
153 The main use for this flag is efficiently encoding binary data as JSON
155 text, as most octets will not be escaped, resulting in a smaller
156 encoded size. The disadvantage is that the resulting JSON text is
157 encoded in latin1 (and must correctly be treated as such when storing
158 and transferring), a rare encoding for JSON. It is therefore most
159 useful when you want to store data structures known to contain binary
160 data efficiently in files or databases, not when talking to other JSON
161 encoders/decoders.
162 JSON::PP->new->latin1->encode (["\x{89}\x{abc}"]
164 => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not)
165 utf8
167 $json = $json->utf8([$enable])
168 $enabled = $json->get_utf8
170 If $enable is true (or missing), then the "encode" method will encode
172 the JSON result into UTF-8, as required by many protocols, while the
173 "decode" method expects to be handled an UTF-8-encoded string. Please
174 note that UTF-8-encoded strings do not contain any characters outside
175 the range 0..255, they are thus useful for bytewise/binary I/O. In
176 future versions, enabling this option might enable autodetection of the
177 UTF-16 and UTF-32 encoding families, as described in RFC4627.
178 If $enable is false, then the "encode" method will return the JSON
180 string as a (non-encoded) Unicode string, while "decode" expects thus a
181 Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16)
182 needs to be done yourself, e.g. using the Encode module.
183 See also the section ENCODING/CODESET FLAG NOTES later in this
185 document.
186 Example, output UTF-16BE-encoded JSON:
188 use Encode;
190 $jsontext = encode "UTF-16BE", JSON::PP->new->encode ($object);
191 Example, decode UTF-32LE-encoded JSON:
193 use Encode;
195 $object = JSON::PP->new->decode (decode "UTF-32LE", $jsontext);
196 pretty
198 $json = $json->pretty([$enable])
199 This enables (or disables) all of the "indent", "space_before" and
201 "space_after" (and in the future possibly more) flags in one call to
202 generate the most readable (or most compact) form possible.
203 indent
205 $json = $json->indent([$enable])
206 $enabled = $json->get_indent
208 If $enable is true (or missing), then the "encode" method will use a
210 multiline format as output, putting every array member or object/hash
211 key-value pair into its own line, indenting them properly.
212 If $enable is false, no newlines or indenting will be produced, and the
214 resulting JSON text is guaranteed not to contain any "newlines".
215 This setting has no effect when decoding JSON texts.
217 The default indent space length is three. You can use "indent_length"
219 to change the length.
220 space_before
222 $json = $json->space_before([$enable])
223 $enabled = $json->get_space_before
225 If $enable is true (or missing), then the "encode" method will add an
227 extra optional space before the ":" separating keys from values in JSON
228 objects.
229 If $enable is false, then the "encode" method will not add any extra
231 space at those places.
232 This setting has no effect when decoding JSON texts. You will also most
234 likely combine this setting with "space_after".
235 Example, space_before enabled, space_after and indent disabled:
237 {"key" :"value"}
239 space_after
241 $json = $json->space_after([$enable])
242 $enabled = $json->get_space_after
244 If $enable is true (or missing), then the "encode" method will add an
246 extra optional space after the ":" separating keys from values in JSON
247 objects and extra whitespace after the "," separating key-value pairs
248 and array members.
249 If $enable is false, then the "encode" method will not add any extra
251 space at those places.
252 This setting has no effect when decoding JSON texts.
254 Example, space_before and indent disabled, space_after enabled:
256 {"key": "value"}
258 relaxed
260 $json = $json->relaxed([$enable])
261 $enabled = $json->get_relaxed
263 If $enable is true (or missing), then "decode" will accept some
265 extensions to normal JSON syntax (see below). "encode" will not be
266 affected in anyway. Be aware that this option makes you accept invalid
267 JSON texts as if they were valid!. I suggest only to use this option to
268 parse application-specific files written by humans (configuration
269 files, resource files etc.)
270 If $enable is false (the default), then "decode" will only accept valid
272 JSON texts.
273 Currently accepted extensions are:
275 · list items can have an end-comma
277 JSON separates array elements and key-value pairs with commas. This
279 can be annoying if you write JSON texts manually and want to be
280 able to quickly append elements, so this extension accepts comma at
281 the end of such items not just between them:
282 [
284 1,
285 2, <- this comma not normally allowed
286 ]
287 {
288 "k1": "v1",
289 "k2": "v2", <- this comma not normally allowed
290 }
291 · shell-style '#'-comments
293 Whenever JSON allows whitespace, shell-style comments are
295 additionally allowed. They are terminated by the first carriage-
296 return or line-feed character, after which more white-space and
297 comments are allowed.
298 [
300 1, # this comment not allowed in JSON
301 # neither this one...
302 ]
303 · C-style multiple-line '/* */'-comments (JSON::PP only)
305 Whenever JSON allows whitespace, C-style multiple-line comments are
307 additionally allowed. Everything between "/*" and "*/" is a
308 comment, after which more white-space and comments are allowed.
309 [
311 1, /* this comment not allowed in JSON */
312 /* neither this one... */
313 ]
314 · C++-style one-line '//'-comments (JSON::PP only)
316 Whenever JSON allows whitespace, C++-style one-line comments are
318 additionally allowed. They are terminated by the first carriage-
319 return or line-feed character, after which more white-space and
320 comments are allowed.
321 [
323 1, // this comment not allowed in JSON
324 // neither this one...
325 ]
326 canonical
328 $json = $json->canonical([$enable])
329 $enabled = $json->get_canonical
331 If $enable is true (or missing), then the "encode" method will output
333 JSON objects by sorting their keys. This is adding a comparatively high
334 overhead.
335 If $enable is false, then the "encode" method will output key-value
337 pairs in the order Perl stores them (which will likely change between
338 runs of the same script, and can change even within the same run from
339 5.18 onwards).
340 This option is useful if you want the same data structure to be encoded
342 as the same JSON text (given the same overall settings). If it is
343 disabled, the same hash might be encoded differently even if contains
344 the same data, as key-value pairs have no inherent ordering in Perl.
345 This setting has no effect when decoding JSON texts.
347 This setting has currently no effect on tied hashes.
349 allow_nonref
351 $json = $json->allow_nonref([$enable])
352 $enabled = $json->get_allow_nonref
354 If $enable is true (or missing), then the "encode" method can convert a
356 non-reference into its corresponding string, number or null JSON value,
357 which is an extension to RFC4627. Likewise, "decode" will accept those
358 JSON values instead of croaking.
359 If $enable is false, then the "encode" method will croak if it isn't
361 passed an arrayref or hashref, as JSON texts must either be an object
362 or array. Likewise, "decode" will croak if given something that is not
363 a JSON object or array.
364 Example, encode a Perl scalar as JSON value with enabled
366 "allow_nonref", resulting in an invalid JSON text:
367 JSON::PP->new->allow_nonref->encode ("Hello, World!")
369 => "Hello, World!"
370 allow_unknown
372 $json = $json->allow_unknown ([$enable])
373 $enabled = $json->get_allow_unknown
375 If $enable is true (or missing), then "encode" will not throw an
377 exception when it encounters values it cannot represent in JSON (for
378 example, filehandles) but instead will encode a JSON "null" value. Note
379 that blessed objects are not included here and are handled separately
380 by c<allow_blessed>.
381 If $enable is false (the default), then "encode" will throw an
383 exception when it encounters anything it cannot encode as JSON.
384 This option does not affect "decode" in any way, and it is recommended
386 to leave it off unless you know your communications partner.
387 allow_blessed
389 $json = $json->allow_blessed([$enable])
390 $enabled = $json->get_allow_blessed
392 See "OBJECT SERIALISATION" for details.
394 If $enable is true (or missing), then the "encode" method will not barf
396 when it encounters a blessed reference that it cannot convert
397 otherwise. Instead, a JSON "null" value is encoded instead of the
398 object.
399 If $enable is false (the default), then "encode" will throw an
401 exception when it encounters a blessed object that it cannot convert
402 otherwise.
403 This setting has no effect on "decode".
405 convert_blessed
407 $json = $json->convert_blessed([$enable])
408 $enabled = $json->get_convert_blessed
410 See "OBJECT SERIALISATION" for details.
412 If $enable is true (or missing), then "encode", upon encountering a
414 blessed object, will check for the availability of the "TO_JSON" method
415 on the object's class. If found, it will be called in scalar context
416 and the resulting scalar will be encoded instead of the object.
417 The "TO_JSON" method may safely call die if it wants. If "TO_JSON"
419 returns other blessed objects, those will be handled in the same way.
420 "TO_JSON" must take care of not causing an endless recursion cycle (==
421 crash) in this case. The name of "TO_JSON" was chosen because other
422 methods called by the Perl core (== not by the user of the object) are
423 usually in upper case letters and to avoid collisions with any
424 "to_json" function or method.
425 If $enable is false (the default), then "encode" will not consider this
427 type of conversion.
428 This setting has no effect on "decode".
430 filter_json_object
432 $json = $json->filter_json_object([$coderef])
433 When $coderef is specified, it will be called from "decode" each time
435 it decodes a JSON object. The only argument is a reference to the
436 newly-created hash. If the code references returns a single scalar
437 (which need not be a reference), this value (i.e. a copy of that scalar
438 to avoid aliasing) is inserted into the deserialised data structure. If
439 it returns an empty list (NOTE: not "undef", which is a valid scalar),
440 the original deserialised hash will be inserted. This setting can slow
441 down decoding considerably.
442 When $coderef is omitted or undefined, any existing callback will be
444 removed and "decode" will not change the deserialised hash in any way.
445 Example, convert all JSON objects into the integer 5:
447 my $js = JSON::PP->new->filter_json_object (sub { 5 });
449 # returns [5]
450 $js->decode ('[{}]'); # the given subroutine takes a hash reference.
451 # throw an exception because allow_nonref is not enabled
452 # so a lone 5 is not allowed.
453 $js->decode ('{"a":1, "b":2}');
454 filter_json_single_key_object
456 $json = $json->filter_json_single_key_object($key [=> $coderef])
457 Works remotely similar to "filter_json_object", but is only called for
459 JSON objects having a single key named $key.
460 This $coderef is called before the one specified via
462 "filter_json_object", if any. It gets passed the single value in the
463 JSON object. If it returns a single value, it will be inserted into the
464 data structure. If it returns nothing (not even "undef" but the empty
465 list), the callback from "filter_json_object" will be called next, as
466 if no single-key callback were specified.
467 If $coderef is omitted or undefined, the corresponding callback will be
469 disabled. There can only ever be one callback for a given key.
470 As this callback gets called less often then the "filter_json_object"
472 one, decoding speed will not usually suffer as much. Therefore, single-
473 key objects make excellent targets to serialise Perl objects into,
474 especially as single-key JSON objects are as close to the type-tagged
475 value concept as JSON gets (it's basically an ID/VALUE tuple). Of
476 course, JSON does not support this in any way, so you need to make sure
477 your data never looks like a serialised Perl hash.
478 Typical names for the single object key are "__class_whatever__", or
480 "$__dollars_are_rarely_used__$" or "}ugly_brace_placement", or even
481 things like "__class_md5sum(classname)__", to reduce the risk of
482 clashing with real hashes.
483 Example, decode JSON objects of the form "{ "__widget__" => <id> }"
485 into the corresponding $WIDGET{<id>} object:
486 # return whatever is in $WIDGET{5}:
488 JSON::PP
489 ->new
490 ->filter_json_single_key_object (__widget__ => sub {
491 $WIDGET{ $_[0] }
492 })
493 ->decode ('{"__widget__": 5')
494 # this can be used with a TO_JSON method in some "widget" class
496 # for serialisation to json:
497 sub WidgetBase::TO_JSON {
498 my ($self) = @_;
499 unless ($self->{id}) {
501 $self->{id} = ..get..some..id..;
502 $WIDGET{$self->{id}} = $self;
503 }
504 { __widget__ => $self->{id} }
506 }
507 shrink
509 $json = $json->shrink([$enable])
510 $enabled = $json->get_shrink
512 If $enable is true (or missing), the string returned by "encode" will
514 be shrunk (i.e. downgraded if possible).
515 The actual definition of what shrink does might change in future
517 versions, but it will always try to save space at the expense of time.
518 If $enable is false, then JSON::PP does nothing.
520 max_depth
522 $json = $json->max_depth([$maximum_nesting_depth])
523 $max_depth = $json->get_max_depth
525 Sets the maximum nesting level (default 512) accepted while encoding or
527 decoding. If a higher nesting level is detected in JSON text or a Perl
528 data structure, then the encoder and decoder will stop and croak at
529 that point.
530 Nesting level is defined by number of hash- or arrayrefs that the
532 encoder needs to traverse to reach a given point or the number of "{"
533 or "[" characters without their matching closing parenthesis crossed to
534 reach a given character in a string.
535 Setting the maximum depth to one disallows any nesting, so that ensures
537 that the object is only a single hash/object or array.
538 If no argument is given, the highest possible setting will be used,
540 which is rarely useful.
541 See "SECURITY CONSIDERATIONS" in JSON::XS for more info on why this is
543 useful.
544 max_size
546 $json = $json->max_size([$maximum_string_size])
547 $max_size = $json->get_max_size
549 Set the maximum length a JSON text may have (in bytes) where decoding
551 is being attempted. The default is 0, meaning no limit. When "decode"
552 is called on a string that is longer then this many bytes, it will not
553 attempt to decode the string but throw an exception. This setting has
554 no effect on "encode" (yet).
555 If no argument is given, the limit check will be deactivated (same as
557 when 0 is specified).
558 See "SECURITY CONSIDERATIONS" in JSON::XS for more info on why this is
560 useful.
561 encode
563 $json_text = $json->encode($perl_scalar)
564 Converts the given Perl value or data structure to its JSON
566 representation. Croaks on error.
567 decode
569 $perl_scalar = $json->decode($json_text)
570 The opposite of "encode": expects a JSON text and tries to parse it,
572 returning the resulting simple scalar or reference. Croaks on error.
573 decode_prefix
575 ($perl_scalar, $characters) = $json->decode_prefix($json_text)
576 This works like the "decode" method, but instead of raising an
578 exception when there is trailing garbage after the first JSON object,
579 it will silently stop parsing there and return the number of characters
580 consumed so far.
581 This is useful if your JSON texts are not delimited by an outer
583 protocol and you need to know where the JSON text ends.
584 JSON::PP->new->decode_prefix ("[1] the tail")
586 => ([1], 3)
587
589 The following flags and properties are for JSON::PP only. If you use
590 any of these, you can't make your application run faster by replacing
591 JSON::PP with JSON::XS. If you need these and also speed boost, try
592 Cpanel::JSON::XS, a fork of JSON::XS by Reini Urban, which supports
593 some of these.
594 allow_singlequote
596 $json = $json->allow_singlequote([$enable])
597 $enabled = $json->get_allow_singlequote
598 If $enable is true (or missing), then "decode" will accept invalid JSON
600 texts that contain strings that begin and end with single quotation
601 marks. "encode" will not be affected in anyway. Be aware that this
602 option makes you accept invalid JSON texts as if they were valid!. I
603 suggest only to use this option to parse application-specific files
604 written by humans (configuration files, resource files etc.)
605 If $enable is false (the default), then "decode" will only accept valid
607 JSON texts.
608 $json->allow_singlequote->decode(qq|{"foo":'bar'}|);
610 $json->allow_singlequote->decode(qq|{'foo':"bar"}|);
611 $json->allow_singlequote->decode(qq|{'foo':'bar'}|);
612 allow_barekey
614 $json = $json->allow_barekey([$enable])
615 $enabled = $json->get_allow_barekey
616 If $enable is true (or missing), then "decode" will accept invalid JSON
618 texts that contain JSON objects whose names don't begin and end with
619 quotation marks. "encode" will not be affected in anyway. Be aware that
620 this option makes you accept invalid JSON texts as if they were valid!.
621 I suggest only to use this option to parse application-specific files
622 written by humans (configuration files, resource files etc.)
623 If $enable is false (the default), then "decode" will only accept valid
625 JSON texts.
626 $json->allow_barekey->decode(qq|{foo:"bar"}|);
628 allow_bignum
630 $json = $json->allow_bignum([$enable])
631 $enabled = $json->get_allow_bignum
632 If $enable is true (or missing), then "decode" will convert big
634 integers Perl cannot handle as integer into Math::BigInt objects and
635 convert floating numbers into Math::BigFloat objects. "encode" will
636 convert "Math::BigInt" and "Math::BigFloat" objects into JSON numbers.
637 $json->allow_nonref->allow_bignum;
639 $bigfloat = $json->decode('2.000000000000000000000000001');
640 print $json->encode($bigfloat);
641 # => 2.000000000000000000000000001
642 See also MAPPING.
644 loose
646 $json = $json->loose([$enable])
647 $enabled = $json->get_loose
648 If $enable is true (or missing), then "decode" will accept invalid JSON
650 texts that contain unescaped [\x00-\x1f\x22\x5c] characters. "encode"
651 will not be affected in anyway. Be aware that this option makes you
652 accept invalid JSON texts as if they were valid!. I suggest only to use
653 this option to parse application-specific files written by humans
654 (configuration files, resource files etc.)
655 If $enable is false (the default), then "decode" will only accept valid
657 JSON texts.
658 $json->loose->decode(qq|["abc
660 def"]|);
661 escape_slash
663 $json = $json->escape_slash([$enable])
664 $enabled = $json->get_escape_slash
665 If $enable is true (or missing), then "encode" will explicitly escape
667 slash (solidus; "U+002F") characters to reduce the risk of XSS (cross
668 site scripting) that may be caused by "</script>" in a JSON text, with
669 the cost of bloating the size of JSON texts.
670 This option may be useful when you embed JSON in HTML, but embedding
672 arbitrary JSON in HTML (by some HTML template toolkit or by string
673 interpolation) is risky in general. You must escape necessary
674 characters in correct order, depending on the context.
675 "decode" will not be affected in anyway.
677 indent_length
679 $json = $json->indent_length($number_of_spaces)
680 $length = $json->get_indent_length
681 This option is only useful when you also enable "indent" or "pretty".
683 JSON::XS indents with three spaces when you "encode" (if requested by
685 "indent" or "pretty"), and the number cannot be changed. JSON::PP
686 allows you to change/get the number of indent spaces with these
687 mutator/accessor. The default number of spaces is three (the same as
688 JSON::XS), and the acceptable range is from 0 (no indentation; it'd be
689 better to disable indentation by indent(0)) to 15.
690 sort_by
692 $json = $json->sort_by($code_ref)
693 $json = $json->sort_by($subroutine_name)
694 If you just want to sort keys (names) in JSON objects when you
696 "encode", enable "canonical" option (see above) that allows you to sort
697 object keys alphabetically.
698 If you do need to sort non-alphabetically for whatever reasons, you can
700 give a code reference (or a subroutine name) to "sort_by", then the
701 argument will be passed to Perl's "sort" built-in function.
702 As the sorting is done in the JSON::PP scope, you usually need to
704 prepend "JSON::PP::" to the subroutine name, and the special variables
705 $a and $b used in the subrontine used by "sort" function.
706 Example:
708 my %ORDER = (id => 1, class => 2, name => 3);
710 $json->sort_by(sub {
711 ($ORDER{$JSON::PP::a} // 999) <=> ($ORDER{$JSON::PP::b} // 999)
712 or $JSON::PP::a cmp $JSON::PP::b
713 });
714 print $json->encode([
715 {name => 'CPAN', id => 1, href => 'http://cpan.org'}
716 ]);
717 # [{"id":1,"name":"CPAN","href":"http://cpan.org"}]
718 Note that "sort_by" affects all the plain hashes in the data structure.
720 If you need finer control, "tie" necessary hashes with a module that
721 implements ordered hash (such as Hash::Ordered and Tie::IxHash).
722 "canonical" and "sort_by" don't affect the key order in "tie"d hashes.
723 use Hash::Ordered;
725 tie my %hash, 'Hash::Ordered',
726 (name => 'CPAN', id => 1, href => 'http://cpan.org');
727 print $json->encode([\%hash]);
728 # [{"name":"CPAN","id":1,"href":"http://cpan.org"}] # order is kept
729
731 This section is also taken from JSON::XS.
732 In some cases, there is the need for incremental parsing of JSON texts.
734 While this module always has to keep both JSON text and resulting Perl
735 data structure in memory at one time, it does allow you to parse a JSON
736 stream incrementally. It does so by accumulating text until it has a
737 full JSON object, which it then can decode. This process is similar to
738 using "decode_prefix" to see if a full JSON object is available, but is
739 much more efficient (and can be implemented with a minimum of method
740 calls).
741 JSON::PP will only attempt to parse the JSON text once it is sure it
743 has enough text to get a decisive result, using a very simple but truly
744 incremental parser. This means that it sometimes won't stop as early as
745 the full parser, for example, it doesn't detect mismatched parentheses.
746 The only thing it guarantees is that it starts decoding as soon as a
747 syntactically valid JSON text has been seen. This means you need to set
748 resource limits (e.g. "max_size") to ensure the parser will stop
749 parsing in the presence if syntax errors.
750 The following methods implement this incremental parser.
752 incr_parse
754 $json->incr_parse( [$string] ) # void context
755 $obj_or_undef = $json->incr_parse( [$string] ) # scalar context
757 @obj_or_empty = $json->incr_parse( [$string] ) # list context
759 This is the central parsing function. It can both append new text and
761 extract objects from the stream accumulated so far (both of these
762 functions are optional).
763 If $string is given, then this string is appended to the already
765 existing JSON fragment stored in the $json object.
766 After that, if the function is called in void context, it will simply
768 return without doing anything further. This can be used to add more
769 text in as many chunks as you want.
770 If the method is called in scalar context, then it will try to extract
772 exactly one JSON object. If that is successful, it will return this
773 object, otherwise it will return "undef". If there is a parse error,
774 this method will croak just as "decode" would do (one can then use
775 "incr_skip" to skip the erroneous part). This is the most common way of
776 using the method.
777 And finally, in list context, it will try to extract as many objects
779 from the stream as it can find and return them, or the empty list
780 otherwise. For this to work, there must be no separators (other than
781 whitespace) between the JSON objects or arrays, instead they must be
782 concatenated back-to-back. If an error occurs, an exception will be
783 raised as in the scalar context case. Note that in this case, any
784 previously-parsed JSON texts will be lost.
785 Example: Parse some JSON arrays/objects in a given string and return
787 them.
788 my @objs = JSON::PP->new->incr_parse ("[5][7][1,2]");
790 incr_text
792 $lvalue_string = $json->incr_text
793 This method returns the currently stored JSON fragment as an lvalue,
795 that is, you can manipulate it. This only works when a preceding call
796 to "incr_parse" in scalar context successfully returned an object.
797 Under all other circumstances you must not call this function (I mean
798 it. although in simple tests it might actually work, it will fail
799 under real world conditions). As a special exception, you can also call
800 this method before having parsed anything.
801 That means you can only use this function to look at or manipulate text
803 before or after complete JSON objects, not while the parser is in the
804 middle of parsing a JSON object.
805 This function is useful in two cases: a) finding the trailing text
807 after a JSON object or b) parsing multiple JSON objects separated by
808 non-JSON text (such as commas).
809 incr_skip
811 $json->incr_skip
812 This will reset the state of the incremental parser and will remove the
814 parsed text from the input buffer so far. This is useful after
815 "incr_parse" died, in which case the input buffer and incremental
816 parser state is left unchanged, to skip the text parsed so far and to
817 reset the parse state.
818 The difference to "incr_reset" is that only text until the parse error
820 occurred is removed.
821 incr_reset
823 $json->incr_reset
824 This completely resets the incremental parser, that is, after this
826 call, it will be as if the parser had never parsed anything.
827 This is useful if you want to repeatedly parse JSON objects and want to
829 ignore any trailing data, which means you have to reset the parser
830 after each successful decode.
831
833 Most of this section is also taken from JSON::XS.
834 This section describes how JSON::PP maps Perl values to JSON values and
836 vice versa. These mappings are designed to "do the right thing" in most
837 circumstances automatically, preserving round-tripping characteristics
838 (what you put in comes out as something equivalent).
839 For the more enlightened: note that in the following descriptions,
841 lowercase perl refers to the Perl interpreter, while uppercase Perl
842 refers to the abstract Perl language itself.
843 JSON -> PERL
845 object
846 A JSON object becomes a reference to a hash in Perl. No ordering of
847 object keys is preserved (JSON does not preserve object key
848 ordering itself).
849 array
851 A JSON array becomes a reference to an array in Perl.
852 string
854 A JSON string becomes a string scalar in Perl - Unicode codepoints
855 in JSON are represented by the same codepoints in the Perl string,
856 so no manual decoding is necessary.
857 number
859 A JSON number becomes either an integer, numeric (floating point)
860 or string scalar in perl, depending on its range and any fractional
861 parts. On the Perl level, there is no difference between those as
862 Perl handles all the conversion details, but an integer may take
863 slightly less memory and might represent more values exactly than
864 floating point numbers.
865 If the number consists of digits only, JSON::PP will try to
867 represent it as an integer value. If that fails, it will try to
868 represent it as a numeric (floating point) value if that is
869 possible without loss of precision. Otherwise it will preserve the
870 number as a string value (in which case you lose roundtripping
871 ability, as the JSON number will be re-encoded to a JSON string).
872 Numbers containing a fractional or exponential part will always be
874 represented as numeric (floating point) values, possibly at a loss
875 of precision (in which case you might lose perfect roundtripping
876 ability, but the JSON number will still be re-encoded as a JSON
877 number).
878 Note that precision is not accuracy - binary floating point values
880 cannot represent most decimal fractions exactly, and when
881 converting from and to floating point, JSON::PP only guarantees
882 precision up to but not including the least significant bit.
883 When "allow_bignum" is enabled, big integer values and any numeric
885 values will be converted into Math::BigInt and Math::BigFloat
886 objects respectively, without becoming string scalars or losing
887 precision.
888 true, false
890 These JSON atoms become "JSON::PP::true" and "JSON::PP::false",
891 respectively. They are overloaded to act almost exactly like the
892 numbers 1 and 0. You can check whether a scalar is a JSON boolean
893 by using the "JSON::PP::is_bool" function.
894 null
896 A JSON null atom becomes "undef" in Perl.
897 shell-style comments ("# text")
899 As a nonstandard extension to the JSON syntax that is enabled by
900 the "relaxed" setting, shell-style comments are allowed. They can
901 start anywhere outside strings and go till the end of the line.
902 PERL -> JSON
904 The mapping from Perl to JSON is slightly more difficult, as Perl is a
905 truly typeless language, so we can only guess which JSON type is meant
906 by a Perl value.
907 hash references
909 Perl hash references become JSON objects. As there is no inherent
910 ordering in hash keys (or JSON objects), they will usually be
911 encoded in a pseudo-random order. JSON::PP can optionally sort the
912 hash keys (determined by the canonical flag and/or sort_by
913 property), so the same data structure will serialise to the same
914 JSON text (given same settings and version of JSON::PP), but this
915 incurs a runtime overhead and is only rarely useful, e.g. when you
916 want to compare some JSON text against another for equality.
917 array references
919 Perl array references become JSON arrays.
920 other references
922 Other unblessed references are generally not allowed and will cause
923 an exception to be thrown, except for references to the integers 0
924 and 1, which get turned into "false" and "true" atoms in JSON. You
925 can also use "JSON::PP::false" and "JSON::PP::true" to improve
926 readability.
927 to_json [\0, JSON::PP::true] # yields [false,true]
929 JSON::PP::true, JSON::PP::false
931 These special values become JSON true and JSON false values,
932 respectively. You can also use "\1" and "\0" directly if you want.
933 JSON::PP::null
935 This special value becomes JSON null.
936 blessed objects
938 Blessed objects are not directly representable in JSON, but
939 "JSON::PP" allows various ways of handling objects. See "OBJECT
940 SERIALISATION", below, for details.
941 simple scalars
943 Simple Perl scalars (any scalar that is not a reference) are the
944 most difficult objects to encode: JSON::PP will encode undefined
945 scalars as JSON "null" values, scalars that have last been used in
946 a string context before encoding as JSON strings, and anything else
947 as number value:
948 # dump as number
950 encode_json [2] # yields [2]
951 encode_json [-3.0e17] # yields [-3e+17]
952 my $value = 5; encode_json [$value] # yields [5]
953 # used as string, so dump as string
955 print $value;
956 encode_json [$value] # yields ["5"]
957 # undef becomes null
959 encode_json [undef] # yields [null]
960 You can force the type to be a string by stringifying it:
962 my $x = 3.1; # some variable containing a number
964 "$x"; # stringified
965 $x .= ""; # another, more awkward way to stringify
966 print $x; # perl does it for you, too, quite often
967 # (but for older perls)
968 You can force the type to be a number by numifying it:
970 my $x = "3"; # some variable containing a string
972 $x += 0; # numify it, ensuring it will be dumped as a number
973 $x *= 1; # same thing, the choice is yours.
974 You cannot currently force the type in other, less obscure, ways.
976 Note that numerical precision has the same meaning as under Perl
978 (so binary to decimal conversion follows the same rules as in Perl,
979 which can differ to other languages). Also, your perl interpreter
980 might expose extensions to the floating point numbers of your
981 platform, such as infinities or NaN's - these cannot be represented
982 in JSON, and it is an error to pass those in.
983 JSON::PP (and JSON::XS) trusts what you pass to "encode" method (or
985 "encode_json" function) is a clean, validated data structure with
986 values that can be represented as valid JSON values only, because
987 it's not from an external data source (as opposed to JSON texts you
988 pass to "decode" or "decode_json", which JSON::PP considers tainted
989 and doesn't trust). As JSON::PP doesn't know exactly what you and
990 consumers of your JSON texts want the unexpected values to be (you
991 may want to convert them into null, or to stringify them with or
992 without normalisation (string representation of infinities/NaN may
993 vary depending on platforms), or to croak without conversion),
994 you're advised to do what you and your consumers need before you
995 encode, and also not to numify values that may start with values
996 that look like a number (including infinities/NaN), without
997 validating.
998 OBJECT SERIALISATION
1000 As for Perl objects, JSON::PP only supports a pure JSON representation
1001 (without the ability to deserialise the object automatically again).
1002 SERIALISATION
1004 What happens when "JSON::PP" encounters a Perl object depends on the
1006 "allow_blessed", "convert_blessed" and "allow_bignum" settings, which
1007 are used in this order:
1008 1. "convert_blessed" is enabled and the object has a "TO_JSON" method.
1010 In this case, the "TO_JSON" method of the object is invoked in
1011 scalar context. It must return a single scalar that can be directly
1012 encoded into JSON. This scalar replaces the object in the JSON
1013 text.
1014 For example, the following "TO_JSON" method will convert all URI
1016 objects to JSON strings when serialised. The fact that these values
1017 originally were URI objects is lost.
1018 sub URI::TO_JSON {
1020 my ($uri) = @_;
1021 $uri->as_string
1022 }
1023 2. "allow_bignum" is enabled and the object is a "Math::BigInt" or
1025 "Math::BigFloat".
1026 The object will be serialised as a JSON number value.
1027 3. "allow_blessed" is enabled.
1029 The object will be serialised as a JSON null value.
1030 4. none of the above
1032 If none of the settings are enabled or the respective methods are
1033 missing, "JSON::PP" throws an exception.
1034
1036 This section is taken from JSON::XS.
1037 The interested reader might have seen a number of flags that signify
1039 encodings or codesets - "utf8", "latin1" and "ascii". There seems to be
1040 some confusion on what these do, so here is a short comparison:
1041 "utf8" controls whether the JSON text created by "encode" (and expected
1043 by "decode") is UTF-8 encoded or not, while "latin1" and "ascii" only
1044 control whether "encode" escapes character values outside their
1045 respective codeset range. Neither of these flags conflict with each
1046 other, although some combinations make less sense than others.
1047 Care has been taken to make all flags symmetrical with respect to
1049 "encode" and "decode", that is, texts encoded with any combination of
1050 these flag values will be correctly decoded when the same flags are
1051 used - in general, if you use different flag settings while encoding
1052 vs. when decoding you likely have a bug somewhere.
1053 Below comes a verbose discussion of these flags. Note that a "codeset"
1055 is simply an abstract set of character-codepoint pairs, while an
1056 encoding takes those codepoint numbers and encodes them, in our case
1057 into octets. Unicode is (among other things) a codeset, UTF-8 is an
1058 encoding, and ISO-8859-1 (= latin 1) and ASCII are both codesets and
1059 encodings at the same time, which can be confusing.
1060 "utf8" flag disabled
1062 When "utf8" is disabled (the default), then "encode"/"decode"
1063 generate and expect Unicode strings, that is, characters with high
1064 ordinal Unicode values (> 255) will be encoded as such characters,
1065 and likewise such characters are decoded as-is, no changes to them
1066 will be done, except "(re-)interpreting" them as Unicode codepoints
1067 or Unicode characters, respectively (to Perl, these are the same
1068 thing in strings unless you do funny/weird/dumb stuff).
1069 This is useful when you want to do the encoding yourself (e.g. when
1071 you want to have UTF-16 encoded JSON texts) or when some other
1072 layer does the encoding for you (for example, when printing to a
1073 terminal using a filehandle that transparently encodes to UTF-8 you
1074 certainly do NOT want to UTF-8 encode your data first and have Perl
1075 encode it another time).
1076 "utf8" flag enabled
1078 If the "utf8"-flag is enabled, "encode"/"decode" will encode all
1079 characters using the corresponding UTF-8 multi-byte sequence, and
1080 will expect your input strings to be encoded as UTF-8, that is, no
1081 "character" of the input string must have any value > 255, as UTF-8
1082 does not allow that.
1083 The "utf8" flag therefore switches between two modes: disabled
1085 means you will get a Unicode string in Perl, enabled means you get
1086 an UTF-8 encoded octet/binary string in Perl.
1087 "latin1" or "ascii" flags enabled
1089 With "latin1" (or "ascii") enabled, "encode" will escape characters
1090 with ordinal values > 255 (> 127 with "ascii") and encode the
1091 remaining characters as specified by the "utf8" flag.
1092 If "utf8" is disabled, then the result is also correctly encoded in
1094 those character sets (as both are proper subsets of Unicode,
1095 meaning that a Unicode string with all character values < 256 is
1096 the same thing as a ISO-8859-1 string, and a Unicode string with
1097 all character values < 128 is the same thing as an ASCII string in
1098 Perl).
1099 If "utf8" is enabled, you still get a correct UTF-8-encoded string,
1101 regardless of these flags, just some more characters will be
1102 escaped using "\uXXXX" then before.
1103 Note that ISO-8859-1-encoded strings are not compatible with UTF-8
1105 encoding, while ASCII-encoded strings are. That is because the
1106 ISO-8859-1 encoding is NOT a subset of UTF-8 (despite the
1107 ISO-8859-1 codeset being a subset of Unicode), while ASCII is.
1108 Surprisingly, "decode" will ignore these flags and so treat all
1110 input values as governed by the "utf8" flag. If it is disabled,
1111 this allows you to decode ISO-8859-1- and ASCII-encoded strings, as
1112 both strict subsets of Unicode. If it is enabled, you can correctly
1113 decode UTF-8 encoded strings.
1114 So neither "latin1" nor "ascii" are incompatible with the "utf8"
1116 flag - they only govern when the JSON output engine escapes a
1117 character or not.
1118 The main use for "latin1" is to relatively efficiently store binary
1120 data as JSON, at the expense of breaking compatibility with most
1121 JSON decoders.
1122 The main use for "ascii" is to force the output to not contain
1124 characters with values > 127, which means you can interpret the
1125 resulting string as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about
1126 any character set and 8-bit-encoding, and still get the same data
1127 structure back. This is useful when your channel for JSON transfer
1128 is not 8-bit clean or the encoding might be mangled in between
1129 (e.g. in mail), and works because ASCII is a proper subset of most
1130 8-bit and multibyte encodings in use in the world.
1131
1133 The json_pp command line utility for quick experiments.
1134 JSON::XS, Cpanel::JSON::XS, and JSON::Tiny for faster alternatives.
1136 JSON and JSON::MaybeXS for easy migration.
1137 JSON::PP::Compat5005 and JSON::PP::Compat5006 for older perl users.
1139 RFC4627 (<http://www.ietf.org/rfc/rfc4627.txt>)
1141
1143 Makamaka Hannyaharamitu, <makamaka[at]cpan.org>
1144
1146 Copyright 2007-2016 by Makamaka Hannyaharamitu
1147 This library is free software; you can redistribute it and/or modify it
1149 under the same terms as Perl itself.
1150perl v5.26.3 2017-12-21 JSON::PP(3)