1JSON::PP(3)           User Contributed Perl Documentation          JSON::PP(3)
2
3
4

NAME

6       JSON::PP - JSON::XS compatible pure-Perl module.
7

SYNOPSIS

9        use JSON::PP;
10
11        # exported functions, they croak on error
12        # and expect/generate UTF-8
13
14        $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
15        $perl_hash_or_arrayref  = decode_json $utf8_encoded_json_text;
16
17        # OO-interface
18
19        $json = JSON::PP->new->ascii->pretty->allow_nonref;
20
21        $pretty_printed_json_text = $json->encode( $perl_scalar );
22        $perl_scalar = $json->decode( $json_text );
23
24        # 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
27        use JSON;
28

VERSION

30           2.97001
31

DESCRIPTION

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
39       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
48       JSON::PP has been in the Perl core since Perl 5.14, mainly for CPAN
49       toolchain modules to parse META.json.
50

FUNCTIONAL INTERFACE

52       This section is taken from JSON::XS almost verbatim. "encode_json" and
53       "decode_json" are exported by default.
54
55   encode_json
56           $json_text = encode_json $perl_scalar
57
58       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
61       This function call is functionally identical to:
62
63           $json_text = JSON::PP->new->utf8->encode($perl_scalar)
64
65       Except being faster.
66
67   decode_json
68           $perl_scalar = decode_json $json_text
69
70       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
74       This function call is functionally identical to:
75
76           $perl_scalar = JSON::PP->new->utf8->decode($json_text)
77
78       Except being faster.
79
80   JSON::PP::is_bool
81           $is_boolean = JSON::PP::is_bool($scalar)
82
83       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
87       See MAPPING, below, for more information on how JSON values are mapped
88       to Perl.
89

OBJECT-ORIENTED INTERFACE

91       This section is also taken from JSON::XS.
92
93       The object oriented interface lets you configure your own encoding or
94       decoding style, within the limits of supported formats.
95
96   new
97           $json = JSON::PP->new
98
99       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
102       The mutators for flags all return the JSON::PP object again and thus
103       calls can be chained:
104
105          my $json = JSON::PP->new->utf8->space_after->encode({a => [1,2]})
106          => {"a": [1, 2]}
107
108   ascii
109           $json = $json->ascii([$enable])
110
111           $enabled = $json->get_ascii
112
113       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
121       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
125       See also the section ENCODING/CODESET FLAG NOTES later in this
126       document.
127
128       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
132         JSON::PP->new->ascii(1)->encode([chr 0x10401])
133         => ["\ud801\udc01"]
134
135   latin1
136           $json = $json->latin1([$enable])
137
138           $enabled = $json->get_latin1
139
140       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
148       If $enable is false, then the "encode" method will not escape Unicode
149       characters unless required by the JSON syntax or other flags.
150
151       See also the section ENCODING/CODESET FLAG NOTES later in this
152       document.
153
154       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
163         JSON::PP->new->latin1->encode (["\x{89}\x{abc}"]
164         => ["\x{89}\\u0abc"]    # (perl syntax, U+abc escaped, U+89 not)
165
166   utf8
167           $json = $json->utf8([$enable])
168
169           $enabled = $json->get_utf8
170
171       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
179       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
184       See also the section ENCODING/CODESET FLAG NOTES later in this
185       document.
186
187       Example, output UTF-16BE-encoded JSON:
188
189         use Encode;
190         $jsontext = encode "UTF-16BE", JSON::PP->new->encode ($object);
191
192       Example, decode UTF-32LE-encoded JSON:
193
194         use Encode;
195         $object = JSON::PP->new->decode (decode "UTF-32LE", $jsontext);
196
197   pretty
198           $json = $json->pretty([$enable])
199
200       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
204   indent
205           $json = $json->indent([$enable])
206
207           $enabled = $json->get_indent
208
209       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
213       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
216       This setting has no effect when decoding JSON texts.
217
218       The default indent space length is three.  You can use "indent_length"
219       to change the length.
220
221   space_before
222           $json = $json->space_before([$enable])
223
224           $enabled = $json->get_space_before
225
226       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
230       If $enable is false, then the "encode" method will not add any extra
231       space at those places.
232
233       This setting has no effect when decoding JSON texts. You will also most
234       likely combine this setting with "space_after".
235
236       Example, space_before enabled, space_after and indent disabled:
237
238          {"key" :"value"}
239
240   space_after
241           $json = $json->space_after([$enable])
242
243           $enabled = $json->get_space_after
244
245       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
250       If $enable is false, then the "encode" method will not add any extra
251       space at those places.
252
253       This setting has no effect when decoding JSON texts.
254
255       Example, space_before and indent disabled, space_after enabled:
256
257          {"key": "value"}
258
259   relaxed
260           $json = $json->relaxed([$enable])
261
262           $enabled = $json->get_relaxed
263
264       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
271       If $enable is false (the default), then "decode" will only accept valid
272       JSON texts.
273
274       Currently accepted extensions are:
275
276       ·   list items can have an end-comma
277
278           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
283              [
284                 1,
285                 2, <- this comma not normally allowed
286              ]
287              {
288                 "k1": "v1",
289                 "k2": "v2", <- this comma not normally allowed
290              }
291
292       ·   shell-style '#'-comments
293
294           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
299             [
300                1, # this comment not allowed in JSON
301                   # neither this one...
302             ]
303
304       ·   C-style multiple-line '/* */'-comments (JSON::PP only)
305
306           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
310             [
311                1, /* this comment not allowed in JSON */
312                   /* neither this one... */
313             ]
314
315       ·   C++-style one-line '//'-comments (JSON::PP only)
316
317           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
322             [
323                1, // this comment not allowed in JSON
324                   // neither this one...
325             ]
326
327   canonical
328           $json = $json->canonical([$enable])
329
330           $enabled = $json->get_canonical
331
332       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
336       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
341       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
346       This setting has no effect when decoding JSON texts.
347
348       This setting has currently no effect on tied hashes.
349
350   allow_nonref
351           $json = $json->allow_nonref([$enable])
352
353           $enabled = $json->get_allow_nonref
354
355       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
360       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
365       Example, encode a Perl scalar as JSON value with enabled
366       "allow_nonref", resulting in an invalid JSON text:
367
368          JSON::PP->new->allow_nonref->encode ("Hello, World!")
369          => "Hello, World!"
370
371   allow_unknown
372           $json = $json->allow_unknown ([$enable])
373
374           $enabled = $json->get_allow_unknown
375
376       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
382       If $enable is false (the default), then "encode" will throw an
383       exception when it encounters anything it cannot encode as JSON.
384
385       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
388   allow_blessed
389           $json = $json->allow_blessed([$enable])
390
391           $enabled = $json->get_allow_blessed
392
393       See "OBJECT SERIALISATION" for details.
394
395       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
400       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
404       This setting has no effect on "decode".
405
406   convert_blessed
407           $json = $json->convert_blessed([$enable])
408
409           $enabled = $json->get_convert_blessed
410
411       See "OBJECT SERIALISATION" for details.
412
413       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
418       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
426       If $enable is false (the default), then "encode" will not consider this
427       type of conversion.
428
429       This setting has no effect on "decode".
430
431   filter_json_object
432           $json = $json->filter_json_object([$coderef])
433
434       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
443       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
446       Example, convert all JSON objects into the integer 5:
447
448          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
455   filter_json_single_key_object
456           $json = $json->filter_json_single_key_object($key [=> $coderef])
457
458       Works remotely similar to "filter_json_object", but is only called for
459       JSON objects having a single key named $key.
460
461       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
468       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
471       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
479       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
484       Example, decode JSON objects of the form "{ "__widget__" => <id> }"
485       into the corresponding $WIDGET{<id>} object:
486
487          # 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
495          # 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
500             unless ($self->{id}) {
501                $self->{id} = ..get..some..id..;
502                $WIDGET{$self->{id}} = $self;
503             }
504
505             { __widget__ => $self->{id} }
506          }
507
508   shrink
509           $json = $json->shrink([$enable])
510
511           $enabled = $json->get_shrink
512
513       If $enable is true (or missing), the string returned by "encode" will
514       be shrunk (i.e. downgraded if possible).
515
516       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
519       If $enable is false, then JSON::PP does nothing.
520
521   max_depth
522           $json = $json->max_depth([$maximum_nesting_depth])
523
524           $max_depth = $json->get_max_depth
525
526       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
531       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
536       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
539       If no argument is given, the highest possible setting will be used,
540       which is rarely useful.
541
542       See "SECURITY CONSIDERATIONS" in JSON::XS for more info on why this is
543       useful.
544
545   max_size
546           $json = $json->max_size([$maximum_string_size])
547
548           $max_size = $json->get_max_size
549
550       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
556       If no argument is given, the limit check will be deactivated (same as
557       when 0 is specified).
558
559       See "SECURITY CONSIDERATIONS" in JSON::XS for more info on why this is
560       useful.
561
562   encode
563           $json_text = $json->encode($perl_scalar)
564
565       Converts the given Perl value or data structure to its JSON
566       representation. Croaks on error.
567
568   decode
569           $perl_scalar = $json->decode($json_text)
570
571       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
574   decode_prefix
575           ($perl_scalar, $characters) = $json->decode_prefix($json_text)
576
577       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
582       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
585          JSON::PP->new->decode_prefix ("[1] the tail")
586          => ([1], 3)
587

FLAGS FOR JSON::PP ONLY

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
595   allow_singlequote
596           $json = $json->allow_singlequote([$enable])
597           $enabled = $json->get_allow_singlequote
598
599       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
606       If $enable is false (the default), then "decode" will only accept valid
607       JSON texts.
608
609           $json->allow_singlequote->decode(qq|{"foo":'bar'}|);
610           $json->allow_singlequote->decode(qq|{'foo':"bar"}|);
611           $json->allow_singlequote->decode(qq|{'foo':'bar'}|);
612
613   allow_barekey
614           $json = $json->allow_barekey([$enable])
615           $enabled = $json->get_allow_barekey
616
617       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
624       If $enable is false (the default), then "decode" will only accept valid
625       JSON texts.
626
627           $json->allow_barekey->decode(qq|{foo:"bar"}|);
628
629   allow_bignum
630           $json = $json->allow_bignum([$enable])
631           $enabled = $json->get_allow_bignum
632
633       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
638          $json->allow_nonref->allow_bignum;
639          $bigfloat = $json->decode('2.000000000000000000000000001');
640          print $json->encode($bigfloat);
641          # => 2.000000000000000000000000001
642
643       See also MAPPING.
644
645   loose
646           $json = $json->loose([$enable])
647           $enabled = $json->get_loose
648
649       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
656       If $enable is false (the default), then "decode" will only accept valid
657       JSON texts.
658
659           $json->loose->decode(qq|["abc
660                                          def"]|);
661
662   escape_slash
663           $json = $json->escape_slash([$enable])
664           $enabled = $json->get_escape_slash
665
666       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
671       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
676       "decode" will not be affected in anyway.
677
678   indent_length
679           $json = $json->indent_length($number_of_spaces)
680           $length = $json->get_indent_length
681
682       This option is only useful when you also enable "indent" or "pretty".
683
684       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
691   sort_by
692           $json = $json->sort_by($code_ref)
693           $json = $json->sort_by($subroutine_name)
694
695       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
699       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
703       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
707       Example:
708
709          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
719       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
724          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

INCREMENTAL PARSING

731       This section is also taken from JSON::XS.
732
733       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
742       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
751       The following methods implement this incremental parser.
752
753   incr_parse
754           $json->incr_parse( [$string] ) # void context
755
756           $obj_or_undef = $json->incr_parse( [$string] ) # scalar context
757
758           @obj_or_empty = $json->incr_parse( [$string] ) # list context
759
760       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
764       If $string is given, then this string is appended to the already
765       existing JSON fragment stored in the $json object.
766
767       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
771       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
778       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
786       Example: Parse some JSON arrays/objects in a given string and return
787       them.
788
789           my @objs = JSON::PP->new->incr_parse ("[5][7][1,2]");
790
791   incr_text
792           $lvalue_string = $json->incr_text
793
794       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
802       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
806       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
810   incr_skip
811           $json->incr_skip
812
813       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
819       The difference to "incr_reset" is that only text until the parse error
820       occurred is removed.
821
822   incr_reset
823           $json->incr_reset
824
825       This completely resets the incremental parser, that is, after this
826       call, it will be as if the parser had never parsed anything.
827
828       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

MAPPING

833       Most of this section is also taken from JSON::XS.
834
835       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
840       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
844   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
850       array
851           A JSON array becomes a reference to an array in Perl.
852
853       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
858       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
866           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
873           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
879           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
884           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
889       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
895       null
896           A JSON null atom becomes "undef" in Perl.
897
898       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
903   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
908       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
918       array references
919           Perl array references become JSON arrays.
920
921       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
928              to_json [\0, JSON::PP::true]      # yields [false,true]
929
930       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
934       JSON::PP::null
935           This special value becomes JSON null.
936
937       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
942       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
949              # 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
954              # used as string, so dump as string
955              print $value;
956              encode_json [$value]                 # yields ["5"]
957
958              # undef becomes null
959              encode_json [undef]                  # yields [null]
960
961           You can force the type to be a string by stringifying it:
962
963              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
969           You can force the type to be a number by numifying it:
970
971              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
975           You cannot currently force the type in other, less obscure, ways.
976
977           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
984           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
999   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
1003       SERIALISATION
1004
1005       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
1009       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
1015           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
1019              sub URI::TO_JSON {
1020                 my ($uri) = @_;
1021                 $uri->as_string
1022              }
1023
1024       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
1028       3. "allow_blessed" is enabled.
1029           The object will be serialised as a JSON null value.
1030
1031       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

ENCODING/CODESET FLAG NOTES

1036       This section is taken from JSON::XS.
1037
1038       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
1042       "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
1048       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
1054       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
1061       "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
1070           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
1077       "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
1084           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
1088       "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
1093           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
1100           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
1104           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
1109           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
1115           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
1119           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
1123           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

SEE ALSO

1133       The json_pp command line utility for quick experiments.
1134
1135       JSON::XS, Cpanel::JSON::XS, and JSON::Tiny for faster alternatives.
1136       JSON and JSON::MaybeXS for easy migration.
1137
1138       JSON::PP::Compat5005 and JSON::PP::Compat5006 for older perl users.
1139
1140       RFC4627 (<http://www.ietf.org/rfc/rfc4627.txt>)
1141

AUTHOR

1143       Makamaka Hannyaharamitu, <makamaka[at]cpan.org>
1144
1146       Copyright 2007-2016 by Makamaka Hannyaharamitu
1147
1148       This library is free software; you can redistribute it and/or modify it
1149       under the same terms as Perl itself.
1150
1151
1152
1153perl v5.26.3                      2017-12-21                       JSON::PP(3)
Impressum