1JSON::Parse(3) User Contributed Perl Documentation JSON::Parse(3)
2
6 JSON::Parse - Parse JSON
7
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 Convert JSON into Perl.
15
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
24 A module for parsing JSON. (JSON means "JavaScript Object Notation" and
25 it is specified in "RFC 8259".)
26 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 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 JSON::Parse accepts only UTF-8 as input. See "UTF-8 only" and "Handling
40 of Unicode".
41
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 produces output
54 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 (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 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 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 The method equivalent to this is "check".
71 The behaviour of disallowing empty inputs was changed in version 0.49.
73 parse_json
75 use JSON::Parse 'parse_json';
76 my $perl = parse_json ('{"x":1, "y":2}');
77 This function converts JSON into a Perl structure, either an array
79 reference, a hash reference, or a scalar.
80 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 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 use JSON::Parse ':all';
90 my $perl = parse_json ('{"a":1, "b":2}');
91 print ref $perl, "\n";
92 produces output
94 HASH
96 (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 If the input JSON text is a serialized array, an array reference is
102 returned:
103 use JSON::Parse ':all';
105 my $perl = parse_json ('["a", "b", "c"]');
106 print ref $perl, "\n";
107 produces output
109 ARRAY
111 (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 Otherwise a Perl scalar is returned.
117 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 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 parse_json_safe
127 This is almost the same thing as "parse_json", but has the following
128 differences:
129 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 eval {
135 $out = parse_json ($json);
136 };
137 if ($@) {
138 carp $@;
139 $out = undef;
140 }
141 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 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 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 As the name implies, this is meant to be a "safety-first" version of
158 "parse_json".
159 ๐ฒ This function was added in version 0.38.
161 read_json
163 use JSON::Parse 'read_json';
164 my $p = read_json ('filename');
165 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 The method equivalent is "read".
173 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 This was renamed from "json_file_to_perl" in version 0.59. The old name
178 will also continue to work indefinitely.
179 valid_json
181 use JSON::Parse 'valid_json';
182 if (valid_json ($json)) {
183 # do something
184 }
185 "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 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 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
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 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 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 check
216 eval {
217 $jp->check ($json);
218 };
219 This does the same thing as "assert_valid_json", except its behaviour
221 can be modified using the "diagnostics_hash" method.
222 ๐ฒ This method was added in version 0.48. This is for the benefit of
224 JSON::Repair.
225 copy_literals
227 $jp->copy_literals (1);
228 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 With a false value, use read-only scalars:
234 $jp->copy_literals (0);
236 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 If the user also sets user-defined literals with "set_true",
242 "set_false" and "set_null", that takes precedence over this.
243 ๐ฒ This method was added in version 0.38.
245 detect_collisions
247 $jp->detect_collisions (1);
248 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 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 produces output
263 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 (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 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 ๐ฒ This method was added in version 0.38.
275 diagnostics_hash
277 $jp->diagnostics_hash (1);
278 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 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 This requires Perl version 5.14 or later.
290 An example of the use of this method to "repair" broken JSON is in the
292 module "JSON::Repair".
293 ๐ฒ This method was added in version 0.46.
295 get_max_depth
297 my $max_depth = $jp->get_max_depth ();
298 This returns the maximum nesting depth of objects or arrays in the
300 input JSON. The default value is 10,000.
301 ๐ฒ This method was added in version 0.58.
303 new
305 my $jp = JSON::Parse->new ();
306 Create a new JSON::Parse object.
308 ๐ฒ This method was added in version 0.38.
310 parse
312 my $out = $jp->parse ($json);
313 This does the same thing as "parse_json", except its behaviour can be
315 modified using object methods.
316 ๐ฒ This method was added in version 0.38.
318 This was renamed from "run" in version 0.60.
320 read
322 my $json = $jp->read ($file);
323 Read a file, parse the contained JSON, and return the output. This
325 method is equivalent to the function "read_json".
326 ๐ฒ This method was added in version 0.60.
328 set_max_depth
330 $jp->set_max_depth (42);
331 Set the maximum nesting depth of objects or arrays in the input JSON.
333 The default value is 10,000.
334 ๐ฒ This method was added in version 0.58.
336 upgrade_utf8
338 $jp->upgrade_utf8 (1);
339 Upgrade input from bytes to characters automatically.
341 This can be switched off again using any false value:
343 $jp->upgrade_utf8 (0);
345 ๐ฒ This method was added in version 0.61.
347 warn_only
349 $jp->warn_only (1);
350 Warn, don't die, on error. Failed parsing returns the undefined value,
352 "undef", and prints a warning.
353 This can be switched off again using any false value:
355 $jp->warn_only ('');
357 ๐ฒ This method was added in version 0.41.
359 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 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 $jp->set_false (undef);
369 Thus, we cannot use a single function "$jp->false (undef)" to cover
371 both setting and deleting of values.
372 ๐ฒ This facility was added in version 0.38.
374 set_true
376 $jp->set_true ("Yes, that is so true");
378 Supply a scalar to be used in place of the JSON "true" literal.
380 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 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 prints
393 Yes, that is so true
395 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 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 ๐ฒ This method was added in version 0.38.
406 delete_true
408 $jp->delete_true ();
410 Delete the user-defined true value. See "set_true".
412 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 ๐ฒ This method was added in version 0.38.
417 set_false
419 $jp->set_false (JSON::PP::Boolean::false);
421 Supply a scalar to be used in place of the JSON "false" literal.
423 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 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 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 ๐ฒ This method was added in version 0.38.
438 delete_false
440 $jp->delete_false ();
442 Delete the user-defined false value. See "set_false".
444 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 ๐ฒ This method was added in version 0.38.
449 set_null
451 $jp->set_null (0);
453 Supply a scalar to be used in place of the JSON "null" literal.
455 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 ๐ฒ This method was added in version 0.38.
461 delete_null
463 $jp->delete_null ();
465 Delete the user-defined null value. See "set_null".
467 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 ๐ฒ This method was added in version 0.38.
472 no_warn_literals
474 $jp->no_warn_literals (1);
476 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 $jp->no_warn_literals (1);
482 $jp->set_false ("false");
483 See also "Contradictory values for "true" and "false"".
485 This also switches off the warning "User-defined value overrules
487 copy_literals".
488 ๐ฒ This method was added in version 0.38.
490
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 The names ending in "_to_perl" seem quite silly in retrospect since
497 surely it is obvious that one is programming in Perl.
498 json_to_perl
500 This is exactly the same function as "parse_json".
501 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 run
508 This is the old name for "parse".
509 validate_json
511 This is exactly the same function as "assert_valid_json".
512
514 JSON elements are mapped to Perl as follows:
515 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 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 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 Handling of Unicode
533 Inputs must be in the UTF-8 format. See "UTF-8 only".
535 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 Unicode encoding points in the input of the form "\u3000" are converted
541 into the equivalent UTF-8 bytes.
542 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 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 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 but
563 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 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 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 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 This is modelled on the behaviour of Perl's "chr":
593 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 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 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 produces output
634 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 (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 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 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 Thus
657 my $p = parse_json ('["monday", "tuesday", "wednesday"]');
659 has the same result as a Perl declaration of the form
661 my $p = [ 'monday', 'tuesday', 'wednesday' ];
663 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 Thus
671 my $j = <<EOF;
673 {"monday":["blue", "black"],
674 "tuesday":["grey", "heart attack"],
675 "friday":"Gotta get down on Friday"}
676 EOF
677 my $p = parse_json ($j);
679 has the same result as a Perl declaration of the form
681 my $p = {
683 monday => ['blue', 'black'],
684 tuesday => ['grey', 'heart attack'],
685 friday => 'Gotta get down on Friday',
686 };
687 Key collisions
689 A key collision is something like the following.
691 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 produces output
699 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 (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 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 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 For performance, "valid_json" and "assert_valid_json" do not store hash
720 keys, thus they cannot detect this variety of problem.
721 Literals
723 false
724 "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 null
736 "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 true
745 "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 Round trips and compatibility
753 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 A round trip with JSON::Tiny
762 This example demonstrates round-trip compatibility using JSON::Tiny,
764 version 0.58:
765 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 print "First do a round-trip of our modules:\n\n";
775 print $jc->create ($jp->parse ($cream)), "\n\n";
776 print "Now do a round-trip of JSON::Tiny:\n\n";
778 print encode_json (decode_json ($cream)), "\n\n";
779 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 # Set our parser to produce these things as literals:
785 $jp->set_true (JSON::Tiny::true);
786 $jp->set_false (JSON::Tiny::false);
787 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 print "๐ Compatibility with JSON::Create:\n\n";
793 print 'create(tiny):', $jc->create (decode_json ($cream)), "\n\n";
794 print "๐ JSON::Parse and JSON::Create are still compatible too:\n\n";
796 print $jc->create ($jp->parse ($cream)), "\n";
797 produces output
799 First do a round-trip of our modules:
801 {"clapton":true,"hendrix":false}
803 Now do a round-trip of JSON::Tiny:
805 {"clapton":true,"hendrix":false}
807 ๐ฅด First, incompatible mode:
809 tiny(parse): {"clapton":1,"hendrix":""}
811 create(tiny): {"clapton":1,"hendrix":0}
812 ๐ Compatibility with JSON::Parse:
814 tiny(parse):{"clapton":true,"hendrix":false}
816 ๐ Compatibility with JSON::Create:
818 create(tiny):{"clapton":true,"hendrix":false}
820 ๐ JSON::Parse and JSON::Create are still compatible too:
822 {"clapton":true,"hendrix":false}
824 (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 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 Modifying the values
834 "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 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 Since the hash values are read-only scalars, "$p->{hocus} = 99" is like
846 this:
847 undef = 99;
849 If you need to modify the returned hash reference, then delete the
851 value first:
852 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 Similarly with array references, delete the value before altering:
860 my $in = '[true,false,null]';
862 my $q = json_parse ($in);
863 delete $q->[1];
864 $q->[1] = 'magic';
865 Note that the return values from parsing bare literals are not read-
867 only scalars, so
868 my $true = JSON::Parse::json_parse ('true');
870 $true = 99;
871 produces no error. This is because Perl copies the scalar.
873
875 This module imposes the following restrictions on its input.
876 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 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 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 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 use Encode 'decode';
908 my $input_utf8 = decode ('UTF-16', $input);
909 my $perl = parse_json ($input_utf8);
910 or, for a file, use ":encoding" (see PerlIO::encoding and
912 perluniintro):
913 open my $input, "<:encoding(UTF-16)", 'some-json-file';
915 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 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 The latest specification for JSON, "RFC 8259", specifies it to be a
926 UTF-8 only format.
927 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
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 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 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 my $p;
948 eval {
949 $p = parse_json ($j);
950 };
951 if ($@) {
952 # handle error
953 }
954 The following error messages are produced:
956 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 assert_valid_json ('+');
964 gives output
966 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 The message always includes a list of what characters are allowed.
970 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 assert_valid_json ('{"this":"\a"}');
976 gives output
978 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 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 assert_valid_json ('[true,folse]');
987 gives output
989 JSON error at line 1, byte 8/12: Unexpected character 'o' parsing literal starting from byte 7: expecting 'a'
991 and the missing second half of a surrogate pair:
993 assert_valid_json ('["\udc00? <-- should be a second half here"]');
995 gives output
997 JSON error at line 1, byte 9/44: Unexpected character '?' parsing unicode escape starting from byte 3: expecting '\'
999 All kinds of errors can occur parsing numbers, for example a
1001 missing fraction,
1002 assert_valid_json ('[1.e9]');
1004 gives output
1006 JSON error at line 1, byte 4/6: Unexpected character 'e' parsing number starting from byte 2: expecting digit: '0-9'
1008 and a leading zero,
1010 assert_valid_json ('[0123]');
1012 gives output
1014 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 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 These are all handled by this error. Thus the error messages are a
1022 little confusing as diagnostics.
1023 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 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 no utf8;
1038 use JSON::Parse 'assert_valid_json';
1039 # Error in first byte:
1041 my $bad_utf8_1 = chr (hex ("81"));
1043 eval { assert_valid_json ("[\"$bad_utf8_1\"]"); };
1044 print "$@\n";
1045 # Error in third byte:
1047 my $bad_utf8_2 = chr (hex ('e2')) . chr (hex ('9C')) . 'b';
1049 eval { assert_valid_json ("[\"$bad_utf8_2\"]"); };
1050 print "$@\n";
1051 prints
1053 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 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 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 assert_valid_json ('{"first":"Suzuki","second":"Murakami","third":"Asada}');
1064 gives output
1066 JSON error at line 1: Unexpected end of input parsing string starting from byte 47
1068 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 assert_valid_json ('["\uDC00\uABCD"]');
1075 gives output
1077 JSON error at line 1: Not surrogate pair parsing unicode escape starting from byte 11
1079 Empty input
1081 This error occurs for an input which is an empty (no length or
1082 whitespace only) or an undefined value.
1083 assert_valid_json ('');
1085 gives output
1087 JSON error: Empty input parsing initial state
1089 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 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 my $p = JSON::Parse->new ();
1099 $p->detect_collisions (1);
1100 $p->run ('{"hocus":1,"pocus":2,"hocus":3}');
1101 gives output
1103 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 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 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 $jp->set_false (1);
1114 To switch off this warning, use "no_warn_literals".
1116 ๐ฒ This warning was added in version 0.38.
1118 User-defined value for JSON true evaluates as false
1120 This happens if you set JSON true to map to a false value:
1121 $jp->set_true (undef);
1123 To switch off this warning, use "no_warn_literals".
1125 ๐ฒ This warning was added in version 0.38.
1127 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 ๐ฒ This warning was added in version 0.38.
1134
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 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 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 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 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 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 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 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 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 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 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
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 json.org
1245 <https://json.org> is the website for JSON, authored by Douglas
1246 Crockford.
1247 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 Modules by the same author
1257 JSON::Create
1258 ๐ JSON::Create is a companion module to JSON::Parse by the
1259 same author.
1260 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 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 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 JSON::Whitespace
1277 JSON::Whitespace is for manipulating the "insignificant
1278 whitespace" part of JSON.
1279 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 This is a fork of JSON::XS. Please see the module for details
1286 about the reasons for the fork.
1287 File::JSON::Slurper
1289 [โญ Author: NEILB <https://metacpan.org/author/NEILB>; Date:
1290 "2020-11-18"; Version: 1.00]
1291 Slurp a JSON file into a data structure, and the reverse. It
1293 relies on "JSON::MaybeXS".
1294 Glib::JSON
1296 [โญ Author: EBASSI <https://metacpan.org/author/EBASSI>; Date:
1297 "2015-04-19"; Version: 0.002]
1298 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 JSON
1307 [โญโญ Author: ISHIGAKI <https://metacpan.org/author/ISHIGAKI>;
1308 Date: "2021-01-24"; Version: 4.03]
1309 This calls on either JSON::PP or JSON::XS.
1311 JSON::DWIW
1313 [Author: DOWENS <https://metacpan.org/author/DOWENS>; Date:
1314 "2010-09-29"; Version: 0.47]
1315 ๐๐ 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 JSON::Parser::Regexp
1325 [Author: RAJ <https://metacpan.org/author/RAJ>; Date:
1326 "2021-03-16"; Version: 0.04]
1327 Uses Regexp::Grammars to parse JSON.
1329 JSON::PP
1331 [โญโญ Author: ISHIGAKI <https://metacpan.org/author/ISHIGAKI>;
1332 Date: "2021-01-23"; Version: 4.06]
1333 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 JSON::Slurper
1340 [โญ Author: SRCHULO <https://metacpan.org/author/SRCHULO>;
1341 Date: "2019-10-30"; Version: 0.12]
1342 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 JSON::Syck
1350 [โญโญ Author: TODDR <https://metacpan.org/author/TODDR>; Date:
1351 "2020-10-26"; Version: 1.34]
1352 ๐๐ 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 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 JSON::Tiny
1366 [โญโญ Author: DAVIDO <https://metacpan.org/author/DAVIDO>;
1367 Date: "2017-11-12"; Version: 0.58]
1368 This is a fork of "Mojo::JSON".
1370 JSON::XS
1372 [โญโญโญ Author: MLEHMANN
1373 <https://metacpan.org/author/MLEHMANN>; Date: "2020-10-27";
1374 Version: 4.03]
1375 This is an all-purpose JSON module in XS, which means it
1377 requires a C compiler to install.
1378 JSON::YAJL
1380 [โญ Author: LBROCARD <https://metacpan.org/author/LBROCARD>;
1381 Date: "2011-08-05"; Version: 0.10]
1382 ๐๐ 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 Mojo::JSON
1388 [โญโญโญ Author: SRI <https://metacpan.org/author/SRI>; Date:
1389 "2021-04-13"; Version: 9.17]
1390 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 Combination modules
1397 These modules rely on more than one back-end module to process JSON
1398 for you.
1399 JSON::Any
1401 [โญ Author: ETHER <https://metacpan.org/author/ETHER>; Date:
1402 "2015-06-10"; Version: 1.39]
1403 ๐ This now-deprecated module combines "JSON::DWIW", "JSON::XS"
1405 versions one and two, and "JSON::Syck".
1406 JSON::MaybeXS
1408 [โญโญ Author: ETHER <https://metacpan.org/author/ETHER>; Date:
1409 "2020-11-13"; Version: 1.004003]
1410 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 JSON::XS::VersionOneAndTwo
1417 [Author: LBROCARD <https://metacpan.org/author/LBROCARD>; Date:
1418 "2008-02-13"; Version: 0.31]
1419 ๐ A "combination module" which supports two different
1421 interfaces of "JSON::XS". However, JSON::XS is now onto version
1422 4.
1423 Mojo::JSON::MaybeXS
1425 [โญ Author: DBOOK <https://metacpan.org/author/DBOOK>; Date:
1426 "2019-08-07"; Version: 1.002]
1427 ๐ 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 Test-related modules
1434 Test2::Tools::JSON
1435 [Author: AKIYM <https://metacpan.org/author/AKIYM>; Date:
1436 "2019-08-07"; Version: 0.05]
1437 Test::Deep::JSON
1439 [โญ Author: MOTEMEN <https://metacpan.org/author/MOTEMEN>;
1440 Date: "2018-04-24"; Version: 0.05]
1441 Compare JSON with Test::Deep. As of version 0.05, it relies on
1443 "JSON::MaybeXS".
1444 Test::JSON
1446 [โญ Author: OVID <https://metacpan.org/author/OVID>; Date:
1447 "2009-08-09"; Version: 0.11]
1448 ๐ 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 Test::JSON::Entails
1455 [Author: VOJ <https://metacpan.org/author/VOJ>; Date:
1456 "2012-09-14"; Version: 0.2]
1457 ๐ 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 Test::JSON::More
1467 [Author: BAYASHI <https://metacpan.org/author/BAYASHI>; Date:
1468 "2016-04-28"; Version: 0.02]
1469 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 Type-related modules
1478 These untangle numbers, strings, and booleans into JSON types.
1479 JSON::TypeInference
1481 [Author: AEREAL <https://metacpan.org/author/AEREAL>; Date:
1482 "2015-10-26"; Version: "v1.0.2"]
1483 ๐ Virtually undocumented, it's not clear what this does.
1485 JSON::Types
1487 [โญ Author: TYPESTER <https://metacpan.org/author/TYPESTER>;
1488 Date: "2012-10-17"; Version: 0.05]
1489 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 JSON::Types::Flexible
1494 [Author: PINE <https://metacpan.org/author/PINE>; Date:
1495 "2017-04-01"; Version: 0.03]
1496 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 JSON::Typist
1506 [โญ Author: RJBS <https://metacpan.org/author/RJBS>; Date:
1507 "2021-05-03"; Version: 0.007]
1508 "Replace mushy strings and numbers with rigidly typed
1510 replacements"
1511 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 Special-purpose modules
1517 App::JSON::to
1518 [โญ Author: DOLMEN <https://metacpan.org/author/DOLMEN>; Date:
1519 "2015-03-04"; Version: 1.000]
1520 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 boolean
1526 [โญโญ Author: INGY <https://metacpan.org/author/INGY>; Date:
1527 "2016-07-08"; Version: 0.46]
1528 ๐ This module offers "true" and "false" literals in Perl, so
1530 you just have
1531 use boolean;
1533 my $something = true;
1534 This is very useful for dealing with JSON.
1536 Config::JSON
1538 [Author: RIZEN <https://metacpan.org/author/RIZEN>; Date:
1539 "2014-12-25"; Version: 1.5202]
1540 Configuration files in JSON, with hash comments also allowed.
1542 Devel::JSON
1544 [โญ Author: DOLMEN <https://metacpan.org/author/DOLMEN>; Date:
1545 "2017-09-03"; Version: 1.001]
1546 For one-liners.
1548 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 Inline::JSON
1554 [Author: KILNA <https://metacpan.org/author/KILNA>; Date:
1555 "2012-07-27"; Version: "v1.0.4"]
1556 "Embed JSON data structures directly into your Perl code".
1558 Relies on "JSON".
1559 JSON::Builder
1561 [Author: KNI <https://metacpan.org/author/KNI>; Date:
1562 "2015-04-16"; Version: 0.04]
1563 Create JSON under memory limitations.
1565 JSON::Color
1567 [โญ Author: PERLANCAR <https://metacpan.org/author/PERLANCAR>;
1568 Date: "2021-05-07"; Version: 0.131]
1569 ๐ This module generates JSON colorized with ANSI escape
1571 sequences.
1572 JSON_File
1574 [โญ Author: GETTY <https://metacpan.org/author/GETTY>; Date:
1575 "2014-09-11"; Version: 0.004]
1576 JSON::MultiValueOrdered
1578 [Author: TOBYINK <https://metacpan.org/author/TOBYINK>; Date:
1579 "2020-01-27"; Version: 0.006]
1580 "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 (JSON::Parse's handling of key collisions is discussed in "Key
1586 collisions" in this document.)
1587 JSON::String
1589 [Author: BRUMMETT <https://metacpan.org/author/BRUMMETT>; Date:
1590 "2015-02-04"; Version: "v0.2.0"]
1591 Automatically change a JSON string when a data structure
1593 changes using tied scalars.
1594 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 "Asserts JSONPaths into a JSON data structure for correct
1601 values/matches"
1602 JSON::Conditional
1604 [Author: LNATION <https://metacpan.org/author/LNATION>; Date:
1605 "2021-03-29"; Version: 1.00]
1606 JSON::GRDDL
1608 [Author: TOBYINK <https://metacpan.org/author/TOBYINK>; Date:
1609 "2014-09-11"; Version: 0.002]
1610 JSON::Hyper
1612 [โญ Author: TOBYINK <https://metacpan.org/author/TOBYINK>;
1613 Date: "2012-10-12"; Version: 0.011]
1614 JSON::JQ
1616 [Author: DONGXU <https://metacpan.org/author/DONGXU>; Date:
1617 "2021-05-16"; Version: 0.06]
1618 Perl access to the "jq" tool via Alien::LibJQ.
1620 JSON::MergePatch
1622 [โญ Author: SOJIRO <https://metacpan.org/author/SOJIRO>; Date:
1623 "2016-02-24"; Version: 0.04]
1624 JSON::Patch
1626 [Author: MIXAS <https://metacpan.org/author/MIXAS>; Date:
1627 "2018-10-25"; Version: 0.04]
1628 ๐ 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 JSON::Path
1635 [โญ Author: POPEFELIX <https://metacpan.org/author/POPEFELIX>;
1636 Date: "2021-01-28"; Version: 0.431]
1637 Search nested hashref/arrayref structures using JSONPath.
1639 JSON::Pointer
1641 [โญ Author: ZIGOROU <https://metacpan.org/author/ZIGOROU>;
1642 Date: "2015-08-13"; Version: 0.07]
1643 Extract parts of a JSON string.
1645 JSON::Schema::ToJSON
1647 [โญ Author: LEEJO <https://metacpan.org/author/LEEJO>; Date:
1648 "2021-04-06"; Version: 0.19]
1649 "Generate example JSON structures from JSON Schema definitions"
1651 JSON::T
1653 [โญ Author: TOBYINK <https://metacpan.org/author/TOBYINK>;
1654 Date: "2014-09-28"; Version: 0.104]
1655 Transform JSON using JsonT
1657 JSON::Transform
1659 [โญ Author: ETJ <https://metacpan.org/author/ETJ>; Date:
1660 "2020-01-01"; Version: 0.03]
1661 JSON::Validator
1663 [โญโญ Author: JHTHORSEN
1664 <https://metacpan.org/author/JHTHORSEN>; Date: "2021-04-28";
1665 Version: 4.17]
1666 "Validate data against a JSON schema" - you can decide what the
1668 JSON is supposed to contain.
1669 Template::Plugin::JSON
1671 [Author: ETHER <https://metacpan.org/author/ETHER>; Date:
1672 "2019-03-07"; Version: 0.08]
1673 "Adds a .json vmethod for all TT values." - for use with
1675 Template.
1676 JSON extensions
1678 These modules extend JSON with comments and other things.
1679 JSON::Diffable
1681 [โญ Author: PHAYLON <https://metacpan.org/author/PHAYLON>;
1682 Date: "2014-12-10"; Version: 0.000002]
1683 "A relaxed and easy diffable JSON variant"
1685 JSON::Relaxed
1687 [Author: MIKO <https://metacpan.org/author/MIKO>; Date:
1688 "2016-04-30"; Version: 0.05]
1689 "An extension of JSON that allows for better human-
1691 readability".
1692 JSON::WithComments
1694 [Author: RJRAY <https://metacpan.org/author/RJRAY>; Date:
1695 "2017-09-02"; Version: 0.003]
1696 JSONY
1698 [โญ Author: INGY <https://metacpan.org/author/INGY>; Date:
1699 "2020-04-27"; Version: "v0.1.21"]
1700 "Relaxed JSON with a little bit of YAML"
1702 Web interactions via JSON
1704 Crypt::JWT
1705 [โญโญ Author: MIK <https://metacpan.org/author/MIK>; Date:
1706 "2021-05-01"; Version: 0.033]
1707 Module covers JSON Web Tokens, JSON Web Signature, and JSON Web
1709 Encryption.
1710 JSON::API
1712 [โญ Author: GFRANKS <https://metacpan.org/author/GFRANKS>;
1713 Date: "2019-07-01"; Version: "v1.1.1"]
1714 Combines LWP::UserAgent and JSON to make a unified module to
1716 communicate with a web server via JSON.
1717 LWP::JSON::Tiny
1719 [โญ Author: SKINGTON <https://metacpan.org/author/SKINGTON>;
1720 Date: "2018-05-11"; Version: 0.014]
1721 WWW::JSON
1723 [โญ Author: ANTIPASTA <https://metacpan.org/author/ANTIPASTA>;
1724 Date: "2015-05-27"; Version: 1.02]
1725 "Make working with JSON Web API's as painless as possible"
1727 Extension modules
1729 These modules extend the existing modules with some extra bits.
1730 JSON::XS::Sugar
1732 [Author: MAXMIND <https://metacpan.org/author/MAXMIND>; Date:
1733 "2015-04-01"; Version: 1.01]
1734 Provides booleans and number/string forcing for "JSON::XS".
1736 Silki::JSON
1738 [โญ Author: DROLSKY <https://metacpan.org/author/DROLSKY>;
1739 Date: "2011-09-19"; Version: 0.29]
1740 Switches on formatting and strict utf8 in a "JSON::XS" object.
1742 Demonstration modules
1744 These modules provide a JSON parser as a demonstration of another
1745 technology.
1746 JSON::Decode::Marpa
1748 [Author: PERLANCAR <https://metacpan.org/author/PERLANCAR>;
1749 Date: "2014-08-27"; Version: 0.02]
1750 JSON::Decode::Regexp
1752 [Author: PERLANCAR <https://metacpan.org/author/PERLANCAR>;
1753 Date: "2018-03-25"; Version: 0.101]
1754 ๐๐ฆ๐ฆ๐ 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 MarpaX::Demo::JSONParser
1766 [Author: RSAVAGE <https://metacpan.org/author/RSAVAGE>; Date:
1767 "2019-06-18"; Version: 1.08]
1768 Pegex::JSON
1770 [Author: INGY <https://metacpan.org/author/INGY>; Date:
1771 "2020-01-22"; Version: 0.31]
1772 ๐ Based on Pegex. See our bug report
1774 <https://github.com/pegex-parser/pegex-json-pm/issues/3>.
1775 Other modules
1777 Modules which are parts of bigger distributions have not been
1778 included here except by accident.
1779 App::JSON::Tools
1781 [Author: KABLAMO <https://metacpan.org/author/KABLAMO>; Date:
1782 "2016-08-05"; Version: 0.01]
1783 Undocumented command-line tools for JSON.
1785 App::JSONPretty
1787 [โญ Author: MSTROUT <https://metacpan.org/author/MSTROUT>;
1788 Date: "2011-02-02"; Version: 1]
1789 ๐๐ 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 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 ARGV::JSON
1800 [โญ Author: MOTEMEN <https://metacpan.org/author/MOTEMEN>;
1801 Date: "2013-12-18"; Version: 0.01]
1802 Jasonify
1804 [Author: BOBK <https://metacpan.org/author/BOBK>; Date:
1805 "2020-03-04"; Version: "v0.20.064"]
1806 JS::JSON
1808 [Author: INGY <https://metacpan.org/author/INGY>; Date:
1809 "2008-08-30"; Version: 0.02]
1810 ๐ 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 JSON::Eval
1816 [Author: TOBYINK <https://metacpan.org/author/TOBYINK>; Date:
1817 "2019-10-27"; Version: 0.002]
1818 Eval Perl code found in JSON. This module enables one to encode
1820 and decode Perl scalar references and code references to JSON.
1821 JSON::ize
1823 [โญ Author: MAJENSEN <https://metacpan.org/author/MAJENSEN>;
1824 Date: "2019-07-13"; Version: 0.202]
1825 JSON::JSend
1827 [Author: HOEKIT <https://metacpan.org/author/HOEKIT>; Date:
1828 "2016-04-23"; Version: 0.02]
1829 JSON::Lines
1831 [โญ Author: LNATION <https://metacpan.org/author/LNATION>;
1832 Date: "2021-03-29"; Version: 1.00]
1833 "JSON Lines is a convenient format for storing structured data
1835 that may be processed one record at a time."
1836 JSON::Meth
1838 [โญ Author: ZOFFIX <https://metacpan.org/author/ZOFFIX>; Date:
1839 "2015-11-28"; Version: 1.001007]
1840 ๐ Claims to be "no nonsense JSON encoding/decoding as method
1842 calls on data". From the documentation:
1843 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 JSON::ON
1850 [Author: EWILHELM <https://metacpan.org/author/EWILHELM>; Date:
1851 "2013-06-26"; Version: "v0.0.3"]
1852 JavaScript object notation object notator.
1854 JSON::SL
1856 [โญ Author: MNUNBERG <https://metacpan.org/author/MNUNBERG>;
1857 Date: "2017-11-10"; Version: "v1.0.7"]
1858 JSON::Streaming::Reader
1860 [โญ Author: MART <https://metacpan.org/author/MART>; Date:
1861 "2012-11-24"; Version: 0.06]
1862 JSON::Streaming::Writer
1864 [Author: MART <https://metacpan.org/author/MART>; Date:
1865 "2012-11-24"; Version: 0.03]
1866 JSON::Util
1868 [Author: JKUTEJ <https://metacpan.org/author/JKUTEJ>; Date:
1869 "2015-09-03"; Version: 0.06]
1870 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 JSON::XS::ByteString
1879 [โญ Author: CINDY <https://metacpan.org/author/CINDY>; Date:
1880 "2020-04-18"; Version: 1.004]
1881 ๐ 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 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 JSON_minify
1899 [Author: RCOSCALI <https://metacpan.org/author/RCOSCALI>; Date:
1900 "2021-01-24"; Version: 1.1]
1901 Text::JSON::Nibble
1903 [Author: DAEMON <https://metacpan.org/author/DAEMON>; Date:
1904 "2017-05-02"; Version: 1.01]
1905 Nibble complete JSON objects from buffers.
1907 This seems to be for extracting JSON from the midst of noise.
1909
1911 A script "validjson" is supplied with the module. This runs
1912 "assert_valid_json" on its inputs, so run it like this.
1913 validjson *.json
1915 The default behaviour is to just do nothing if the input is valid. For
1917 invalid input it prints what the problem is:
1918 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 If you need confirmation, use its --verbose option:
1923 validjson -v *.json
1925 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
1933 Carp
1934
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 All of the functions can be exported using the tag ':all':
1942 use JSON::Parse ':all';
1944
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 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 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 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 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 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 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 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
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
2028 Ben Bullock, <bkb@cpan.org>
2029
2031 This package and associated files are copyright (C) 2013-2022 Ben
2032 Bullock.
2033 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.
2037perl v5.36.0 2023-01-20 JSON::Parse(3)