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

NAME

6       JSON::Parse - Parse JSON
7

SYNOPSIS

9           use JSON::Parse 'parse_json';
10           my $json = '["golden", "fleece"]';
11           my $perl = parse_json ($json);
12           # Same effect as $perl = ['golden', 'fleece'];
13
14       Convert JSON into Perl.
15

VERSION

17       This documents version 0.61 of JSON::Parse corresponding to git commit
18       033269fa8972fdce8626aa65cd11a5394ab50492
19       <https://github.com/benkasminbullock/JSON-
20       Parse/commit/033269fa8972fdce8626aa65cd11a5394ab50492> released on Thu
21       Feb 11 09:14:04 2021 +0900.
22

DESCRIPTION

24       A module for parsing JSON. (JSON means "JavaScript Object Notation" and
25       it is specified in "RFC 8259".)
26
27       JSON::Parse offers the function "parse_json", which takes a string
28       containing JSON, and returns an equivalent Perl structure. It also
29       offers validation of JSON via "valid_json", which returns true or false
30       depending on whether the JSON is correct or not, and
31       "assert_valid_json", which produces a descriptive fatal error if the
32       JSON is invalid. A function "read_json" reads JSON from a file, and
33       there is a safer version of "parse_json" called "parse_json_safe" which
34       doesn't throw exceptions.
35
36       For special cases of parsing, there are also methods "new" and "parse",
37       which create a JSON parsing object and run it on text. See "METHODS".
38
39       JSON::Parse accepts only UTF-8 as input. See "UTF-8 only" and "Handling
40       of Unicode".
41

FUNCTIONS

43   assert_valid_json
44           use JSON::Parse 'assert_valid_json';
45           eval {
46               assert_valid_json ('["xyz":"b"]');
47           };
48           if ($@) {
49               print "Your JSON was invalid: $@\n";
50           }
51           # Prints "Unexpected character ':' parsing array"
52
53       produces output
54
55           Your JSON was invalid: JSON error at line 1, byte 7/11: Unexpected character ':' parsing array starting from byte 1: expecting whitespace: 'n', '\r', '\t', ' ' or comma: ',' or end of array: ']' at /usr/home/ben/projects/json-parse/examples/assert.pl line 6.
56
57       (This example is included as assert.pl
58       <https://fastapi.metacpan.org/source/BKB/JSON-
59       Parse-0.61/examples/assert.pl> in the distribution.)
60
61       This is the underlying function for "valid_json". It runs at the same
62       speed, but it throws an error if the JSON is wrong, rather than
63       returning 1 or 0. See "DIAGNOSTICS" for the error format, which is
64       identical to "parse_json".
65
66       This cannot detect key collisions in the JSON since it does not store
67       values. See "Key collisions" for more on this module's handling of non-
68       unique names in the JSON.
69
70       The method equivalent to this is "check".
71
72       The behaviour of disallowing empty inputs was changed in version 0.49.
73
74   parse_json
75           use JSON::Parse 'parse_json';
76           my $perl = parse_json ('{"x":1, "y":2}');
77
78       This function converts JSON into a Perl structure, either an array
79       reference, a hash reference, or a scalar.
80
81       If the first argument does not contain a complete valid JSON text, is
82       the undefined value, an empty string, or a string containing only
83       whitespace "parse_json" throws a fatal error ("dies").
84
85       If the argument contains valid JSON, the return value is either a hash
86       reference, an array reference, or a scalar. If the input JSON text is a
87       serialized object, a hash reference is returned:
88
89           use JSON::Parse ':all';
90           my $perl = parse_json ('{"a":1, "b":2}');
91           print ref $perl, "\n";
92
93       produces output
94
95           HASH
96
97       (This example is included as hash.pl
98       <https://fastapi.metacpan.org/source/BKB/JSON-
99       Parse-0.61/examples/hash.pl> in the distribution.)
100
101       If the input JSON text is a serialized array, an array reference is
102       returned:
103
104           use JSON::Parse ':all';
105           my $perl = parse_json ('["a", "b", "c"]');
106           print ref $perl, "\n";
107
108       produces output
109
110           ARRAY
111
112       (This example is included as array.pl
113       <https://fastapi.metacpan.org/source/BKB/JSON-
114       Parse-0.61/examples/array.pl> in the distribution.)
115
116       Otherwise a Perl scalar is returned.
117
118       The behaviour of allowing a scalar was added in version 0.32 of this
119       module. This brings it into line with the new specification for JSON.
120       The behaviour of disallowing empty inputs was changed in version 0.49.
121
122       The function "parse_json_safe" offers a version of this function with
123       various safety features enabled. The method "parse" is equivalent to
124       this.
125
126   parse_json_safe
127       This is almost the same thing as "parse_json", but has the following
128       differences:
129
130       Does not throw exceptions
131           If the JSON is invalid, a warning is printed and the undefined
132           value is returned, as if calling "parse_json" like this:
133
134               eval {
135                   $out = parse_json ($json);
136               };
137               if ($@) {
138                   carp $@;
139                   $out = undef;
140               }
141
142       Detects key collisions
143           This switches on "detect_collisions", so that if the JSON contains
144           non-unique names, a warning is printed and the undefined value is
145           returned. See "Key collisions" for an explanation of what a key
146           collision is.
147
148       Booleans are not read-only
149           This switches on "copy_literals" so that JSON true, false and null
150           values are copied. These values can be modified, but they will not
151           be converted back into "true" and "false" by JSON::Create.
152
153       Errors are reported by carp
154           Parsing errors are reported by "carp" in Carp, so the error line
155           number refers to the caller's line.
156
157       As the name implies, this is meant to be a "safety-first" version of
158       "parse_json".
159
160       ๐ŸŽฒ This function was added in version 0.38.
161
162   read_json
163           use JSON::Parse 'read_json';
164           my $p = read_json ('filename');
165
166       This is exactly the same as "parse_json" except that it reads the JSON
167       from the specified file rather than a scalar. The file must be in the
168       UTF-8 encoding, and is opened as a character file using
169       ":encoding(utf8)" (see PerlIO::encoding and perluniintro). The output
170       is marked as character strings.
171
172       The method equivalent is "read".
173
174       This is a convenience function written in Perl. You may prefer to read
175       the file yourself using another module if you need faster performance.
176
177       This was renamed from "json_file_to_perl" in version 0.59. The old name
178       will also continue to work indefinitely.
179
180   valid_json
181           use JSON::Parse 'valid_json';
182           if (valid_json ($json)) {
183               # do something
184           }
185
186       "valid_json" returns 1 if its argument is valid JSON and 0 if not. It
187       runs several times faster than "parse_json". This gain in speed is
188       obtained because it discards the input data after reading it, rather
189       than storing it into Perl variables.
190
191       This does not supply the actual errors which caused invalidity. Use
192       "assert_valid_json" to get error messages when the JSON is invalid.
193
194       This cannot detect duplicate keys in JSON objects because it does not
195       store values. See "Key collisions" for more on this module's handling
196       of non-unique names in the JSON.
197

METHODS

199       If you need to parse JSON and you are not satisfied with the parsing
200       options offered by "parse_json" and "parse_json_safe", you can create a
201       JSON parsing object with "new" and set various options on the object,
202       then use it with "parse" or "read".
203
204       There are options to copy JSON literals ("true", "false", "null") with
205       "copy_literals", switch off fatal errors with "warn_only", detect
206       duplicate keys in objects with "detect_collisions", set the maximum
207       depth of nested objects and arrays with "set_max_depth", produce
208       machine-readable parsing errors with "diagnostics_hash", and set the
209       JSON literals to user defined values with the methods described under
210       "Methods for manipulating literals".
211
212       These methods only affect the object created with "new"; they do not
213       globally affect the behaviour of "parse_json" or "parse_json_safe".
214
215   check
216           eval {
217               $jp->check ($json);
218           };
219
220       This does the same thing as "assert_valid_json", except its behaviour
221       can be modified using the "diagnostics_hash" method.
222
223       ๐ŸŽฒ This method was added in version 0.48. This is for the benefit of
224       JSON::Repair.
225
226   copy_literals
227           $jp->copy_literals (1);
228
229       With a true value, copy JSON literal values ("null", "true", and
230       "false") into new Perl scalar values, and don't put read-only values
231       into the output.
232
233       With a false value, use read-only scalars:
234
235           $jp->copy_literals (0);
236
237       The "copy_literals (1)" behaviour is the behaviour of
238       "parse_json_safe". The "copy_literals (0)" behaviour is the behaviour
239       of "parse_json".
240
241       If the user also sets user-defined literals with "set_true",
242       "set_false" and "set_null", that takes precedence over this.
243
244       ๐ŸŽฒ This method was added in version 0.38.
245
246   detect_collisions
247           $jp->detect_collisions (1);
248
249       This switches on a check for hash key collisions (non-unique names in
250       JSON objects). If a collision is found, an error message "Name is not
251       unique" is printed, which also gives the non-unique name and the byte
252       position where the start of the colliding string was found:
253
254           use JSON::Parse;
255           my $jp = JSON::Parse->new ();
256           $jp->detect_collisions (1);
257           eval {
258               $jp->parse ('{"animals":{"cat":"moggy","cat":"feline","cat":"neko"}}');
259           };
260           print "$@\n" if $@;
261
262       produces output
263
264           JSON error at line 1, byte 28/55: Name is not unique: "cat" parsing object starting from byte 12 at /usr/home/ben/projects/json-parse/examples/../blib/lib/JSON/Parse.pm line 131.
265
266       (This example is included as collide.pl
267       <https://fastapi.metacpan.org/source/BKB/JSON-
268       Parse-0.61/examples/collide.pl> in the distribution.)
269
270       The "detect_collisions (1)" behaviour is the behaviour of
271       "parse_json_safe". The "detect_collisions (0)" behaviour is the
272       behaviour of "parse_json".
273
274       ๐ŸŽฒ This method was added in version 0.38.
275
276   diagnostics_hash
277           $jp->diagnostics_hash (1);
278
279       This changes diagnostics produced by errors from a simple string into a
280       hash reference containing various fields. This is incompatible with
281       "warn_only".
282
283       This replaces the previous experimental global variable
284       $json_diagnostics, which was removed from the module. The hash keys and
285       values are identical to those provided in the object returned by
286       $json_diagnostics, with the addition of a key "error as string" which
287       returns the usual error.
288
289       This requires Perl version 5.14 or later.
290
291       An example of the use of this method to "repair" broken JSON is in the
292       module "JSON::Repair".
293
294       ๐ŸŽฒ This method was added in version 0.46.
295
296   get_max_depth
297          my $max_depth = $jp->get_max_depth ();
298
299       This returns the maximum nesting depth of objects or arrays in the
300       input JSON. The default value is 10,000.
301
302       ๐ŸŽฒ This method was added in version 0.58.
303
304   new
305           my $jp = JSON::Parse->new ();
306
307       Create a new JSON::Parse object.
308
309       ๐ŸŽฒ This method was added in version 0.38.
310
311   parse
312           my $out = $jp->parse ($json);
313
314       This does the same thing as "parse_json", except its behaviour can be
315       modified using object methods.
316
317       ๐ŸŽฒ This method was added in version 0.38.
318
319       This was renamed from "run" in version 0.60.
320
321   read
322           my $json = $jp->read ($file);
323
324       Read a file, parse the contained JSON, and return the output. This
325       method is equivalent to the function "read_json".
326
327       ๐ŸŽฒ This method was added in version 0.60.
328
329   set_max_depth
330           $jp->set_max_depth (42);
331
332       Set the maximum nesting depth of objects or arrays in the input JSON.
333       The default value is 10,000.
334
335       ๐ŸŽฒ This method was added in version 0.58.
336
337   upgrade_utf8
338           $jp->upgrade_utf8 (1);
339
340       Upgrade input from bytes to characters automatically.
341
342       This can be switched off again using any false value:
343
344           $jp->upgrade_utf8 (0);
345
346       ๐ŸŽฒ This method was added in version 0.61.
347
348   warn_only
349           $jp->warn_only (1);
350
351       Warn, don't die, on error. Failed parsing returns the undefined value,
352       "undef", and prints a warning.
353
354       This can be switched off again using any false value:
355
356           $jp->warn_only ('');
357
358       ๐ŸŽฒ This method was added in version 0.41.
359
360   Methods for manipulating literals
361       These methods alter what is written into the Perl structure when the
362       parser sees a literal value, "true", "false" or "null" in the input
363       JSON.
364
365       This number of methods is needed because of the possibility that a user
366       wants to set the output for "false" to be "undef":
367
368           $jp->set_false (undef);
369
370       Thus, we cannot use a single function "$jp->false (undef)" to cover
371       both setting and deleting of values.
372
373       ๐ŸŽฒ This facility was added in version 0.38.
374
375       set_true
376
377           $jp->set_true ("Yes, that is so true");
378
379       Supply a scalar to be used in place of the JSON "true" literal.
380
381       This example puts the string "Yes, that is so true" into the hash or
382       array when we hit a "true" literal, rather than the default read-only
383       scalar:
384
385           use JSON::Parse;
386           my $json = '{"yes":true,"no":false}';
387           my $jp = JSON::Parse->new ();
388           $jp->set_true ('Yes, that is so true');
389           my $out = $jp->parse ($json);
390           print $out->{yes}, "\n";
391
392       prints
393
394           Yes, that is so true
395
396       To override the previous value, call it again with a new value. To
397       delete the value and revert to the default behaviour, use
398       "delete_true".
399
400       If you give this a value which is not "true", as in Perl will evaluate
401       it as a false in an if statement, it prints a warning "User-defined
402       value for JSON true evaluates as false".  You can switch this warning
403       off with "no_warn_literals".
404
405       ๐ŸŽฒ This method was added in version 0.38.
406
407       delete_true
408
409           $jp->delete_true ();
410
411       Delete the user-defined true value. See "set_true".
412
413       This method is "safe" in that it has absolutely no effect if no user-
414       defined value is in place. It does not return a value.
415
416       ๐ŸŽฒ This method was added in version 0.38.
417
418       set_false
419
420           $jp->set_false (JSON::PP::Boolean::false);
421
422       Supply a scalar to be used in place of the JSON "false" literal.
423
424       In the above example, when we hit a "false" literal, we put
425       "JSON::PP::Boolean::false" in the output, similar to JSON::PP and other
426       CPAN modules like Mojo::JSON or JSON::XS.
427
428       To override the previous value, call it again with a new value. To
429       delete the value and revert to the default behaviour, use
430       "delete_false".
431
432       If you give this a value which is not "false", as in Perl will evaluate
433       it as a false in an if statement, it prints a warning "User-defined
434       value for JSON false evaluates as true".  You can switch this warning
435       off with "no_warn_literals".
436
437       ๐ŸŽฒ This method was added in version 0.38.
438
439       delete_false
440
441           $jp->delete_false ();
442
443       Delete the user-defined false value. See "set_false".
444
445       This method is "safe" in that it has absolutely no effect if no user-
446       defined value is in place. It does not return a value.
447
448       ๐ŸŽฒ This method was added in version 0.38.
449
450       set_null
451
452           $jp->set_null (0);
453
454       Supply a scalar to be used in place of the JSON "null" literal.
455
456       To override the previous value, call it again with a new value. To
457       delete the value and revert to the default behaviour, use
458       "delete_null".
459
460       ๐ŸŽฒ This method was added in version 0.38.
461
462       delete_null
463
464           $jp->delete_null ();
465
466       Delete the user-defined null value. See "set_null".
467
468       This method is "safe" in that it has absolutely no effect if no user-
469       defined value is in place. It does not return a value.
470
471       ๐ŸŽฒ This method was added in version 0.38.
472
473       no_warn_literals
474
475           $jp->no_warn_literals (1);
476
477       Use a true value to switch off warnings about setting boolean values to
478       contradictory things. For example if you want to set the JSON "false"
479       literal to turn into the string "false",
480
481           $jp->no_warn_literals (1);
482           $jp->set_false ("false");
483
484       See also "Contradictory values for "true" and "false"".
485
486       This also switches off the warning "User-defined value overrules
487       copy_literals".
488
489       ๐ŸŽฒ This method was added in version 0.38.
490

OLD INTERFACE

492       The following alternative function names are accepted. These are the
493       names used for the functions in old versions of this module. These
494       names are not deprecated and will never be removed from the module.
495
496       The names ending in "_to_perl" seem quite silly in retrospect since
497       surely it is obvious that one is programming in Perl.
498
499   json_to_perl
500       This is exactly the same function as "parse_json".
501
502   json_file_to_perl
503       This is exactly the same function as "read_json". The function was
504       renamed in version 0.59, after the same function in
505       "File::JSON::Slurper".
506
507   run
508       This is the old name for "parse".
509
510   validate_json
511       This is exactly the same function as "assert_valid_json".
512

Mapping from JSON to Perl

514       JSON elements are mapped to Perl as follows:
515
516   JSON numbers
517       JSON numbers become Perl numbers, either integers or double-precision
518       floating point numbers, or possibly strings containing the number if
519       parsing of a number by the usual methods fails somehow.
520
521       JSON does not allow leading zeros, like 0123, or leading plus signs,
522       like +100, in numbers, so these cause an "Unexpected character" error.
523       JSON also does not allow numbers of the form 1., but it does allow
524       things like 0e0 or 1E999999. As far as possible these are accepted by
525       JSON::Parse.
526
527   JSON strings
528       JSON strings become Perl strings. The JSON escape characters such as
529       "\t" for the tab character (see section 2.5 of "RFC 8259") are mapped
530       to the equivalent ASCII character.
531
532       Handling of Unicode
533
534       Inputs must be in the UTF-8 format. See "UTF-8 only".
535
536       In addition, JSON::Parse rejects UTF-8 which encodes non-characters
537       such as "U+FFFF" and ill-formed characters such as incomplete halves of
538       surrogate pairs.
539
540       Unicode encoding points in the input of the form "\u3000" are converted
541       into the equivalent UTF-8 bytes.
542
543       Surrogate pairs in the form "\uD834\uDD1E" are also handled. If the
544       second half of the surrogate pair is missing, an "Unexpected character"
545       or "Unexpected end of input" error is thrown. If the second half of the
546       surrogate pair is present but contains an impossible value, a "Not
547       surrogate pair" error is thrown.
548
549       If the input to "parse_json" is marked as Unicode characters, the
550       output strings will be marked as Unicode characters. If the input is
551       not marked as Unicode characters, the output strings will not be marked
552       as Unicode characters. Thus,
553
554           use JSON::Parse ':all';
555           # The scalar $sasori looks like Unicode to Perl
556           use utf8;
557           my $sasori = '["่ "]';
558           my $p = parse_json ($sasori);
559           print utf8::is_utf8 ($p->[0]);
560           # Prints 1.
561
562       but
563
564           use JSON::Parse ':all';
565           # The scalar $ebi does not look like Unicode to Perl
566           no utf8;
567           my $ebi = '["ๆตท่€"]';
568           my $p = parse_json ($ebi);
569           print utf8::is_utf8 ($p->[0]);
570           # Prints nothing.
571
572       Escapes of the form \uXXXX (see page three of "RFC 8259") are mapped to
573       ASCII if XXXX is less than 0x80, or to UTF-8 if XXXX is greater than or
574       equal to 0x80.
575
576       Strings containing \uXXXX escapes greater than 0x80 are also upgraded
577       to character strings, regardless of whether the input is a character
578       string or a byte string, thus regardless of whether Perl thinks the
579       input string is Unicode, escapes like \u87f9 are converted into the
580       equivalent UTF-8 bytes and the particular string in which they occur is
581       marked as a character string:
582
583           use JSON::Parse ':all';
584           no utf8;
585           # ่Ÿน
586           my $kani = '["\u87f9"]';
587           my $p = parse_json ($kani);
588           print "It's marked as a character string" if utf8::is_utf8 ($p->[0]);
589           # Prints "It's marked as a character string" because it's upgraded
590           # regardless of the input string's flags.
591
592       This is modelled on the behaviour of Perl's "chr":
593
594           no utf8;
595           my $kani = '87f9';
596           print "hex is character string\n" if utf8::is_utf8 ($kani);
597           # prints nothing
598           $kani = chr (hex ($kani));
599           print "chr makes it a character string\n" if utf8::is_utf8 ($kani);
600           # prints "chr makes it a character string"
601
602       However, JSON::Parse also upgrades the remaining part of the string
603       into a character string, even when it's not marked as a character
604       string. For example,
605
606           use JSON::Parse ':all';
607           use Unicode::UTF8 'decode_utf8';
608           no utf8;
609           my $highbytes = "ใ‹";
610           my $not_utf8 = "$highbytes\\u3042";
611           my $test = "{\"a\":\"$not_utf8\"}";
612           my $out = parse_json ($test);
613           # JSON::Parse does something unusual here in promoting the first part
614           # of the string into UTF-8.
615           print "JSON::Parse gives this: ", $out->{a}, "\n";
616           # Perl cannot assume that $highbytes is in UTF-8, so it has to just
617           # turn the initial characters into garbage.
618           my $add_chr = $highbytes . chr (0x3042);
619           print "Perl's output is like this: ", $add_chr, "\n";
620           # In fact JSON::Parse's behaviour is equivalent to this:
621           my $equiv = decode_utf8 ($highbytes) . chr (0x3042);
622           print "JSON::Parse did something like this: ", $equiv, "\n";
623           # With character strings switched on, Perl and JSON::Parse do the same
624           # thing.
625           use utf8;
626           my $is_utf8 = "ใ‹";
627           my $test2 = "{\"a\":\"$is_utf8\\u3042\"}";
628           my $out2 = parse_json ($test2);
629           print "JSON::Parse: ", $out2->{a}, "\n";
630           my $add_chr2 = $is_utf8 . chr (0x3042);
631           print "Native Perl: ", $add_chr2, "\n";
632
633       produces output
634
635           JSON::Parse gives this: ใ‹ใ‚
636           Perl's output is like this: รฃยย‹ใ‚
637           JSON::Parse did something like this: ใ‹ใ‚
638           JSON::Parse: ใ‹ใ‚
639           Native Perl: ใ‹ใ‚
640
641       (This example is included as unicode-details.pl
642       <https://fastapi.metacpan.org/source/BKB/JSON-
643       Parse-0.61/examples/unicode-details.pl> in the distribution.)
644
645       Although in general the above would be an unsafe practice, JSON::Parse
646       can do things this way because JSON is a text-only, Unicode-only
647       format. To ensure that invalid inputs are never upgraded, JSON::Parse
648       checks each input byte to make sure that it forms UTF-8. See also
649       "UTF-8 only". Doing things this way, rather than the way that Perl does
650       it, was one of the original motivations for writing this module.
651
652   JSON arrays
653       JSON arrays become Perl array references. The elements of the Perl
654       array are in the same order as they appear in the JSON.
655
656       Thus
657
658           my $p = parse_json ('["monday", "tuesday", "wednesday"]');
659
660       has the same result as a Perl declaration of the form
661
662           my $p = [ 'monday', 'tuesday', 'wednesday' ];
663
664   JSON objects
665       JSON objects become Perl hashes. The members of the JSON object become
666       key and value pairs in the Perl hash. The string part of each object
667       member becomes the key of the Perl hash. The value part of each member
668       is mapped to the value of the Perl hash.
669
670       Thus
671
672           my $j = <<EOF;
673           {"monday":["blue", "black"],
674            "tuesday":["grey", "heart attack"],
675            "friday":"Gotta get down on Friday"}
676           EOF
677
678           my $p = parse_json ($j);
679
680       has the same result as a Perl declaration of the form
681
682           my $p = {
683               monday => ['blue', 'black'],
684               tuesday => ['grey', 'heart attack'],
685               friday => 'Gotta get down on Friday',
686           };
687
688       Key collisions
689
690       A key collision is something like the following.
691
692           use JSON::Parse qw/parse_json parse_json_safe/;
693           my $j = '{"a":1, "a":2}';
694           my $p = parse_json ($j);
695           print "Ambiguous key 'a' is ", $p->{a}, "\n";
696           my $q = parse_json_safe ($j);
697
698       produces output
699
700           JSON::Parse::parse_json_safe: Name is not unique: "a" parsing object starting from byte 1 at /usr/home/ben/projects/json-parse/examples/key-collision.pl line 8.
701           Ambiguous key 'a' is 2
702
703       (This example is included as key-collision.pl
704       <https://fastapi.metacpan.org/source/BKB/JSON-Parse-0.61/examples/key-
705       collision.pl> in the distribution.)
706
707       Here the key "a" could be either 1 or 2. As seen in the example,
708       "parse_json" overwrites the first value with the second value.
709       "parse_json_safe" halts and prints a warning. If you use "new" you can
710       switch key collision on and off with the "detect_collisions" method.
711
712       The rationale for "parse_json" not to give warnings is that Perl
713       doesn't give information about collisions when storing into hash
714       values, and checking for collisions for every key will degrade
715       performance for the sake of an unlikely occurrence. The JSON
716       specification says "The names within an object SHOULD be unique." (see
717       "RFC 8259", page 5), although it's not a requirement.
718
719       For performance, "valid_json" and "assert_valid_json" do not store hash
720       keys, thus they cannot detect this variety of problem.
721
722   Literals
723       false
724
725       "parse_json" maps the JSON false literal to a readonly scalar which
726       evaluates to the empty string, or to zero in a numeric context. (This
727       behaviour changed from version 0.36 to 0.37. In versions up to 0.36,
728       the false literal was mapped to a readonly scalar which evaluated to 0
729       only.) "parse_json_safe" maps the JSON literal to a similar scalar
730       without the readonly constraints. If you use a parser created with
731       "new", you can choose either of these behaviours with "copy_literals",
732       or you can tell JSON::Parse to put your own value in place of falses
733       using the "set_false" method.
734
735       null
736
737       "parse_json" maps the JSON null literal to a readonly scalar
738       $JSON::Parse::null which evaluates to "undef". "parse_json_safe" maps
739       the JSON literal to the undefined value. If you use a parser created
740       with "new", you can choose either of these behaviours with
741       "copy_literals", or you can tell JSON::Parse to put your own value in
742       place of nulls using the "set_null" method.
743
744       true
745
746       "parse_json" maps the JSON true literal to a readonly scalar which
747       evaluates to 1. "parse_json_safe" maps the JSON literal to the value 1.
748       If you use a parser created with "new", you can choose either of these
749       behaviours with "copy_literals", or you can tell JSON::Parse to put
750       your own value in place of trues using the "set_true" method.
751
752       Round trips and compatibility
753
754       The Perl versions of literals produced by "parse_json" will be
755       converted back to JSON literals if you use "create_json" in
756       JSON::Create. However, JSON::Parse's literals are incompatible with the
757       other CPAN JSON modules. For compatibility with other CPAN modules,
758       create a JSON::Parse object with "new", and set JSON::Parse's literals
759       with "set_true", "set_false", and "set_null".
760
761       A round trip with JSON::Tiny
762
763       This example demonstrates round-trip compatibility using JSON::Tiny,
764       version 0.58:
765
766           use utf8;
767           use JSON::Tiny '0.58', qw(decode_json encode_json);
768           use JSON::Parse;
769           use JSON::Create;
770           my $cream = '{"clapton":true,"hendrix":false}';
771           my $jp = JSON::Parse->new ();
772           my $jc = JSON::Create->new (sort => 1);
773
774           print "First do a round-trip of our modules:\n\n";
775           print $jc->create ($jp->parse ($cream)), "\n\n";
776
777           print "Now do a round-trip of JSON::Tiny:\n\n";
778           print encode_json (decode_json ($cream)), "\n\n";
779
780           print "๐Ÿฅด First, incompatible mode:\n\n";
781           print 'tiny(parse): ', encode_json ($jp->parse ($cream)), "\n";
782           print 'create(tiny): ', $jc->create (decode_json ($cream)), "\n\n";
783
784           # Set our parser to produce these things as literals:
785           $jp->set_true (JSON::Tiny::true);
786           $jp->set_false (JSON::Tiny::false);
787
788           print "๐Ÿ”„ Compatibility with JSON::Parse:\n\n";
789           print 'tiny(parse):', encode_json ($jp->parse ($cream)), "\n\n";
790           $jc->bool ('JSON::Tiny::_Bool');
791
792           print "๐Ÿ”„ Compatibility with JSON::Create:\n\n";
793           print 'create(tiny):', $jc->create (decode_json ($cream)), "\n\n";
794
795           print "๐Ÿ”„ JSON::Parse and JSON::Create are still compatible too:\n\n";
796           print $jc->create ($jp->parse ($cream)), "\n";
797
798       produces output
799
800           First do a round-trip of our modules:
801
802           {"clapton":true,"hendrix":false}
803
804           Now do a round-trip of JSON::Tiny:
805
806           {"clapton":true,"hendrix":false}
807
808           ๐Ÿฅด First, incompatible mode:
809
810           tiny(parse): {"clapton":1,"hendrix":""}
811           create(tiny): {"clapton":1,"hendrix":0}
812
813           ๐Ÿ”„ Compatibility with JSON::Parse:
814
815           tiny(parse):{"clapton":true,"hendrix":false}
816
817           ๐Ÿ”„ Compatibility with JSON::Create:
818
819           create(tiny):{"clapton":true,"hendrix":false}
820
821           ๐Ÿ”„ JSON::Parse and JSON::Create are still compatible too:
822
823           {"clapton":true,"hendrix":false}
824
825       (This example is included as json-tiny-round-trip-demo.pl
826       <https://fastapi.metacpan.org/source/BKB/JSON-Parse-0.61/examples/json-
827       tiny-round-trip-demo.pl> in the distribution.)
828
829       Most of the other CPAN modules use similar methods to JSON::Tiny, so
830       the above example can easily be adapted. See also "Interoperability" in
831       JSON::Create for various examples.
832
833       Modifying the values
834
835       "parse_json" maps all the literals to read-only values. Because of
836       this, attempting to modifying the boolean values in the hash reference
837       returned by "parse_json" will cause "Modification of a read-only value
838       attempted" errors:
839
840           my $in = '{"hocus":true,"pocus":false,"focus":null}';
841           my $p = json_parse ($in);
842           $p->{hocus} = 99;
843           # "Modification of a read-only value attempted" error occurs
844
845       Since the hash values are read-only scalars, "$p->{hocus} = 99" is like
846       this:
847
848           undef = 99;
849
850       If you need to modify the returned hash reference, then delete the
851       value first:
852
853           my $in = '{"hocus":true,"pocus":false,"focus":null}';
854           my $p = json_parse ($in);
855           delete $p->{pocus};
856           $p->{pocus} = 99;
857           # OK
858
859       Similarly with array references, delete the value before altering:
860
861           my $in = '[true,false,null]';
862           my $q = json_parse ($in);
863           delete $q->[1];
864           $q->[1] = 'magic';
865
866       Note that the return values from parsing bare literals are not read-
867       only scalars, so
868
869           my $true = JSON::Parse::json_parse ('true');
870           $true = 99;
871
872       produces no error. This is because Perl copies the scalar.
873

RESTRICTIONS

875       This module imposes the following restrictions on its input.
876
877       JSON only
878           JSON::Parse is a strict parser. It only accepts input which exactly
879           meets the criteria of "RFC 8259". That means, for example,
880           JSON::Parse does not accept single quotes (') instead of double
881           quotes ("), or numbers with leading zeros, like 0123. JSON::Parse
882           does not accept control characters (0x00 - 0x1F) in strings,
883           missing commas between array or hash elements like "["a" "b"]", or
884           trailing commas like "["a","b","c",]". It also does not accept
885           trailing non-whitespace, like the second "]" in "["a"]]".
886
887           You may find "JSON::Repair" by the same authors as JSON::Parse
888           useful if you need to process JSON-like text with tolerance for
889           errors.
890
891       No incremental parsing
892           JSON::Parse does not parse incrementally. It only parses fully-
893           formed JSON strings which include all opening and closing brackets.
894           This is an inherent part of the design of the module. Incremental
895           parsing in the style of XML::Parser would require some kind of
896           callback structure to deal with the elements of the partially
897           digested structures, but JSON::Parse was never designed to do this;
898           it merely converts what it sees into a Perl structure. Claims to
899           offer incremental JSON parsing in other modules' documentation
900           should be diligently verified.
901
902       UTF-8 only
903           JSON::Parse only parses the UTF-8 format. If input is in a
904           different Unicode encoding than UTF-8, convert the input before
905           handing it to this module. For example, for the UTF-16 format,
906
907               use Encode 'decode';
908               my $input_utf8 = decode ('UTF-16', $input);
909               my $perl = parse_json ($input_utf8);
910
911           or, for a file, use ":encoding" (see PerlIO::encoding and
912           perluniintro):
913
914               open my $input, "<:encoding(UTF-16)", 'some-json-file';
915
916           JSON::Parse does not try to determine the nature of the octet
917           stream using BOM markers. A BOM marker in the input consists of
918           bytes 0xFE and 0xFF, both of which are invalid as UTF-8, and thus
919           will cause a fatal error.
920
921           This restriction to UTF-8 applies regardless of whether Perl thinks
922           that the input string is a character string or a byte string.
923           Non-UTF-8 input will cause an "Unexpected character" error.
924
925           The latest specification for JSON, "RFC 8259", specifies it to be a
926           UTF-8 only format.
927
928           JSON::Parse does not accept Unicode non-characters (U+FFFF, UFDDO,
929           etc.), UTF-8 representing surrogate pair code points, or bytes
930           outside the range of Unicode code points as UTF-8 bytes.
931

DIAGNOSTICS

933       "valid_json" does not produce error messages. "parse_json" and
934       "assert_valid_json" die on encountering invalid input.
935       "parse_json_safe" uses "carp" in Carp to pass error messages as
936       warnings.
937
938       Error messages have the line number, and the byte number where
939       appropriate, of the input which caused the problem. The line number is
940       formed simply by counting the number of "\n" (linefeed, ASCII 0x0A)
941       characters in the whitespace part of the JSON.
942
943       In "parse_json" and "assert_valid_json", parsing errors are fatal, so
944       to continue after an error occurs, put the parsing into an "eval"
945       block:
946
947           my $p;
948           eval {
949               $p = parse_json ($j);
950           };
951           if ($@) {
952               # handle error
953           }
954
955       The following error messages are produced:
956
957       Unexpected character
958           An unexpected character (byte) was encountered in the input. For
959           example, when looking at the beginning of a string supposedly
960           containing JSON, if the module encounters a plus sign, it will give
961           an error like this:
962
963               assert_valid_json ('+');
964
965           gives output
966
967               JSON error at line 1, byte 1/1: Unexpected character '+' parsing initial state: expecting whitespace: 'n', '\r', '\t', ' ' or start of string: '"' or digit: '0-9' or minus: '-' or start of an array or object: '{', '[' or start of literal: 't', 'f', 'n'
968
969           The message always includes a list of what characters are allowed.
970
971           If there is some recognizable structure being parsed, the error
972           message will include its starting point in the form "starting from
973           byte n":
974
975               assert_valid_json ('{"this":"\a"}');
976
977           gives output
978
979               JSON error at line 1, byte 11/13: Unexpected character 'a' parsing string starting from byte 9: expecting escape: '', '/', '"', 'b', 'f', 'n', 'r', 't', 'u'
980
981           A feature of JSON is that parsing it requires only one byte to be
982           examined at a time. Thus almost all parsing problems can be handled
983           using the "Unexpected character" error type, including spelling
984           errors in literals:
985
986               assert_valid_json ('[true,folse]');
987
988           gives output
989
990               JSON error at line 1, byte 8/12: Unexpected character 'o' parsing literal starting from byte 7: expecting 'a'
991
992           and the missing second half of a surrogate pair:
993
994               assert_valid_json ('["\udc00? <-- should be a second half here"]');
995
996           gives output
997
998               JSON error at line 1, byte 9/44: Unexpected character '?' parsing unicode escape starting from byte 3: expecting '\'
999
1000           All kinds of errors can occur parsing numbers, for example a
1001           missing fraction,
1002
1003               assert_valid_json ('[1.e9]');
1004
1005           gives output
1006
1007               JSON error at line 1, byte 4/6: Unexpected character 'e' parsing number starting from byte 2: expecting digit: '0-9'
1008
1009           and a leading zero,
1010
1011               assert_valid_json ('[0123]');
1012
1013           gives output
1014
1015               JSON error at line 1, byte 3/6: Unexpected character '1' parsing number starting from byte 2: expecting whitespace: 'n', '\r', '\t', ' ' or comma: ',' or end of array: ']' or dot: '.' or exponential sign: 'e', 'E'
1016
1017           The error message is this complicated because all of the following
1018           are valid here: whitespace: "[0 ]"; comma: "[0,1]", end of array:
1019           "[0]", dot: "[0.1]", or exponential: "[0e0]".
1020
1021           These are all handled by this error.  Thus the error messages are a
1022           little confusing as diagnostics.
1023
1024           Versions of this module prior to 0.29 gave more informative
1025           messages like "leading zero in number". (The messages weren't
1026           documented.) The reason to change over to the single message was
1027           because it makes the parsing code simpler, and because the testing
1028           code described in "TESTING" makes use of the internals of this
1029           error to check that the error message produced actually do
1030           correspond to the invalid and valid bytes allowed by the parser, at
1031           the exact byte given.
1032
1033           This is a bytewise error, thus for example if a miscoded UTF-8
1034           appears in the input, an error message saying what bytes would be
1035           valid at that point will be printed.
1036
1037               no utf8;
1038               use JSON::Parse 'assert_valid_json';
1039
1040               # Error in first byte:
1041
1042               my $bad_utf8_1 = chr (hex ("81"));
1043               eval { assert_valid_json ("[\"$bad_utf8_1\"]"); };
1044               print "$@\n";
1045
1046               # Error in third byte:
1047
1048               my $bad_utf8_2 = chr (hex ('e2')) . chr (hex ('9C')) . 'b';
1049               eval { assert_valid_json ("[\"$bad_utf8_2\"]"); };
1050               print "$@\n";
1051
1052           prints
1053
1054               JSON error at line 1, byte 3/5: Unexpected character 0x81 parsing string starting from byte 2: expecting printable ASCII or first byte of UTF-8: '\x20-\x7f', '\xC2-\xF4' at examples/bad-utf8.pl line 10.
1055
1056               JSON error at line 1, byte 5/7: Unexpected character 'b' parsing string starting from byte 2: expecting bytes in range 80-bf: '\x80-\xbf' at examples/bad-utf8.pl line 16.
1057
1058       Unexpected end of input
1059           The end of the string was encountered before the end of whatever
1060           was being parsed was. For example, if a quote is missing from the
1061           end of the string, it will give an error like this:
1062
1063               assert_valid_json ('{"first":"Suzuki","second":"Murakami","third":"Asada}');
1064
1065           gives output
1066
1067               JSON error at line 1: Unexpected end of input parsing string starting from byte 47
1068
1069       Not surrogate pair
1070           While parsing a string, a surrogate pair was encountered. While
1071           trying to turn this into UTF-8, the second half of the surrogate
1072           pair turned out to be an invalid value.
1073
1074               assert_valid_json ('["\uDC00\uABCD"]');
1075
1076           gives output
1077
1078               JSON error at line 1: Not surrogate pair parsing unicode escape starting from byte 11
1079
1080       Empty input
1081           This error occurs for an input which is an empty (no length or
1082           whitespace only) or an undefined value.
1083
1084               assert_valid_json ('');
1085
1086           gives output
1087
1088               JSON error: Empty input parsing initial state
1089
1090           Prior to version 0.49, this error was produced by
1091           "assert_valid_json" only, but it is now also produced by
1092           "parse_json".
1093
1094       Name is not unique
1095           This error occurs when parsing JSON when the user has chosen
1096           "detect_collisions". For example an input like
1097
1098               my $p = JSON::Parse->new ();
1099               $p->detect_collisions (1);
1100               $p->run ('{"hocus":1,"pocus":2,"hocus":3}');
1101
1102           gives output
1103
1104               JSON error at line 1, byte 23/31: Name is not unique: "hocus" parsing object starting from byte 1 at blib/lib/JSON/Parse.pm line 131.
1105
1106           where the JSON object has two keys with the same name, "hocus". The
1107           terminology "name is not unique" is from the JSON specification.
1108
1109       Contradictory values for "true" and "false"
1110           User-defined value for JSON false evaluates as true
1111               This happens if you set JSON false to map to a true value:
1112
1113                   $jp->set_false (1);
1114
1115               To switch off this warning, use "no_warn_literals".
1116
1117               ๐ŸŽฒ This warning was added in version 0.38.
1118
1119           User-defined value for JSON true evaluates as false
1120               This happens if you set JSON true to map to a false value:
1121
1122                   $jp->set_true (undef);
1123
1124               To switch off this warning, use "no_warn_literals".
1125
1126               ๐ŸŽฒ This warning was added in version 0.38.
1127
1128           User-defined value overrules copy_literals
1129               This warning is given if you set up literals with
1130               "copy_literals" then you also set up your own true, false, or
1131               null values with "set_true", "set_false", or "set_null".
1132
1133               ๐ŸŽฒ This warning was added in version 0.38.
1134

PERFORMANCE

1136       On the author's computer, the module's speed of parsing is
1137       approximately the same as JSON::XS, with small variations depending on
1138       the type of input. For validation, "valid_json" is faster than any
1139       other module known to the author, and up to ten times faster than
1140       JSON::XS.
1141
1142       Some special types of input, such as floating point numbers containing
1143       an exponential part, like "1e09", seem to be about two or three times
1144       faster to parse with this module than with JSON::XS. In JSON::Parse,
1145       parsing of exponentials is done by the system's "strtod" function, but
1146       JSON::XS contains its own parser for exponentials, so these results may
1147       be system-dependent.
1148
1149       At the moment the main place JSON::XS wins over JSON::Parse is in
1150       strings containing escape characters, where JSON::XS is about 10%
1151       faster on the module author's computer and compiler. As of version
1152       0.33, despite some progress in improving JSON::Parse, I haven't been
1153       able to fully work out the reason behind the better speed.
1154
1155       There is some benchmarking code in the github repository under the
1156       directory "benchmarks" for those wishing to test these claims. The
1157       script benchmarks/bench <https://github.com/benkasminbullock/JSON-
1158       Parse/033269fa8972fdce8626aa65cd11a5394ab50492/benchmarks/bench> is an
1159       adaptation of the similar script in the JSON::XS distribution. The
1160       script benchmarks/pub-bench.pl
1161       <https://github.com/benkasminbullock/JSON-
1162       Parse/033269fa8972fdce8626aa65cd11a5394ab50492/benchmarks/pub-bench.pl>
1163       runs the benchmarks and prints them out as POD.
1164
1165       The following benchmark tests used version 0.58_01 of JSON::Parse,
1166       version 4.03 of "JSON::XS", and version 4.25 of "Cpanel::JSON::XS" on
1167       Perl version v5.32.0 compiled with Clang version FreeBSD clang version
1168       10.0.1 on FreeBSD 12.2. The files in the "benchmarks" directory of
1169       JSON::Parse. short.json and long.json are the benchmarks used by
1170       "JSON::XS".
1171
1172       short.json
1173               Repetitions: 10 x 100 = 1000
1174               --------------+------------+------------+
1175               module        |      1/min |        min |
1176               --------------|------------|------------|
1177               Cpanel        | 313007.761 |  0.0000319 |
1178               JP::valid     | 838860.800 |  0.0000119 |
1179               JSON::Parse   | 310689.185 |  0.0000322 |
1180               JSON::XS      | 303935.072 |  0.0000329 |
1181               --------------+------------+------------+
1182
1183       long.json
1184               Repetitions: 10 x 100 = 1000
1185               --------------+------------+------------+
1186               module        |      1/min |        min |
1187               --------------|------------|------------|
1188               Cpanel        |   5611.860 |  0.0017819 |
1189               JP::valid     |  13586.991 |  0.0007360 |
1190               JSON::Parse   |   4924.048 |  0.0020308 |
1191               JSON::XS      |   6406.452 |  0.0015609 |
1192               --------------+------------+------------+
1193
1194       words-array.json
1195               Repetitions: 10 x 100 = 1000
1196               --------------+------------+------------+
1197               module        |      1/min |        min |
1198               --------------|------------|------------|
1199               Cpanel        |  34749.826 |  0.0002878 |
1200               JP::valid     | 270600.258 |  0.0000370 |
1201               JSON::Parse   |  34017.064 |  0.0002940 |
1202               JSON::XS      |  35726.610 |  0.0002799 |
1203               --------------+------------+------------+
1204
1205       exp.json
1206               Repetitions: 10 x 100 = 1000
1207               --------------+------------+------------+
1208               module        |      1/min |        min |
1209               --------------|------------|------------|
1210               Cpanel        |  46759.242 |  0.0002139 |
1211               JP::valid     | 117817.528 |  0.0000849 |
1212               JSON::Parse   |  46759.242 |  0.0002139 |
1213               JSON::XS      |  19195.899 |  0.0005209 |
1214               --------------+------------+------------+
1215
1216       literals.json
1217               Repetitions: 10 x 100 = 1000
1218               --------------+------------+------------+
1219               module        |      1/min |        min |
1220               --------------|------------|------------|
1221               Cpanel        |  33026.016 |  0.0003028 |
1222               JP::valid     | 384798.532 |  0.0000260 |
1223               JSON::Parse   |  40840.351 |  0.0002449 |
1224               JSON::XS      |  33689.189 |  0.0002968 |
1225               --------------+------------+------------+
1226
1227       cpantesters.json
1228               Repetitions: 10 x 100 = 1000
1229               --------------+------------+------------+
1230               module        |      1/min |        min |
1231               --------------|------------|------------|
1232               Cpanel        |    212.377 |  0.0470860 |
1233               JP::valid     |   1309.043 |  0.0076392 |
1234               JSON::Parse   |    207.491 |  0.0481949 |
1235               JSON::XS      |    226.439 |  0.0441620 |
1236               --------------+------------+------------+
1237

SEE ALSO

1239       RFC 8259
1240           JSON is specified in RFC 8259 "The JavaScript Object Notation
1241           (JSON) Data Interchange Format"
1242           <http://www.ietf.org/rfc/rfc8259.txt>.
1243
1244       json.org
1245           <https://json.org> is the website for JSON, authored by Douglas
1246           Crockford.
1247
1248   Other CPAN modules for parsing and producing JSON
1249       The โญ represents the number of votes this module has received on
1250       metacpan, on a logarithmic scale. Modules which we recommend are marked
1251       with ๐Ÿ‘. Deprecated modules and modules which are definitely buggy (bug
1252       reports/pull requests ignored) and abandoned (no releases for several
1253       years) are marked with ๐Ÿ‘Ž and/or ๐Ÿ›. Modules we can't work out are
1254       marked with ๐Ÿ˜•.
1255
1256       Modules by the same author
1257           JSON::Create
1258               ๐Ÿ‘ JSON::Create is a companion module to JSON::Parse by the
1259               same author.
1260
1261           JSON::Repair
1262               JSON::Repair is an example module which demonstrates using
1263               JSON::Parse to apply some kinds of heuristics to repair
1264               "relaxed JSON" or otherwise broken JSON into compliant JSON.
1265
1266           JSON::Server
1267               JSON::Server is a module which offers a JSON-only, UTF-8 only
1268               server using "JSON::Parse" and "JSON::Create".
1269
1270           JSON::Tokenize
1271               JSON::Tokenize is part of the JSON::Parse distribution, a
1272               tokenizer which reduces a JSON string to tokens. This makes the
1273               JSON::Parse tokenizer available to people who want to write
1274               their own JSON parsers.
1275
1276           JSON::Whitespace
1277               JSON::Whitespace is for manipulating the "insignificant
1278               whitespace" part of JSON.
1279
1280       Reading and writing JSON
1281           Cpanel::JSON::XS
1282               [โญโญ Author: RURBAN <https://metacpan.org/author/RURBAN>;
1283               Date: "2020-10-28"; Version: 4.25]
1284
1285               This is a fork of JSON::XS. Please see the module for details
1286               about the reasons for the fork.
1287
1288           File::JSON::Slurper
1289               [โญ Author: NEILB <https://metacpan.org/author/NEILB>; Date:
1290               "2020-11-18"; Version: 1.00]
1291
1292               Slurp a JSON file into a data structure, and the reverse. It
1293               relies on "JSON::MaybeXS".
1294
1295           Glib::JSON
1296               [โญ Author: EBASSI <https://metacpan.org/author/EBASSI>; Date:
1297               "2015-04-19"; Version: 0.002]
1298
1299               Uses the JSON library from Glib, a library of C functions for
1300               the Linux GNOME desktop project, so it is independent of the
1301               other CPAN modules. Judging from the fairly sparse
1302               documentation, it seems to be a module where you build the JSON
1303               on the fly rather than converting a Perl structure wholesale
1304               into JSON.
1305
1306           JSON
1307               [โญโญ Author: ISHIGAKI <https://metacpan.org/author/ISHIGAKI>;
1308               Date: "2021-01-24"; Version: 4.03]
1309
1310               This calls on either JSON::PP or JSON::XS.
1311
1312           JSON::DWIW
1313               [Author: DOWENS <https://metacpan.org/author/DOWENS>; Date:
1314               "2010-09-29"; Version: 0.47]
1315
1316               ๐Ÿ‘Ž๐Ÿ› This module "Does What I Want", where "I" refers to the
1317               module's author. Development seems to have ceased in 2010,
1318               there is a long list of unfixed bugs, and some of the module's
1319               features seem to predate Unicode support in Perl. It is written
1320               in XS, and it claims to accept a wide variety of non-JSON
1321               formats such as comments, single-quoted strings, trailing
1322               commas, etc.
1323
1324           JSON::PP
1325               [โญโญ Author: ISHIGAKI <https://metacpan.org/author/ISHIGAKI>;
1326               Date: "2021-01-23"; Version: 4.06]
1327
1328               This is part of the Perl core, installed when you install Perl.
1329               "PP" stands for "Pure Perl", which means it is in Perl-only
1330               without the XS (C-based) parsing. This is slower but may be
1331               necessary if you cannot install modules requiring a C compiler.
1332
1333           JSON::Slurper
1334               [โญ Author: SRCHULO <https://metacpan.org/author/SRCHULO>;
1335               Date: "2019-10-30"; Version: 0.12]
1336
1337               Convenient file slurping and spurting of data using JSON. Uses
1338               "JSON::PP" or "Cpanel::JSON::XS" if available. The basic idea
1339               seems to be that it uses context to return arrays or hashes as
1340               required, and read and write files without extra stages of
1341               opening and closing the file.
1342
1343           JSON::Syck
1344               [โญโญ Author: TODDR <https://metacpan.org/author/TODDR>; Date:
1345               "2020-10-26"; Version: 1.34]
1346
1347               ๐Ÿ‘Ž๐Ÿ› Takes advantage of a similarity between YAML (yet another
1348               markup language) and JSON to provide a JSON parser/producer
1349               using YAML::Syck.
1350
1351               We have never tried this module, but it seems to be semi-
1352               deprecated (the ABSTRACT says "consider using JSON::XS
1353               instead!")  and there are a lot of bug reports
1354               <https://github.com/toddr/YAML-Syck/issues> about things like
1355               failing to process equals signs. However, the maintainer is
1356               fixing some of the bugs and making new releases, so we're not
1357               really sure.
1358
1359           JSON::Tiny
1360               [โญโญ Author: DAVIDO <https://metacpan.org/author/DAVIDO>;
1361               Date: "2017-11-12"; Version: 0.58]
1362
1363               This is a fork of "Mojo::JSON".
1364
1365           JSON::XS
1366               [โญโญโญ Author: MLEHMANN
1367               <https://metacpan.org/author/MLEHMANN>; Date: "2020-10-27";
1368               Version: 4.03]
1369
1370               This is an all-purpose JSON module in XS, which means it
1371               requires a C compiler to install.
1372
1373           JSON::YAJL
1374               [โญ Author: LBROCARD <https://metacpan.org/author/LBROCARD>;
1375               Date: "2011-08-05"; Version: 0.10]
1376
1377               ๐Ÿ‘Ž๐Ÿ› Wraps a C library called yajl. The module has been
1378               abandoned since ten years ago. Bug reports include serious
1379               errors, and pull requests have been ignored.
1380
1381           Mojo::JSON
1382               [โญโญโญ Author: SRI <https://metacpan.org/author/SRI>; Date:
1383               "2021-01-17"; Version: 8.71]
1384
1385               Part of the Mojolicious standalone web framework, "pure Perl"
1386               JSON reader/writer. As of version 8.70 of Mojolicious, this
1387               actually depends on "JSON::PP" but will load "Cpanel::JSON::XS"
1388               if it is available.
1389
1390       Combination modules
1391           These modules rely on more than one back-end module to process JSON
1392           for you.
1393
1394           JSON::Any
1395               [โญ Author: ETHER <https://metacpan.org/author/ETHER>; Date:
1396               "2015-06-10"; Version: 1.39]
1397
1398               ๐Ÿ‘Ž This now-deprecated module combines "JSON::DWIW", "JSON::XS"
1399               versions one and two, and "JSON::Syck".
1400
1401           JSON::MaybeXS
1402               [โญโญ Author: ETHER <https://metacpan.org/author/ETHER>; Date:
1403               "2020-11-13"; Version: 1.004003]
1404
1405               A module which combines "Cpanel::JSON::XS", "JSON::XS", and
1406               "JSON::PP". The original "JSON" combines "JSON::XS" and
1407               "JSON::PP", but this prioritizes "Cpanel::JSON::XS" over
1408               "JSON::XS".
1409
1410           JSON::XS::VersionOneAndTwo
1411               [Author: LBROCARD <https://metacpan.org/author/LBROCARD>; Date:
1412               "2008-02-13"; Version: 0.31]
1413
1414               ๐Ÿ‘Ž A "combination module" which supports two different
1415               interfaces of "JSON::XS". However, JSON::XS is now onto version
1416               4.
1417
1418           Mojo::JSON::MaybeXS
1419               [โญ Author: DBOOK <https://metacpan.org/author/DBOOK>; Date:
1420               "2019-08-07"; Version: 1.002]
1421
1422               ๐Ÿ‘Ž This pulls in "JSON::MaybeXS" instead of "Mojo::JSON" for
1423               Mojolicious users. It seems to have been rendered obsolete by
1424               modern versions of Mojolicious due to changes to make that
1425               depend on "Cpanel::JSON::XS" if available.
1426
1427       Test-related modules
1428           Test2::Tools::JSON
1429               [Author: AKIYM <https://metacpan.org/author/AKIYM>; Date:
1430               "2019-08-07"; Version: 0.05]
1431
1432           Test::Deep::JSON
1433               [โญ Author: MOTEMEN <https://metacpan.org/author/MOTEMEN>;
1434               Date: "2018-04-24"; Version: 0.05]
1435
1436               Compare JSON with Test::Deep. As of version 0.05, it relies on
1437               "JSON::MaybeXS".
1438
1439           Test::JSON
1440               [โญ Author: OVID <https://metacpan.org/author/OVID>; Date:
1441               "2009-08-09"; Version: 0.11]
1442
1443               ๐Ÿ‘Ž This offers a way to compare two different JSON strings to
1444               see if they refer to the same object. The most recent version,
1445               0.11, was released in 2009, and it relies on the deprecated
1446               "JSON::Any", which makes it essentially abandoned.
1447
1448           Test::JSON::Entails
1449               [Author: VOJ <https://metacpan.org/author/VOJ>; Date:
1450               "2012-09-14"; Version: 0.2]
1451
1452               ๐Ÿ‘Ž Test whether one JSON or Perl structure entails/subsumes
1453               another. The most recent version is from 2012, and it relies on
1454               "JSON::Any", so it is probably abandoned. Also, oddly but not
1455               uniquely for CPAN modules with the name JSON in the title, it
1456               seems to not actually have that much to do with JSON, which is
1457               a data serialisation format, but actually be testing Perl
1458               hashes and arrays.
1459
1460           Test::JSON::More
1461               [Author: BAYASHI <https://metacpan.org/author/BAYASHI>; Date:
1462               "2016-04-28"; Version: 0.02]
1463
1464               JSON Test Utility. As of version 0.02, it relies on "JSON" but
1465               it is able to use "JSON::XS" instead, and so probably
1466               "Cpanel::JSON::XS" would be OK too. According to the
1467               documentation, it can test JSON for validity and compare JSON
1468               strings with keys in a different order, and presumably with
1469               different whitespace.
1470
1471       Type-related modules
1472           These untangle numbers, strings, and booleans into JSON types.
1473
1474           JSON::TypeInference
1475               [Author: AEREAL <https://metacpan.org/author/AEREAL>; Date:
1476               "2015-10-26"; Version: "v1.0.2"]
1477
1478               ๐Ÿ˜• Virtually undocumented, it's not clear what this does.
1479
1480           JSON::Types
1481               [โญ Author: TYPESTER <https://metacpan.org/author/TYPESTER>;
1482               Date: "2012-10-17"; Version: 0.05]
1483
1484               Change the type of a Perl variable so that it comes out as a
1485               number, a string, or a boolean in the output JSON.
1486
1487           JSON::Types::Flexible
1488               [Author: PINE <https://metacpan.org/author/PINE>; Date:
1489               "2017-04-01"; Version: 0.03]
1490
1491               The module is barely documented, but from looking at the test
1492               file <https://metacpan.org/source/PINE/JSON-Types-
1493               Flexible-0.03/t%2Fjson%2Ftypes%2Fflexible%2Fclass.t>, this
1494               seems to enable you to change the output type of a number or a
1495               string so that you can, for example, make the number 1 come out
1496               as either a number, 1, a string "1", or a boolean, "true", in
1497               the output JSON.
1498
1499           JSON::Typist
1500               [โญ Author: RJBS <https://metacpan.org/author/RJBS>; Date:
1501               "2019-12-26"; Version: 0.006]
1502
1503               "Replace mushy strings and numbers with rigidly typed
1504               replacements"
1505
1506               Since Perl muddles strings and numbers, this enables you to
1507               work out whether your input JSON was "123" (a string) or 123 (a
1508               number).
1509
1510       Special-purpose modules
1511           App::JSON::to
1512               [โญ Author: DOLMEN <https://metacpan.org/author/DOLMEN>; Date:
1513               "2015-03-04"; Version: 1.000]
1514
1515               Convert JSON data to other formats. It reads your JSON file or
1516               input and converts it into either YAML or Perl native format
1517               using Data::Dumper.
1518
1519           boolean
1520               [โญโญ Author: INGY <https://metacpan.org/author/INGY>; Date:
1521               "2016-07-08"; Version: 0.46]
1522
1523               ๐Ÿ‘ This module offers "true" and "false" literals in Perl, so
1524               you just have
1525
1526                   use boolean;
1527                   my $something = true;
1528
1529               This is very useful for dealing with JSON.
1530
1531           Config::JSON
1532               [Author: RIZEN <https://metacpan.org/author/RIZEN>; Date:
1533               "2014-12-25"; Version: 1.5202]
1534
1535               Configuration files in JSON, with hash comments also allowed.
1536
1537           Devel::JSON
1538               [โญ Author: DOLMEN <https://metacpan.org/author/DOLMEN>; Date:
1539               "2017-09-03"; Version: 1.001]
1540
1541               For one-liners.
1542
1543                   If you use this module from the command-line, the last
1544                   value of your one-liner (-e) code will be serialized as
1545                   JSON data.
1546
1547           Inline::JSON
1548               [Author: KILNA <https://metacpan.org/author/KILNA>; Date:
1549               "2012-07-27"; Version: "v1.0.4"]
1550
1551               "Embed JSON data structures directly into your Perl code".
1552               Relies on "JSON".
1553
1554           JSON::Builder
1555               [Author: KNI <https://metacpan.org/author/KNI>; Date:
1556               "2015-04-16"; Version: 0.04]
1557
1558               Create JSON under memory limitations.
1559
1560           JSON::Color
1561               [โญ Author: PERLANCAR <https://metacpan.org/author/PERLANCAR>;
1562               Date: "2020-06-09"; Version: 0.130]
1563
1564               ๐ŸŒˆ This module generates JSON colorized with ANSI escape
1565               sequences.
1566
1567           JSON_File
1568               [โญ Author: GETTY <https://metacpan.org/author/GETTY>; Date:
1569               "2014-09-11"; Version: 0.004]
1570
1571           JSON::MultiValueOrdered
1572               [Author: TOBYINK <https://metacpan.org/author/TOBYINK>; Date:
1573               "2020-01-27"; Version: 0.006]
1574
1575               "JSON::MultiValueOrdered" is a special-purpose module for
1576               parsing JSON objects which have key collisions (something like
1577               "{"a":1,"a":2}") within objects.
1578
1579               (JSON::Parse's handling of key collisions is discussed in "Key
1580               collisions" in this document.)
1581
1582           JSON::String
1583               [Author: BRUMMETT <https://metacpan.org/author/BRUMMETT>; Date:
1584               "2015-02-04"; Version: "v0.2.0"]
1585
1586               Automatically change a JSON string when a data structure
1587               changes using tied scalars.
1588
1589       Patch, path, pointer, schema, and transform modules
1590           JSON::Assert
1591               [Author: SGREEN <https://metacpan.org/author/SGREEN>; Date:
1592               "2017-07-07"; Version: 0.08]
1593
1594               "Asserts JSONPaths into a JSON data structure for correct
1595               values/matches"
1596
1597           JSON::GRDDL
1598           JSON::Hyper
1599           JSON::MergePatch
1600               [โญ Author: SOJIRO <https://metacpan.org/author/SOJIRO>; Date:
1601               "2016-02-24"; Version: 0.04]
1602
1603           JSON::Patch
1604               [Author: MIXAS <https://metacpan.org/author/MIXAS>; Date:
1605               "2018-10-25"; Version: 0.04]
1606
1607               ๐Ÿ˜• We don't know what this does, or how it relates to JSON. The
1608               example in the synopsis section of the document doesn't show
1609               any JSON, it shows an example of altering nested hashes in
1610               Perl.
1611
1612           JSON::Path
1613               [โญ Author: POPEFELIX <https://metacpan.org/author/POPEFELIX>;
1614               Date: "2018-05-05"; Version: 0.420]
1615
1616               Search nested hashref/arrayref structures using JSONPath.
1617
1618           JSON::Pointer
1619               [โญ Author: ZIGOROU <https://metacpan.org/author/ZIGOROU>;
1620               Date: "2015-08-13"; Version: 0.07]
1621
1622               Extract parts of a JSON string.
1623
1624           JSON::Schema::ToJSON
1625               "Generate example JSON structures from JSON Schema definitions"
1626
1627           JSON::T
1628               [โญ Author: TOBYINK <https://metacpan.org/author/TOBYINK>;
1629               Date: "2014-09-28"; Version: 0.104]
1630
1631               Transform JSON using JsonT
1632
1633           JSON::Transform
1634               [โญ Author: ETJ <https://metacpan.org/author/ETJ>; Date:
1635               "2020-01-01"; Version: 0.03]
1636
1637           JSON::Validator
1638               [โญโญ Author: JHTHORSEN
1639               <https://metacpan.org/author/JHTHORSEN>; Date: "2021-01-24";
1640               Version: 4.12]
1641
1642               "Validate data against a JSON schema" - you can decide what the
1643               JSON is supposed to contain.
1644
1645       JSON extensions
1646           These modules extend JSON with comments and other things.
1647
1648           JSON::Diffable
1649               [โญ Author: PHAYLON <https://metacpan.org/author/PHAYLON>;
1650               Date: "2014-12-10"; Version: 0.000002]
1651
1652               "A relaxed and easy diffable JSON variant"
1653
1654           JSON::Relaxed
1655               [Author: MIKO <https://metacpan.org/author/MIKO>; Date:
1656               "2016-04-30"; Version: 0.05]
1657
1658               "An extension of JSON that allows for better human-
1659               readability".
1660
1661           JSONY
1662               [โญ Author: INGY <https://metacpan.org/author/INGY>; Date:
1663               "2020-04-27"; Version: "v0.1.21"]
1664
1665               "Relaxed JSON with a little bit of YAML"
1666
1667       Web interactions via JSON
1668           Crypt::JWT
1669               [โญโญ Author: MIK <https://metacpan.org/author/MIK>; Date:
1670               "2021-01-10"; Version: 0.031]
1671
1672               Module covers JSON Web Tokens, JSON Web Signature, and JSON Web
1673               Encryption.
1674
1675           JSON::API
1676               [โญ Author: GFRANKS <https://metacpan.org/author/GFRANKS>;
1677               Date: "2019-07-01"; Version: "v1.1.1"]
1678
1679               Combines LWP::UserAgent and JSON to make a unified module to
1680               communicate with a web server via JSON.
1681
1682           LWP::JSON::Tiny
1683               [โญ Author: SKINGTON <https://metacpan.org/author/SKINGTON>;
1684               Date: "2018-05-11"; Version: 0.014]
1685
1686           WWW::JSON
1687               [โญ Author: ANTIPASTA <https://metacpan.org/author/ANTIPASTA>;
1688               Date: "2015-05-27"; Version: 1.02]
1689
1690               "Make working with JSON Web API's as painless as possible"
1691
1692       Extension modules
1693           These modules extend the existing modules with some extra bits.
1694
1695           JSON::XS::Sugar
1696               [Author: MAXMIND <https://metacpan.org/author/MAXMIND>; Date:
1697               "2015-04-01"; Version: 1.01]
1698
1699               Provides booleans and number/string forcing for "JSON::XS".
1700
1701           Silki::JSON
1702               [โญ Author: DROLSKY <https://metacpan.org/author/DROLSKY>;
1703               Date: "2011-09-19"; Version: 0.29]
1704
1705               Switches on formatting and strict utf8 in a "JSON::XS" object.
1706
1707       Demonstration modules
1708           These modules provide a JSON parser as a demonstration of another
1709           technology.
1710
1711           JSON::Decode::Marpa
1712               [Author: PERLANCAR <https://metacpan.org/author/PERLANCAR>;
1713               Date: "2014-08-27"; Version: 0.02]
1714
1715           JSON::Decode::Regexp
1716               [Author: PERLANCAR <https://metacpan.org/author/PERLANCAR>;
1717               Date: "2018-03-25"; Version: 0.101]
1718
1719               ๐Ÿ›๐ŸฆŸ๐Ÿฆ‹๐Ÿž JSON parser as a single Perl Regex, originally by
1720               Randal Schwartz. This may be ingenious, but it's not remotely a
1721               useful JSON parser. For example, looking at the string part, it
1722               provides no Unicode validation, no support for Unicode escapes
1723               <https://metacpan.org/release/JSON-Decode-
1724               Regexp/source/lib/JSON/Decode/Regexp.pm#L141> and it allows
1725               invalid escapes such as "\xFF"
1726               <https://metacpan.org/release/JSON-Decode-
1727               Regexp/source/lib/JSON/Decode/Regexp.pm#L137>.
1728
1729           MarpaX::Demo::JSONParser
1730               [Author: RSAVAGE <https://metacpan.org/author/RSAVAGE>; Date:
1731               "2019-06-18"; Version: 1.08]
1732
1733           Pegex::JSON
1734               [Author: INGY <https://metacpan.org/author/INGY>; Date:
1735               "2020-01-22"; Version: 0.31]
1736
1737               ๐Ÿ› Based on Pegex.  See our bug report
1738               <https://github.com/pegex-parser/pegex-json-pm/issues/3>.
1739
1740       Other modules
1741           Modules which are parts of bigger distributions have not been
1742           included here except by accident.
1743
1744           App::JSON::Tools
1745               [Author: KABLAMO <https://metacpan.org/author/KABLAMO>; Date:
1746               "2016-08-05"; Version: 0.01]
1747
1748               Undocumented command-line tools for JSON.
1749
1750           App::JSONPretty
1751               [โญ Author: MSTROUT <https://metacpan.org/author/MSTROUT>;
1752               Date: "2011-02-02"; Version: 1]
1753
1754               ๐Ÿ‘Ž๐Ÿ› JSON prettification script. For whatever reason the script
1755               encapsulates the entirety of an old version of the "JSON"
1756               module dating from before "JSON::PP" was included in the Perl
1757               core.
1758
1759               If you need this kind of script, there is something called
1760               json_xs which comes with "JSON::XS", or equivalently
1761               cpanel_json_xs in the forked module "Cpanel::JSON::XS".
1762
1763           ARGV::JSON
1764               [โญ Author: MOTEMEN <https://metacpan.org/author/MOTEMEN>;
1765               Date: "2013-12-18"; Version: 0.01]
1766
1767           Jasonify
1768               [Author: BOBK <https://metacpan.org/author/BOBK>; Date:
1769               "2020-03-04"; Version: "v0.20.064"]
1770
1771           JS::JSON
1772               [Author: INGY <https://metacpan.org/author/INGY>; Date:
1773               "2008-08-30"; Version: 0.02]
1774
1775               ๐Ÿ‘Ž This is JavaScript code which was uploaded to CPAN. The
1776               original JavaScript is now obsolete since the thing it codes is
1777               included in all modern web browsers.
1778
1779           JSON::Eval
1780               [Author: TOBYINK <https://metacpan.org/author/TOBYINK>; Date:
1781               "2019-10-27"; Version: 0.002]
1782
1783               Eval Perl code found in JSON. This module enables one to encode
1784               and decode Perl scalar references and code references to JSON.
1785
1786           JSON::ize
1787               [โญ Author: MAJENSEN <https://metacpan.org/author/MAJENSEN>;
1788               Date: "2019-07-13"; Version: 0.202]
1789
1790               Something about one-liners.
1791
1792           JSON::JSend
1793               [Author: HOEKIT <https://metacpan.org/author/HOEKIT>; Date:
1794               "2016-04-23"; Version: 0.02]
1795
1796           JSON::Lines
1797               [โญ Author: LNATION <https://metacpan.org/author/LNATION>;
1798               Date: "2020-10-25"; Version: 0.03]
1799
1800               "JSON Lines is a convenient format for storing structured data
1801               that may be processed one record at a time."
1802
1803           JSON::Meth
1804               [โญ Author: ZOFFIX <https://metacpan.org/author/ZOFFIX>; Date:
1805               "2015-11-28"; Version: 1.001007]
1806
1807               ๐Ÿ˜• Claims to be "no nonsense JSON encoding/decoding as method
1808               calls on data". From the documentation:
1809
1810                   Don't make me think and give me what I want! This module
1811                   automatically figures out whether you want to encode a Perl
1812                   data structure to JSON or decode a JSON string to a Perl
1813                   data structure.
1814
1815           JSON::ON
1816               [Author: EWILHELM <https://metacpan.org/author/EWILHELM>; Date:
1817               "2013-06-26"; Version: "v0.0.3"]
1818
1819               JavaScript object notation object notator.
1820
1821           JSON::SL
1822               [โญ Author: MNUNBERG <https://metacpan.org/author/MNUNBERG>;
1823               Date: "2017-11-10"; Version: "v1.0.7"]
1824
1825           JSON::Streaming::Reader
1826               [โญ Author: MART <https://metacpan.org/author/MART>; Date:
1827               "2012-11-24"; Version: 0.06]
1828
1829           JSON::Streaming::Writer
1830               [Author: MART <https://metacpan.org/author/MART>; Date:
1831               "2012-11-24"; Version: 0.03]
1832
1833           JSON::Util
1834               [Author: JKUTEJ <https://metacpan.org/author/JKUTEJ>; Date:
1835               "2015-09-03"; Version: 0.06]
1836
1837               Relies on JSON::MaybeXS and the author's other module IO::Any,
1838               so that you can put either a file name or a JSON string as the
1839               argument and it tries to work out which one you have given it.
1840               That is ingenious, but it seems that if you are a programmer
1841               who cannot distinguish whether your input string is a file name
1842               or JSON, you have a very serious problem.
1843
1844           JSON::XS::ByteString
1845               [โญ Author: CINDY <https://metacpan.org/author/CINDY>; Date:
1846               "2020-04-18"; Version: 1.004]
1847
1848               ๐Ÿ˜• The README <https://metacpan.org/source/CINDY/JSON-XS-
1849               ByteString-1.004/README> claims it is a "thin wrapper around
1850               JSON::XS", but it contains a complete implementation of JSON
1851               <https://metacpan.org/source/CINDY/JSON-XS-
1852               ByteString-1.004/ByteString.xs>, which seems to have partly
1853               been copy-pasted from the JSON::XS source code, but internally
1854               it doesn't make any reference to JSON::XS. The licence and
1855               copyright statement don't mention JSON::XS's original author at
1856               all so we're not sure if this is a fork, a wrapper, or a
1857               reimplementation.
1858
1859               We haven't tried downloading this or installing it, but
1860               according to the documentation, this module encodes numbers
1861               with quotes around them, so "{this => 2}" turns into
1862               "{"this":"2"}".
1863
1864           JSON_minify
1865               [Author: RCOSCALI <https://metacpan.org/author/RCOSCALI>; Date:
1866               "2021-01-24"; Version: 1.1]
1867
1868           Text::JSON::Nibble
1869               [Author: DAEMON <https://metacpan.org/author/DAEMON>; Date:
1870               "2017-05-02"; Version: 1.01]
1871
1872               Nibble complete JSON objects from buffers.
1873
1874               This seems to be for extracting JSON from the midst of noise.
1875

SCRIPT

1877       A script "validjson" is supplied with the module. This runs
1878       "assert_valid_json" on its inputs, so run it like this.
1879
1880            validjson *.json
1881
1882       The default behaviour is to just do nothing if the input is valid. For
1883       invalid input it prints what the problem is:
1884
1885           validjson ids.go
1886           ids.go: JSON error at line 1, byte 1/7588: Unexpected character '/' parsing initial state: expecting whitespace: '\n', '\r', '\t', ' ' or start of string: '"' or digit: '0-9' or minus: '-' or start of an array or object: '{', '[' or start of literal: 't', 'f', 'n'.
1887
1888       If you need confirmation, use its --verbose option:
1889
1890           validjson -v *.json
1891
1892           atoms.json is valid JSON.
1893           ids.json is valid JSON.
1894           kanjidic.json is valid JSON.
1895           linedecomps.json is valid JSON.
1896           radkfile-radicals.json is valid JSON.
1897

DEPENDENCIES

1899       Carp
1900

EXPORTS

1902       The module exports nothing by default. Functions "parse_json",
1903       "parse_json_safe", "read_json", "valid_json" and "assert_valid_json",
1904       as well as the old function names "validate_json", "json_file_to_perl",
1905       and "json_to_perl", can be exported on request.
1906
1907       All of the functions can be exported using the tag ':all':
1908
1909           use JSON::Parse ':all';
1910

TESTING

1912   Internal testing code
1913       The module incorporates extensive testing related to the production of
1914       error messages and validation of input. Some of the testing code is
1915       supplied with the module in the /t/ subdirectory of the distribution.
1916
1917       More extensive testing code is in the git repository. This is not
1918       supplied in the CPAN distribution. A script, randomjson.pl
1919       <https://github.com/benkasminbullock/JSON-
1920       Parse/033269fa8972fdce8626aa65cd11a5394ab50492/randomjson.pl>,
1921       generates a set number of bytes of random JSON and checks that the
1922       module's bytewise validation of input is correct. It does this by
1923       taking a valid fragment, then adding each possible byte from 0 to 255
1924       to see whether the module correctly identifies it as valid or invalid
1925       at that point, then randomly picking one of the valid bytes and adding
1926       it to the fragment and continuing the process until a complete valid
1927       JSON input is formed. The module has undergone about a billion
1928       repetitions of this test.
1929
1930       This setup relies on a C file, json-random-test.c
1931       <https://github.com/benkasminbullock/JSON-
1932       Parse/033269fa8972fdce8626aa65cd11a5394ab50492/json-random-test.c>,
1933       which isn't in the CPAN distribution, and it also requires Json3.xs
1934       <https://github.com/benkasminbullock/JSON-
1935       Parse/033269fa8972fdce8626aa65cd11a5394ab50492/Json3.xs> to be edited
1936       to make the macro "TESTRANDOM" true (uncomment line 7 of the file). The
1937       testing code uses C setjmp/longjmp, so it's not guaranteed to work on
1938       all operating systems and is commented out for CPAN releases.
1939
1940       A pure C version called random-test.c
1941       <https://github.com/benkasminbullock/JSON-
1942       Parse/033269fa8972fdce8626aa65cd11a5394ab50492/random-test.c> also
1943       exists. This applies exactly the same tests, and requires no Perl at
1944       all.
1945
1946       If you're interested in testing your own JSON parser, the outputs
1947       generated by randomjson.pl <https://github.com/benkasminbullock/JSON-
1948       Parse/033269fa8972fdce8626aa65cd11a5394ab50492/randomjson.pl> are quite
1949       a good place to start. The default is to produce UTF-8 output, which
1950       looks pretty horrible since it tends to produce long strings of UTF-8
1951       garbage. (This is because it chooses randomly from 256 bytes and the
1952       end-of-string marker """ has only a 1/256 chance of being chosen, so
1953       the strings tend to get long and messy). You can mess with the
1954       internals of JSON::Parse by setting MAXBYTE in json-common.c to 0x80,
1955       recompiling (you can ignore the compiler warnings), and running
1956       randomjson.pl again to get just ASCII random JSON things. This breaks
1957       the UTF-8 functionality of JSON::Parse, so please don't install that
1958       version.
1959
1960   JSON Parsing Test Suite
1961       JSON::Parse version 0.58 passes most of the JSON Parsing Test Suite,
1962       with the exception that JSON::Parse rejects various erroneous UTF-8
1963       inputs, for example JSON::Parse will throw an error for non-character
1964       code points like Unicode U+FFFF and U+10FFFF. This parser only accepts
1965       valid UTF-8 as input. See "UTF-8 only".
1966
1967       In our opinion it would be a disservice to users of this module to
1968       allow bytes containing useless fragments such as incomplete parts of
1969       surrogate pairs, or invalid characters, just because the JSON
1970       specification doesn't actually explicitly demand rejecting these kinds
1971       of garbage inputs. Please see the function "daft_test" in the file
1972       xt/JPXT.pm for exactly which of these elements of the test suite we do
1973       not comply with. We note that this comment from Douglas Crockford, the
1974       inventor of JSON, JSON parser
1975       <https://github.com/douglascrockford/JSON-
1976       c/blob/master/utf8_decode.c#L38-L43>, dated 2005, agrees with our
1977       opinion on this point.
1978
1979       JSON::Parse version 0.58 also introduced "get_max_depth" and
1980       "set_max_depth" to prevent the stack overflow errors caused by some
1981       very deeply nested inputs such as those of the JSON Parsing Test Suite.
1982

ACKNOWLEDGEMENTS

1984       Toby Inkster (TOBYINK) suggested some of the new function names which
1985       replaced the "OLD INTERFACE" names. Nicolas Immelman and Shlomi Fish
1986       (SHLOMIF) reported memory leaks which were fixed in 0.32 and 0.40.
1987       Github user kolmogorov42 reported a bug which led to 0.42. Github user
1988       SteveGlassman found an error in string copying for long strings, fixed
1989       in 0.57. Lars Dษชแด‡แด„แด‹แดแดก (DAXIM) pointed out problems with the JSON
1990       Parsing Test Suite which led to the addition of stack protection and
1991       "set_max_depth" and "get_max_depth" in 0.58.
1992

AUTHOR

1994       Ben Bullock, <bkb@cpan.org>
1995
1997       This package and associated files are copyright (C) 2013-2021 Ben
1998       Bullock.
1999
2000       You can use, copy, modify and redistribute this package and associated
2001       files under the Perl Artistic Licence or the GNU General Public
2002       Licence.
2003
2004
2005
2006perl v5.34.0                      2021-07-22                    JSON::Parse(3)
Impressum