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

SCRIPT

1911       A script "validjson" is supplied with the module. This runs
1912       "assert_valid_json" on its inputs, so run it like this.
1913
1914            validjson *.json
1915
1916       The default behaviour is to just do nothing if the input is valid. For
1917       invalid input it prints what the problem is:
1918
1919           validjson ids.go
1920           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'.
1921
1922       If you need confirmation, use its --verbose option:
1923
1924           validjson -v *.json
1925
1926           atoms.json is valid JSON.
1927           ids.json is valid JSON.
1928           kanjidic.json is valid JSON.
1929           linedecomps.json is valid JSON.
1930           radkfile-radicals.json is valid JSON.
1931

DEPENDENCIES

1933       Carp
1934

EXPORTS

1936       The module exports nothing by default. Functions "parse_json",
1937       "parse_json_safe", "read_json", "valid_json" and "assert_valid_json",
1938       as well as the old function names "validate_json", "json_file_to_perl",
1939       and "json_to_perl", can be exported on request.
1940
1941       All of the functions can be exported using the tag ':all':
1942
1943           use JSON::Parse ':all';
1944

TESTING

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

ACKNOWLEDGEMENTS

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

AUTHOR

2028       Ben Bullock, <bkb@cpan.org>
2029
2031       This package and associated files are copyright (C) 2013-2022 Ben
2032       Bullock.
2033
2034       You can use, copy, modify and redistribute this package and associated
2035       files under the Perl Artistic Licence or the GNU General Public
2036       Licence.
2037
2038
2039
2040perl v5.36.0                      2023-01-20                    JSON::Parse(3)
Impressum