1JSON::Parse(3) User Contributed Perl Documentation JSON::Parse(3)
2
6 JSON::Parse - Read JSON into a Perl variable
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.57 of JSON::Parse corresponding to git commit
18 42e099ed38a3e85daed46f53bf367fa2b828e152
19 <https://github.com/benkasminbullock/JSON-
20 Parse/commit/42e099ed38a3e85daed46f53bf367fa2b828e152> released on Thu
21 Jul 9 07:16:33 2020 +0900.
22
24 A module for parsing JSON. (JSON means "JavaScript Object Notation" and
25 it is specified in "RFC 7159".)
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 "json_file_to_perl" reads JSON from a file,
33 and there is a safer version of "parse_json" called "parse_json_safe"
34 which doesn't throw exceptions.
35 For special cases of parsing, there are also methods "new" and "run",
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 parse_json
44 use JSON::Parse 'parse_json';
45 my $perl = parse_json ('{"x":1, "y":2}');
46 This function converts JSON into a Perl structure, either an array
48 reference, a hash reference, or a scalar.
49 If the first argument does not contain a complete valid JSON text, is
51 the undefined value, an empty string, or a string containing only
52 whitespace "parse_json" throws a fatal error ("dies").
53 If the argument contains valid JSON, the return value is either a hash
55 reference, an array reference, or a scalar. If the input JSON text is a
56 serialized object, a hash reference is returned:
57 use JSON::Parse ':all';
59 my $perl = parse_json ('{"a":1, "b":2}');
60 print ref $perl, "\n";
61 produces output
63 HASH
65 (This example is included as hash.pl
67 <https://fastapi.metacpan.org/source/BKB/JSON-
68 Parse-0.57/examples/hash.pl> in the distribution.)
69 If the input JSON text is a serialized array, an array reference is
71 returned:
72 use JSON::Parse ':all';
74 my $perl = parse_json ('["a", "b", "c"]');
75 print ref $perl, "\n";
76 produces output
78 ARRAY
80 (This example is included as array.pl
82 <https://fastapi.metacpan.org/source/BKB/JSON-
83 Parse-0.57/examples/array.pl> in the distribution.)
84 Otherwise a Perl scalar is returned.
86 The behaviour of allowing a scalar was added in version 0.32 of this
88 module. This brings it into line with the new specification for JSON.
89 The behaviour of disallowing empty inputs was changed in version 0.49.
90 This makes it conform to the "JSON Parsing Test Suite".
91 The function "parse_json_safe" offers a version of this function with
93 various safety features enabled.
94 json_file_to_perl
96 use JSON::Parse 'json_file_to_perl';
97 my $p = json_file_to_perl ('filename');
98 This is exactly the same as "parse_json" except that it reads the JSON
100 from the specified file rather than a scalar. The file must be in the
101 UTF-8 encoding, and is opened as a character file using
102 ":encoding(UTF-8)" (see PerlIO::encoding and perluniintro for details).
103 The output is marked as character strings.
104 This is a convenience function written in Perl. You may prefer to read
106 the file yourself using another module if you need faster performance.
107 valid_json
109 use JSON::Parse 'valid_json';
110 if (valid_json ($json)) {
111 # do something
112 }
113 "valid_json" returns 1 if its argument is valid JSON and 0 if not. It
115 runs several times faster than "parse_json". This gain in speed is
116 obtained because it discards the input data after reading it, rather
117 than storing it into Perl variables.
118 This does not supply the actual errors which caused invalidity. Use
120 "assert_valid_json" to get error messages when the JSON is invalid.
121 This cannot detect key collisions in the JSON since it does not store
123 values. See "Key collisions" for more on this module's handling of non-
124 unique names in the JSON.
125 assert_valid_json
127 use JSON::Parse 'assert_valid_json';
128 eval {
129 assert_valid_json ('["xyz":"b"]');
130 };
131 if ($@) {
132 print "Your JSON was invalid: $@\n";
133 }
134 # Prints "Unexpected character ':' parsing array"
135 produces output
137 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/Json3/examples/assert.pl line 6.
139 (This example is included as assert.pl
141 <https://fastapi.metacpan.org/source/BKB/JSON-
142 Parse-0.57/examples/assert.pl> in the distribution.)
143 This is the underlying function for "valid_json". It runs at the same
145 speed, but it throws an error if the JSON is wrong, rather than
146 returning 1 or 0. See "DIAGNOSTICS" for the error format, which is
147 identical to "parse_json".
148 This cannot detect key collisions in the JSON since it does not store
150 values. See "Key collisions" for more on this module's handling of non-
151 unique names in the JSON.
152 The behaviour of disallowing empty inputs was changed in version 0.49.
154 This makes it conform to the "JSON Parsing Test Suite", and also makes
155 it give identical results to "valid_json".
156 parse_json_safe
158 This is almost the same thing as "parse_json", but has the following
159 differences:
160 Does not throw exceptions
162 If the JSON is invalid, a warning is printed and the undefined
163 value is returned, as if calling "parse_json" like this:
164 eval {
166 $out = parse_json ($json);
167 };
168 if ($@) {
169 carp $@;
170 $out = undef;
171 }
172 Detects key collisions
174 This switches on "detect_collisions", so that if the JSON contains
175 non-unique names, a warning is printed and the undefined value is
176 returned. See "Key collisions" for an explanation of what a key
177 collision is.
178 Booleans are not read-only
180 This switches on "copy_literals" so that JSON true, false and null
181 values are copied. These values can be modified, but they will not
182 be converted back into "true" and "false" by JSON::Create.
183 Errors are reported by carp
185 Parsing errors are reported by "carp" in Carp, so the error line
186 number refers to the caller's line.
187 As the name implies, this is meant to be a "safety-first" version of
189 "parse_json". This function does not pass all of the tests of the "JSON
190 Parsing Test Suite", because it creates an error for duplicate keys in
191 objects, which is legal JSON. See t/jpts.t for details.
192 This function was added in version 0.38.
194
196 The following alternative function names are accepted. These are the
197 names used for the functions in old versions of this module. These
198 names are not deprecated and will never be removed from the module.
199 json_to_perl
201 This is exactly the same function as "parse_json".
202 validate_json
204 This is exactly the same function as "assert_valid_json".
205
207 JSON elements are mapped to Perl as follows:
208 JSON numbers
210 JSON numbers become Perl numbers, either integers or double-precision
211 floating point numbers, or possibly strings containing the number if
212 parsing of a number by the usual methods fails somehow.
213 JSON does not allow leading zeros, like 0123, or leading plus signs,
215 like +100, in numbers, so these cause an "Unexpected character" error.
216 JSON also does not allow numbers of the form 1., but it does allow
217 things like 0e0 or 1E999999. As far as possible these are accepted by
218 JSON::Parse.
219 JSON strings
221 JSON strings become Perl strings. The JSON escape characters such as
222 "\t" for the tab character (see section 2.5 of "RFC 7159") are mapped
223 to the equivalent ASCII character.
224 Handling of Unicode
226 Inputs must be in the UTF-8 format. See "UTF-8 only".
228 If the input to "parse_json" is marked as Unicode characters, the
230 output strings will be marked as Unicode characters. If the input is
231 not marked as Unicode characters, the output strings will not be marked
232 as Unicode characters. Thus,
233 use JSON::Parse ':all';
235 # The scalar $sasori looks like Unicode to Perl
236 use utf8;
237 my $sasori = '["蠍"]';
238 my $p = parse_json ($sasori);
239 print utf8::is_utf8 ($p->[0]);
240 # Prints 1.
241 but
243 use JSON::Parse ':all';
245 # The scalar $ebi does not look like Unicode to Perl
246 no utf8;
247 my $ebi = '["海老"]';
248 my $p = parse_json ($ebi);
249 print utf8::is_utf8 ($p->[0]);
250 # Prints nothing.
251 Escapes of the form \uXXXX (see page three of "RFC 7159") are mapped to
253 ASCII if XXXX is less than 0x80, or to UTF-8 if XXXX is greater than or
254 equal to 0x80.
255 Strings containing \uXXXX escapes greater than 0x80 are also upgraded
257 to character strings, regardless of whether the input is a character
258 string or a byte string, thus regardless of whether Perl thinks the
259 input string is Unicode, escapes like \u87f9 are converted into the
260 equivalent UTF-8 bytes and the particular string in which they occur is
261 marked as a character string:
262 use JSON::Parse ':all';
264 no utf8;
265 # 蟹
266 my $kani = '["\u87f9"]';
267 my $p = parse_json ($kani);
268 print "It's marked as a character string" if utf8::is_utf8 ($p->[0]);
269 # Prints "It's marked as a character string" because it's upgraded
270 # regardless of the input string's flags.
271 This is modelled on the behaviour of Perl's "chr":
273 no utf8;
275 my $kani = '87f9';
276 print "hex is character string\n" if utf8::is_utf8 ($kani);
277 # prints nothing
278 $kani = chr (hex ($kani));
279 print "chr makes it a character string\n" if utf8::is_utf8 ($kani);
280 # prints "chr makes it a character string"
281 However, JSON::Parse also upgrades the remaining part of the string
283 into a character string, even when it's not marked as a character
284 string. For example,
285 use JSON::Parse ':all';
287 use Unicode::UTF8 'decode_utf8';
288 no utf8;
289 my $highbytes = "か";
290 my $not_utf8 = "$highbytes\\u3042";
291 my $test = "{\"a\":\"$not_utf8\"}";
292 my $out = parse_json ($test);
293 # JSON::Parse does something unusual here in promoting the first part
294 # of the string into UTF-8.
295 print "JSON::Parse gives this: ", $out->{a}, "\n";
296 # Perl cannot assume that $highbytes is in UTF-8, so it has to just
297 # turn the initial characters into garbage.
298 my $add_chr = $highbytes . chr (0x3042);
299 print "Perl's output is like this: ", $add_chr, "\n";
300 # In fact JSON::Parse's behaviour is equivalent to this:
301 my $equiv = decode_utf8 ($highbytes) . chr (0x3042);
302 print "JSON::Parse did something like this: ", $equiv, "\n";
303 # With character strings switched on, Perl and JSON::Parse do the same
304 # thing.
305 use utf8;
306 my $is_utf8 = "か";
307 my $test2 = "{\"a\":\"$is_utf8\\u3042\"}";
308 my $out2 = parse_json ($test2);
309 print "JSON::Parse: ", $out2->{a}, "\n";
310 my $add_chr2 = $is_utf8 . chr (0x3042);
311 print "Native Perl: ", $add_chr2, "\n";
312 produces output
314 JSON::Parse gives this: かあ
316 Perl's output is like this: ãあ
317 JSON::Parse did something like this: かあ
318 JSON::Parse: かあ
319 Native Perl: かあ
320 (This example is included as unicode-details.pl
322 <https://fastapi.metacpan.org/source/BKB/JSON-
323 Parse-0.57/examples/unicode-details.pl> in the distribution.)
324 Although in general the above would be an unsafe practice, JSON::Parse
326 can do things this way because JSON is a text-only, Unicode-only
327 format. To ensure that invalid inputs are never upgraded, JSON::Parse
328 checks each input byte to make sure that it forms UTF-8. See also
329 "UTF-8 only". Doing things this way, rather than the way that Perl does
330 it, was one of the original motivations for writing this module. See
331 also "HISTORY".
332 Surrogate pairs in the form "\uD834\uDD1E" are also handled. If the
334 second half of the surrogate pair is missing, an "Unexpected character"
335 or "Unexpected end of input" error is thrown. If the second half of the
336 surrogate pair is present but contains an impossible value, a "Not
337 surrogate pair" error is thrown.
338 JSON arrays
340 JSON arrays become Perl array references. The elements of the Perl
341 array are in the same order as they appear in the JSON.
342 Thus
344 my $p = parse_json ('["monday", "tuesday", "wednesday"]');
346 has the same result as a Perl declaration of the form
348 my $p = [ 'monday', 'tuesday', 'wednesday' ];
350 JSON objects
352 JSON objects become Perl hashes. The members of the JSON object become
353 key and value pairs in the Perl hash. The string part of each object
354 member becomes the key of the Perl hash. The value part of each member
355 is mapped to the value of the Perl hash.
356 Thus
358 my $j = <<EOF;
360 {"monday":["blue", "black"],
361 "tuesday":["grey", "heart attack"],
362 "friday":"Gotta get down on Friday"}
363 EOF
364 my $p = parse_json ($j);
366 has the same result as a Perl declaration of the form
368 my $p = {
370 monday => ['blue', 'black'],
371 tuesday => ['grey', 'heart attack'],
372 friday => 'Gotta get down on Friday',
373 };
374 Key collisions
376 A key collision is something like the following.
378 use JSON::Parse qw/parse_json parse_json_safe/;
380 my $j = '{"a":1, "a":2}';
381 my $p = parse_json ($j);
382 print "Ambiguous key 'a' is ", $p->{a}, "\n";
383 my $q = parse_json_safe ($j);
384 produces output
386 JSON::Parse::parse_json_safe: JSON error at line 1, byte 10/14: Name is not unique: "a" parsing object starting from byte 1 at /usr/home/ben/projects/Json3/examples/key-collision.pl line 8.
388 Ambiguous key 'a' is 2
389 (This example is included as key-collision.pl
391 <https://fastapi.metacpan.org/source/BKB/JSON-Parse-0.57/examples/key-
392 collision.pl> in the distribution.)
393 Here the key "a" could be either 1 or 2. As seen in the example,
395 "parse_json" overwrites the first value with the second value.
396 "parse_json_safe" halts and prints a warning. If you use "new" you can
397 switch key collision on and off with the "detect_collisions" method.
398 The rationale for "parse_json" not to give warnings is that Perl
400 doesn't give information about collisions when storing into hash
401 values, and checking for collisions for every key will degrade
402 performance for the sake of an unlikely occurrence. The JSON
403 specification says "The names within an object SHOULD be unique." (see
404 "RFC 7159", page 5), although it's not a requirement.
405 For performance, "valid_json" and "assert_valid_json" do not store hash
407 keys, thus they cannot detect this variety of problem.
408 Literals
410 null
411 "parse_json" maps the JSON null literal to a readonly scalar
413 $JSON::Parse::null which evaluates to "undef". "parse_json_safe" maps
414 the JSON literal to the undefined value. If you use a parser created
415 with "new", you can choose either of these behaviours with
416 "copy_literals", or you can tell JSON::Parse to put your own value in
417 place of nulls using the "set_null" method.
418 true
420 "parse_json" maps the JSON true literal to a readonly scalar which
422 evaluates to 1. "parse_json_safe" maps the JSON literal to the value 1.
423 If you use a parser created with "new", you can choose either of these
424 behaviours with "copy_literals", or you can tell JSON::Parse to put
425 your own value in place of trues using the "set_true" method.
426 false
428 "parse_json" maps the JSON false literal to a readonly scalar which
430 evaluates to the empty string, or to zero in a numeric context. (This
431 behaviour changed from version 0.36 to 0.37. In versions up to 0.36,
432 the false literal was mapped to a readonly scalar which evaluated to 0
433 only.) "parse_json_safe" maps the JSON literal to a similar scalar
434 without the readonly constraints. If you use a parser created with
435 "new", you can choose either of these behaviours with "copy_literals",
436 or you can tell JSON::Parse to put your own value in place of falses
437 using the "set_false" method.
438 Round trips and compatibility
440 The Perl versions of literals produced by "parse_json" will be
442 converted back to JSON literals if you use "create_json" in
443 JSON::Create. However, JSON::Parse's literals are incompatible with the
444 other CPAN JSON modules. For compatibility with other CPAN modules,
445 create a JSON::Parse object with "new", and set JSON::Parse's literals
446 with "set_true", "set_false", and "set_null".
447 This example demonstrates round-trip compatibility using JSON::Tiny
449 version 0.54:
450 use JSON::Tiny '0.54', qw(decode_json encode_json);
452 use JSON::Parse;
453 use JSON::Create;
454 my $cream = '{"clapton":true,"hendrix":false,"bruce":true,"fripp":false}';
455 my $jp = JSON::Parse->new ();
456 my $jc = JSON::Create->new ();
457 print "First do a round-trip of our modules:\n\n";
458 print $jc->run ($jp->run ($cream)), "\n\n";
459 print "Now do a round-trip of JSON::Tiny:\n\n";
460 print encode_json (decode_json ($cream)), "\n\n";
461 print "First, incompatible mode:\n\n";
462 print 'tiny(parse): ', encode_json ($jp->run ($cream)), "\n";
463 print 'create(tiny): ', $jc->run (decode_json ($cream)), "\n\n";
464 $jp->set_true (JSON::Tiny::true);
465 $jp->set_false (JSON::Tiny::false);
466 print "Compatibility with JSON::Parse:\n\n";
467 print 'tiny(parse):', encode_json ($jp->run ($cream)), "\n\n";
468 $jc->bool ('JSON::Tiny::_Bool');
469 print "Compatibility with JSON::Create:\n\n";
470 print 'create(tiny):', $jc->run (decode_json ($cream)), "\n\n";
471 print "JSON::Parse and JSON::Create are still compatible too:\n\n";
472 print $jc->run ($jp->run ($cream)), "\n";
473 produces output
475 First do a round-trip of our modules:
477 {"hendrix":false,"clapton":true,"fripp":false,"bruce":true}
479 Now do a round-trip of JSON::Tiny:
481 {"bruce":true,"clapton":true,"fripp":false,"hendrix":false}
483 First, incompatible mode:
485 tiny(parse): {"bruce":1,"clapton":1,"fripp":"","hendrix":""}
487 create(tiny): {"fripp":0,"bruce":1,"clapton":1,"hendrix":0}
488 Compatibility with JSON::Parse:
490 tiny(parse):{"bruce":true,"clapton":true,"fripp":false,"hendrix":false}
492 Compatibility with JSON::Create:
494 create(tiny):{"hendrix":false,"fripp":false,"bruce":true,"clapton":true}
496 JSON::Parse and JSON::Create are still compatible too:
498 {"fripp":false,"bruce":true,"clapton":true,"hendrix":false}
500 (This example is included as json-tiny-round-trip-demo.pl
502 <https://fastapi.metacpan.org/source/BKB/JSON-Parse-0.57/examples/json-
503 tiny-round-trip-demo.pl> in the distribution.)
504 Most of the other CPAN modules use similar methods to JSON::Tiny, so
506 the above example can easily be adapted. See also "Interoperability" in
507 JSON::Create for various examples.
508 Modifying the values
510 "parse_json" maps all the literals to read-only values. Because of
512 this, attempting to modifying the boolean values in the hash reference
513 returned by "parse_json" will cause "Modification of a read-only value
514 attempted" errors:
515 my $in = '{"hocus":true,"pocus":false,"focus":null}';
517 my $p = json_parse ($in);
518 $p->{hocus} = 99;
519 # "Modification of a read-only value attempted" error occurs
520 Since the hash values are read-only scalars, "$p->{hocus} = 99" is like
522 this:
523 undef = 99;
525 If you need to modify the returned hash reference, then delete the
527 value first:
528 my $in = '{"hocus":true,"pocus":false,"focus":null}';
530 my $p = json_parse ($in);
531 delete $p->{pocus};
532 $p->{pocus} = 99;
533 # OK
534 Similarly with array references, delete the value before altering:
536 my $in = '[true,false,null]';
538 my $q = json_parse ($in);
539 delete $q->[1];
540 $q->[1] = 'magic';
541 Note that the return values from parsing bare literals are not read-
543 only scalars, so
544 my $true = JSON::Parse::json_parse ('true');
546 $true = 99;
547 produces no error. This is because Perl copies the scalar.
549
551 If you need to parse JSON and you are not satisfied with the parsing
552 options offered by "parse_json" and "parse_json_safe", you can create a
553 JSON parsing object with "new" and set various options on the object,
554 then use it with "run". These options include the ability to copy JSON
555 literals with "copy_literals", switch off fatal errors with
556 "warn_only", detect key collisions in objects with "detect_collisions",
557 and set the JSON literals to user defined values with the methods
558 described under "Methods for manipulating literals".
559 These methods only work on an object created with "new"; they do not
561 affect the behaviour of "parse_json" or "parse_json_safe".
562 new
564 my $jp = JSON::Parse->new ();
565 Create a new JSON::Parse object.
567 This method was added in version 0.38.
569 run
571 my $out = $jp->run ($json);
572 This does the same thing as "parse_json", except its behaviour can be
574 modified using the methods below.
575 This method was added in version 0.38.
577 check
579 eval {
580 $jp->check ($json);
581 };
582 This does the same thing as "assert_valid_json", except its behaviour
584 can be modified using the methods below. Only the "diagnostics_hash"
585 method will actually affect this.
586 This method was added in version 0.48, for the benefit of JSON::Repair.
588 copy_literals
590 $jp->copy_literals (1);
591 With a true value, copy JSON literal values ("null", "true", and
593 "false") into new Perl scalar values, and don't put read-only values
594 into the output.
595 With a false value, use read-only scalars:
597 $jp->copy_literals (0);
599 The "copy_literals (1)" behaviour is the behaviour of
601 "parse_json_safe". The "copy_literals (0)" behaviour is the behaviour
602 of "parse_json".
603 If the user also sets user-defined literals with "set_true",
605 "set_false" and "set_null", that takes precedence over this.
606 This method was added in version 0.38.
608 warn_only
610 $jp->warn_only (1);
611 Warn, don't die, on error. Failed parsing returns the undefined value,
613 "undef", and prints a warning.
614 This can be switched off again using any false value:
616 $jp->warn_only ('');
618 This method was documented in version 0.38, but only implemented in
620 version 0.41.
621 detect_collisions
623 $jp->detect_collisions (1);
624 This switches on a check for hash key collisions (non-unique names in
626 JSON objects). If a collision is found, an error message "Name is not
627 unique" is printed, which also gives the non-unique name and the byte
628 position where the start of the colliding string was found:
629 use JSON::Parse;
631 my $jp = JSON::Parse->new ();
632 $jp->detect_collisions (1);
633 eval {
634 $jp->run ('{"animals":{"cat":"moggy","cat":"feline","cat":"neko"}}');
635 };
636 print "$@\n" if $@;
637 produces output
639 JSON error at line 1, byte 28/55: Name is not unique: "cat" parsing object starting from byte 12 at /usr/home/ben/projects/Json3/blib/lib/JSON/Parse.pm line 103.
641 (This example is included as collide.pl
643 <https://fastapi.metacpan.org/source/BKB/JSON-
644 Parse-0.57/examples/collide.pl> in the distribution.)
645 The "detect_collisions (1)" behaviour is the behaviour of
647 "parse_json_safe". The "detect_collisions (0)" behaviour is the
648 behaviour of "parse_json".
649 This method was added in version 0.38.
651 diagnostics_hash
653 $jp->diagnostics_hash (1);
654 This changes diagnostics produced by errors from a simple string into a
656 hash reference containing various fields. This is experimental and
657 subject to change. This is incompatible with "warn_only".
658 This replaces the previous experimental global variable
660 $json_diagnostics, which was removed from the module. The hash keys and
661 values are identical to those provided in the object returned by
662 $json_diagnostics, with the addition of a key "error as string" which
663 returns the usual error.
664 This requires Perl version 5.14 or later.
666 This method was added in version 0.46.
668 Methods for manipulating literals
670 These methods alter what is written into the Perl structure when the
671 parser sees a literal value, "true", "false" or "null" in the input
672 JSON.
673 This number of methods is unfortunately necessary, since it's possible
675 that a user might want to set_false (undef) to set false values to turn
676 into undefs.
677 $jp->set_false (undef);
679 Thus, we cannot use a single function "$jp->false (undef)" to cover
681 both setting and deleting of values.
682 These methods were added in version 0.38.
684 set_true
686 $jp->set_true ("Yes, that is so true");
688 Supply a scalar to be used in place of the JSON "true" literal.
690 This example puts the string "Yes, that is so true" into the hash or
692 array when we hit a "true" literal, rather than the default read-only
693 scalar:
694 use JSON::Parse;
696 my $json = '{"yes":true,"no":false}';
697 my $jp = JSON::Parse->new ();
698 $jp->set_true ('Yes, that is so true');
699 my $out = $jp->run ($json);
700 print $out->{yes}, "\n";
701 prints
703 Yes, that is so true
705 To override the previous value, call it again with a new value. To
707 delete the value and revert to the default behaviour, use
708 "delete_true".
709 If you give this a value which is not "true", as in Perl will evaluate
711 it as a false in an if statement, it prints a warning "User-defined
712 value for JSON true evaluates as false". You can switch this warning
713 off with "no_warn_literals".
714 This method was added in version 0.38.
716 delete_true
718 $jp->delete_true ();
720 Delete the user-defined true value. See "set_true".
722 This method is "safe" in that it has absolutely no effect if no user-
724 defined value is in place. It does not return a value.
725 This method was added in version 0.38.
727 set_false
729 $jp->set_false (JSON::PP::Boolean::false);
731 Supply a scalar to be used in place of the JSON "false" literal.
733 In the above example, when we hit a "false" literal, we put
735 "JSON::PP::Boolean::false" in the output, similar to JSON::PP and other
736 CPAN modules like Mojo::JSON or JSON::XS.
737 To override the previous value, call it again with a new value. To
739 delete the value and revert to the default behaviour, use
740 "delete_false".
741 If you give this a value which is not "false", as in Perl will evaluate
743 it as a false in an if statement, it prints a warning "User-defined
744 value for JSON false evaluates as true". You can switch this warning
745 off with "no_warn_literals".
746 This method was added in version 0.38.
748 delete_false
750 $jp->delete_false ();
752 Delete the user-defined false value. See "set_false".
754 This method is "safe" in that it has absolutely no effect if no user-
756 defined value is in place. It does not return a value.
757 This method was added in version 0.38.
759 set_null
761 $jp->set_null (0);
763 Supply a scalar to be used in place of the JSON "null" literal.
765 To override the previous value, call it again with a new value. To
767 delete the value and revert to the default behaviour, use
768 "delete_null".
769 This method was added in version 0.38.
771 delete_null
773 $jp->delete_null ();
775 Delete the user-defined null value. See "set_null".
777 This method is "safe" in that it has absolutely no effect if no user-
779 defined value is in place. It does not return a value.
780 This method was added in version 0.38.
782 no_warn_literals
784 $jp->no_warn_literals (1);
786 Use a true value to switch off warnings about setting boolean values to
788 contradictory things. For example if you want to set the JSON "false"
789 literal to turn into the string "false",
790 $jp->no_warn_literals (1);
792 $jp->set_false ("false");
793 See also "Contradictory values for "true" and "false"".
795 This also switches off the warning "User-defined value overrules
797 copy_literals".
798 This method was added in version 0.38.
800
802 This module imposes the following restrictions on its input.
803 JSON only
805 JSON::Parse is a strict parser. It only accepts input which exactly
806 meets the criteria of "RFC 7159". That means, for example,
807 JSON::Parse does not accept single quotes (') instead of double
808 quotes ("), or numbers with leading zeros, like 0123. JSON::Parse
809 does not accept control characters (0x00 - 0x1F) in strings,
810 missing commas between array or hash elements like "["a" "b"]", or
811 trailing commas like "["a","b","c",]". It also does not accept
812 trailing non-whitespace, like the second "]" in "["a"]]".
813 No incremental parsing
815 JSON::Parse does not parse incrementally. It only parses fully-
816 formed JSON strings which include all opening and closing brackets.
817 This is an inherent part of the design of the module. Incremental
818 parsing in the style of XML::Parser would (obviously) require some
819 kind of callback structure to deal with the elements of the
820 partially digested structures, but JSON::Parse was never designed
821 to do this; it merely converts what it sees into a Perl structure.
822 Claims to offer incremental JSON parsing in other modules'
823 documentation should be diligently verified.
824 UTF-8 only
826 Although JSON may come in various encodings of Unicode, JSON::Parse
827 only parses the UTF-8 format. If input is in a different Unicode
828 encoding than UTF-8, convert the input before handing it to this
829 module. For example, for the UTF-16 format,
830 use Encode 'decode';
832 my $input_utf8 = decode ('UTF-16', $input);
833 my $perl = parse_json ($input_utf8);
834 or, for a file, use ":encoding" (see PerlIO::encoding and
836 perluniintro):
837 open my $input, "<:encoding(UTF-16)", 'some-json-file';
839 JSON::Parse does not determine the nature of the octet stream, as
841 described in part 3 of "RFC 7159".
842 This restriction to UTF-8 applies regardless of whether Perl thinks
844 that the input string is a character string or a byte string.
845 Non-UTF-8 input will cause an "Unexpected character" error.
846
848 "valid_json" does not produce error messages. "parse_json" and
849 "assert_valid_json" die on encountering invalid input.
850 "parse_json_safe" uses "carp" in Carp to pass error messages as
851 warnings.
852 Error messages have the line number, and the byte number where
854 appropriate, of the input which caused the problem. The line number is
855 formed simply by counting the number of "\n" (linefeed, ASCII 0x0A)
856 characters in the whitespace part of the JSON.
857 In "parse_json" and "assert_valid_json", parsing errors are fatal, so
859 to continue after an error occurs, put the parsing into an "eval"
860 block:
861 my $p;
863 eval {
864 $p = parse_json ($j);
865 };
866 if ($@) {
867 # handle error
868 }
869 The following error messages are produced:
871 Unexpected character
873 An unexpected character (byte) was encountered in the input. For
874 example, when looking at the beginning of a string supposedly
875 containing JSON, if the module encounters a plus sign, it will give an
876 error like this:
877 assert_valid_json ('+');
879 gives output
881 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'
883 The message always includes a list of what characters are allowed.
885 If there is some recognizable structure being parsed, the error message
887 will include its starting point in the form "starting from byte n":
888 assert_valid_json ('{"this":"\a"}');
890 gives output
892 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'
894 A feature of JSON is that parsing it requires only one byte to be
896 examined at a time. Thus almost all parsing problems can be handled
897 using the "Unexpected character" error type, including spelling errors
898 in literals:
899 assert_valid_json ('[true,folse]');
901 gives output
903 JSON error at line 1, byte 8/12: Unexpected character 'o' parsing literal starting from byte 7: expecting 'a'
905 and the missing second half of a surrogate pair:
907 assert_valid_json ('["\udc00? <-- should be a second half here"]');
909 gives output
911 JSON error at line 1, byte 9/44: Unexpected character '?' parsing unicode escape starting from byte 3: expecting '\'
913 All kinds of errors can occur parsing numbers, for example a missing
915 fraction,
916 assert_valid_json ('[1.e9]');
918 gives output
920 JSON error at line 1, byte 4/6: Unexpected character 'e' parsing number starting from byte 2: expecting digit: '0-9'
922 and a leading zero,
924 assert_valid_json ('[0123]');
926 gives output
928 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'
930 The error message is this complicated because all of the following are
932 valid here: whitespace: "[0 ]"; comma: "[0,1]", end of array: "[0]",
933 dot: "[0.1]", or exponential: "[0e0]".
934 These are all handled by this error. Thus the error messages are a
936 little confusing as diagnostics.
937 Versions of this module prior to 0.29 gave more informative messages
939 like "leading zero in number". (The messages weren't documented.) The
940 reason to change over to the single message was because it makes the
941 parsing code simpler, and because the testing code described in
942 "TESTING" makes use of the internals of this error to check that the
943 error message produced actually do correspond to the invalid and valid
944 bytes allowed by the parser, at the exact byte given.
945 This is a bytewise error, thus for example if a miscoded UTF-8 appears
947 in the input, an error message saying what bytes would be valid at that
948 point will be printed.
949 no utf8;
951 use JSON::Parse 'assert_valid_json';
952 # Error in first byte:
954 my $bad_utf8_1 = chr (hex ("81"));
956 eval { assert_valid_json ("[\"$bad_utf8_1\"]"); };
957 print "$@\n";
958 # Error in third byte:
960 my $bad_utf8_2 = chr (hex ('e2')) . chr (hex ('9C')) . 'b';
962 eval { assert_valid_json ("[\"$bad_utf8_2\"]"); };
963 print "$@\n";
964 prints
966 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.
968 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.
970 Unexpected end of input
972 The end of the string was encountered before the end of whatever was
973 being parsed was. For example, if a quote is missing from the end of
974 the string, it will give an error like this:
975 assert_valid_json ('{"first":"Suzuki","second":"Murakami","third":"Asada}');
977 gives output
979 JSON error at line 1: Unexpected end of input parsing string starting from byte 47
981 Not surrogate pair
983 While parsing a string, a surrogate pair was encountered. While trying
984 to turn this into UTF-8, the second half of the surrogate pair turned
985 out to be an invalid value.
986 assert_valid_json ('["\uDC00\uABCD"]');
988 gives output
990 JSON error at line 1: Not surrogate pair parsing unicode escape starting from byte 11
992 Empty input
994 This error occurs for an input which is an empty (no length or
995 whitespace only) or an undefined value.
996 assert_valid_json ('');
998 gives output
1000 JSON error: Empty input parsing initial state
1002 Prior to version 0.49, this error was produced by "assert_valid_json"
1004 only, but it is now also produced by "parse_json". See "JSON Parsing
1005 Test Suite".
1006 Name is not unique
1008 This error occurs when parsing JSON when the user has chosen
1009 "detect_collisions". For example an input like
1010 my $p = JSON::Parse->new ();
1012 $p->detect_collisions (1);
1013 $p->run ('{"hocus":1,"pocus":2,"hocus":3}');
1014 gives output
1016 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 109.
1018 where the JSON object has two keys with the same name, "hocus". The
1020 terminology "name is not unique" is from the JSON specification.
1021 Contradictory values for "true" and "false"
1023 User-defined value for JSON false evaluates as true
1024 This happens if you set JSON false to map to a true value:
1026 $jp->set_false (1);
1028 To switch off this warning, use "no_warn_literals".
1030 This warning was added in version 0.38.
1032 User-defined value for JSON true evaluates as false
1034 This happens if you set JSON true to map to a false value:
1036 $jp->set_true (undef);
1038 To switch off this warning, use "no_warn_literals".
1040 This warning was added in version 0.38.
1042 User-defined value overrules copy_literals
1044 This warning is given if you set up literals with "copy_literals" then
1045 you also set up your own true, false, or null values with "set_true",
1046 "set_false", or "set_null".
1047 This warning was added in version 0.38.
1049
1051 On the author's computer, the module's speed of parsing is
1052 approximately the same as JSON::XS, with small variations depending on
1053 the type of input. For validation, "valid_json" is faster than any
1054 other module known to the author, and up to ten times faster than
1055 JSON::XS.
1056 Some special types of input, such as floating point numbers containing
1058 an exponential part, like "1e09", seem to be about two or three times
1059 faster to parse with this module than with JSON::XS. In JSON::Parse,
1060 parsing of exponentials is done by the system's "strtod" function, but
1061 JSON::XS contains its own parser for exponentials, so these results may
1062 be system-dependent.
1063 At the moment the main place JSON::XS wins over JSON::Parse is in
1065 strings containing escape characters, where JSON::XS is about 10%
1066 faster on the module author's computer and compiler. As of version
1067 0.33, despite some progress in improving JSON::Parse, I haven't been
1068 able to fully work out the reason behind the better speed.
1069 There is some benchmarking code in the github repository under the
1071 directory "benchmarks" for those wishing to test these claims. The
1072 script benchmarks/bench <https://github.com/benkasminbullock/JSON-
1073 Parse/blob/42e099ed38a3e85daed46f53bf367fa2b828e152/benchmarks/bench>
1074 is an adaptation of the similar script in the JSON::XS distribution.
1075 The script benchmarks/pub-bench.pl
1076 <https://github.com/benkasminbullock/JSON-
1077 Parse/blob/42e099ed38a3e85daed46f53bf367fa2b828e152/benchmarks/pub-
1078 bench.pl> runs the benchmarks and prints them out as POD.
1079 The following benchmark tests used version 0.47 of JSON::Parse and
1081 version 3.03 of JSON::XS on Perl Version 18.2, compiled with Clang
1082 version 3.4.1 on FreeBSD 10.3. The files in the "benchmarks" directory
1083 of JSON::Parse. "short.json" and "long.json" are the benchmarks used by
1084 JSON::XS.
1085 short.json
1087 Repetitions: 10 x 100 = 1000
1088 --------------+------------+------------+
1089 module | 1/min | min |
1090 --------------|------------|------------|
1091 JP::valid | 776722.963 | 0.0000129 |
1092 JSON::Parse | 285326.803 | 0.0000350 |
1093 JSON::XS | 257319.264 | 0.0000389 |
1094 --------------+------------+------------+
1095 long.json
1097 Repetitions: 10 x 100 = 1000
1098 --------------+------------+------------+
1099 module | 1/min | min |
1100 --------------|------------|------------|
1101 JP::valid | 13985.675 | 0.0007150 |
1102 JSON::Parse | 5128.138 | 0.0019500 |
1103 JSON::XS | 5919.977 | 0.0016892 |
1104 --------------+------------+------------+
1105 words-array.json
1107 Repetitions: 10 x 100 = 1000
1108 --------------+------------+------------+
1109 module | 1/min | min |
1110 --------------|------------|------------|
1111 JP::valid | 285326.803 | 0.0000350 |
1112 JSON::Parse | 32589.775 | 0.0003068 |
1113 JSON::XS | 32263.877 | 0.0003099 |
1114 --------------+------------+------------+
1115 exp.json
1117 Repetitions: 10 x 100 = 1000
1118 --------------+------------+------------+
1119 module | 1/min | min |
1120 --------------|------------|------------|
1121 JP::valid | 128266.177 | 0.0000780 |
1122 JSON::Parse | 52626.148 | 0.0001900 |
1123 JSON::XS | 19849.995 | 0.0005038 |
1124 --------------+------------+------------+
1125 literals.json
1127 Repetitions: 10 x 100 = 1000
1128 --------------+------------+------------+
1129 module | 1/min | min |
1130 --------------|------------|------------|
1131 JP::valid | 313007.761 | 0.0000319 |
1132 JSON::Parse | 47180.022 | 0.0002120 |
1133 JSON::XS | 28826.832 | 0.0003469 |
1134 --------------+------------+------------+
1135 cpantesters.json
1137 Repetitions: 10 x 100 = 1000
1138 --------------+------------+------------+
1139 module | 1/min | min |
1140 --------------|------------|------------|
1141 JP::valid | 1398.241 | 0.0071518 |
1142 JSON::Parse | 211.734 | 0.0472291 |
1143 JSON::XS | 215.100 | 0.0464900 |
1144 --------------+------------+------------+
1145
1147 RFC 7159
1148 JSON is specified in RFC 7159 "The application/json Media Type for
1149 JavaScript Object Notation (JSON)"
1150 <http://www.ietf.org/rfc/rfc7159.txt>.
1151 json.org
1153 <http://json.org> is the website for JSON, authored by Douglas
1154 Crockford.
1155 JSON::Create
1157 JSON::Create is a companion module to JSON::Parse by the same
1158 author. As of version 0.08, I'm using it everywhere, but it should
1159 still be considered to be in a testing stage. Please feel free to
1160 try it out.
1161 JSON::Tokenize
1163 JSON::Tokenize is part of the JSON::Parse distribution, a tokenizer
1164 which reduces a JSON string to tokens. This makes the JSON::Parse
1165 tokenizer available to people who want to write their own JSON
1166 parsers.
1167 JSON::Repair
1169 JSON::Repair is an example module which demonstrates using
1170 JSON::Parse to apply some kinds of heuristics to repair "relaxed
1171 JSON" or otherwise broken JSON into compliant JSON.
1172 Other CPAN modules for parsing and producing JSON
1174 Reading and writing JSON
1175 JSON
1176 This calls on either JSON::PP or JSON::XS.
1177 JSON::PP
1179 This is part of the Perl core, installed when you install Perl.
1180 "PP" stands for "Pure Perl", which means it is in Perl-only
1181 without the XS (C-based) parsing. This is slower but may be
1182 necessary if you cannot install modules requiring a C compiler.
1183 JSON::XS
1185 This is an all-purpose JSON module in XS, which means it
1186 requires a C compiler to install.
1187 Cpanel::JSON::XS
1189 This is a fork of JSON::XS related to a disagreement about how
1190 to report bugs. Please see the module for details.
1191 JSON::DWIW
1193 "Does what I want" module.
1194 JSON::YAJL
1196 Wraps a C library called yajl.
1197 JSON::Util
1199 Relies on JSON::MaybeXS.
1200 Pegex::JSON
1202 Based on Pegex.
1203 JSON::Syck
1205 Takes advantage of a similarity between YAML (yet another
1206 markup language) and JSON to provide a JSON parser/producer
1207 using YAML::Syck.
1208 Inline::JSON
1210 Relies on "JSON".
1211 Glib::JSON
1213 Uses the JSON library from Glib, a library of C functions for
1214 the Linux GNOME desktop project.
1215 Mojo::JSON
1217 Part of the Mojolicious standalone web framework, "pure Perl"
1218 JSON reader/writer. As of version 6.25 of Mojolicious, this
1219 actually depends on "JSON::PP".
1220 JSON::Tiny
1222 This is a fork of "Mojo::JSON".
1223 File::JSON::Slurper
1225 Slurp a JSON file into a data structure, and the reverse. It
1226 relies on "JSON::MaybeXS".
1227 Special-purpose modules
1229 JSON::MultiValueOrdered and JSON::Tiny::Subclassable
1230 "JSON::MultiValueOrdered" is a special-purpose module for
1231 parsing JSON objects which have key collisions (something like
1232 "{"a":1,"a":2}") within objects.
1233 (JSON::Parse's handling of key collisions is discussed in "Key
1235 collisions" in this document.)
1236 boolean
1238 This module offers "true" and "false" literals similar to JSON.
1239 Devel::JSON
1241 For one-liners.
1242 App::JSON::to
1244 Convert JSON data to other formats.
1245 JSON::Color
1247 This module generates JSON, colorized with ANSI escape
1248 sequences.
1249 Config::JSON
1251 Configuration files in JSON
1252 JSON::String
1254 Automatically change a JSON string when a data structure
1255 changes.
1256 JSON::Builder
1258 Create JSON under memory limitations.
1259 JSON::Pointer
1261 Extract parts of a JSON string.
1262 Inline::JSON
1264 Include JSON in a Perl program.
1265 JSON::Path
1267 Search nested hashref/arrayref structures using JSONPath.
1268 Test-related modules
1270 Test::JSON
1271 This offers a way to compare two different JSON strings to see
1272 if they refer to the same object. As of version 0.11, it relies
1273 on "JSON::Any".
1274 Test::JSON::More
1276 JSON Test Utility. As of version 0.02, it relies on "JSON".
1277 Test::Deep::JSON
1279 Compare JSON with Test::Deep. As of version 0.03, it relies on
1280 "JSON".
1281 Type-related modules
1283 These untangle numbers, strings, and booleans into JSON types.
1284 JSON::Types
1286 JSON::TypeInference
1287 JSON::Typist
1288 JSON::Types::Flexible
1289 Combination modules
1290 These modules rely on more than one back-end module.
1291 JSON::MaybeXS
1293 A module which combines "Cpanel::JSON::XS", "JSON::XS", and
1294 "JSON::PP". The original "JSON" combines "JSON::XS" and
1295 "JSON::PP", so this prioritizes "Cpanel::JSON::XS".
1296 JSON::Any
1298 This module combines "JSON::DWIW", "JSON::XS" versions one and
1299 two, and "JSON::Syck".
1300 JSON::XS::VersionOneAndTwo
1302 A "combination module" which supports two different interfaces
1303 of "JSON::XS". However, JSON::XS is now onto version 3.
1304 Mojo::JSON::MaybeXS
1306 This pulls in "JSON::MaybeXS" instead of "Mojo::JSON".
1307 JSON extensions
1309 These modules extend JSON with comments and other things.
1310 JSON::Relaxed
1312 "An extension of JSON that allows for better human-
1313 readability".
1314 JSONY
1316 "Relaxed JSON with a little bit of YAML"
1317 JSON::Diffable
1319 "A relaxed and easy diffable JSON variant"
1320 Other modules
1322 App::JSON::Tools
1323 App::JSONPretty
1324 Eve::Json
1325 Haineko::JSON
1326 JBD::JSON
1327 JSON::JS
1328 JSON::Meth
1329 JSON::ON
1330 JSON::SL
1331 JSON::Streaming::Reader and JSON::Streaming::Writer
1332 JSON::XS::ByteString
1333 JSON::XS::Sugar
1334 Silki::JSON
1335 Text::JSON::Nibble
1336
1338 A script "validjson" is supplied with the module. This runs
1339 "assert_valid_json" on its inputs, so run it like this.
1340 validjson *.json
1342 The default behaviour is to just do nothing if the input is valid. For
1344 invalid input it prints what the problem is:
1345 validjson ids.go
1347 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'.
1348 If you need confirmation, use its --verbose option:
1350 validjson -v *.json
1352 atoms.json is valid JSON.
1354 ids.json is valid JSON.
1355 kanjidic.json is valid JSON.
1356 linedecomps.json is valid JSON.
1357 radkfile-radicals.json is valid JSON.
1358
1360 The CPAN testers results are at the usual place.
1361 The ActiveState test results are at
1363 <http://code.activestate.com/ppm/JSON-Parse/>.
1364
1366 Carp
1367
1369 The module exports nothing by default. Functions "parse_json",
1370 "parse_json_safe", "json_file_to_perl", "valid_json" and
1371 "assert_valid_json", as well as the old function names "validate_json"
1372 and "json_to_perl", can be exported on request.
1373 All of the functions can be exported using the tag ':all':
1375 use JSON::Parse ':all';
1377
1379 Internal testing code
1380 The module incorporates extensive testing related to the production of
1381 error messages and validation of input. Some of the testing code is
1382 supplied with the module in the /t/ subdirectory of the distribution.
1383 More extensive testing code is in the git repository. This is not
1385 supplied in the CPAN distribution. A script, randomjson.pl
1386 <https://github.com/benkasminbullock/JSON-
1387 Parse/blob/42e099ed38a3e85daed46f53bf367fa2b828e152/randomjson.pl>,
1388 generates a set number of bytes of random JSON and checks that the
1389 module's bytewise validation of input is correct. It does this by
1390 taking a valid fragment, then adding each possible byte from 0 to 255
1391 to see whether the module correctly identifies it as valid or invalid
1392 at that point, then randomly picking one of the valid bytes and adding
1393 it to the fragment and continuing the process until a complete valid
1394 JSON input is formed. The module has undergone about a billion
1395 repetitions of this test.
1396 This setup relies on a C file, json-random-test.c
1398 <https://github.com/benkasminbullock/JSON-
1399 Parse/blob/42e099ed38a3e85daed46f53bf367fa2b828e152/json-random-
1400 test.c>, which isn't in the CPAN distribution, and it also requires
1401 Json3.xs <https://github.com/benkasminbullock/JSON-
1402 Parse/blob/42e099ed38a3e85daed46f53bf367fa2b828e152/Json3.xs> to be
1403 edited to make the macro "TESTRANDOM" true (uncomment line 7 of the
1404 file). The testing code uses C setjmp/longjmp, so it's not guaranteed
1405 to work on all operating systems and is commented out for CPAN
1406 releases.
1407 A pure C version called random-test.c
1409 <https://github.com/benkasminbullock/JSON-
1410 Parse/blob/42e099ed38a3e85daed46f53bf367fa2b828e152/random-test.c> also
1411 exists. This applies exactly the same tests, and requires no Perl at
1412 all.
1413 If you're interested in testing your own JSON parser, the outputs
1415 generated by randomjson.pl <https://github.com/benkasminbullock/JSON-
1416 Parse/blob/42e099ed38a3e85daed46f53bf367fa2b828e152/randomjson.pl> are
1417 quite a good place to start. The default is to produce UTF-8 output,
1418 which looks pretty horrible since it tends to produce long strings of
1419 UTF-8 garbage. (This is because it chooses randomly from 256 bytes and
1420 the end-of-string marker """ has only a 1/256 chance of being chosen,
1421 so the strings tend to get long and messy). You can mess with the
1422 internals of JSON::Parse by setting MAXBYTE in json-common.c to 0x80,
1423 recompiling (you can ignore the compiler warnings), and running
1424 randomjson.pl again to get just ASCII random JSON things. This breaks
1425 the UTF-8 functionality of JSON::Parse, so please don't install that
1426 version.
1427 JSON Parsing Test Suite
1429 Version 0.48 passed all but two of the yes/no tests of the JSON Parsing
1430 Test Suite <https://github.com/nst/JSONTestSuite>. The first failure
1431 was that "assert_valid_json" did not mark a completely empty file
1432 <https://github.com/nst/JSONTestSuite/blob/master/test_parsing/n_structure_no_data.json>
1433 as invalid JSON, and the second was that "parse_json" did not mark a
1434 file containing a single space character
1435 <https://github.com/nst/JSONTestSuite/blob/master/test_parsing/n_single_space.json>
1436 as invalid json. The tests also revealed an inconsistency between
1437 "assert_valid_json" and "valid_json", which was reporting the
1438 completely empty file as invalid. Running these tests also revealed
1439 several bugs in the script validjson. All of these errors were amended
1440 in version 0.49.
1441 I attempted to include the JSON Parsing Test Suite tests in the
1443 module's tests, but some of the files (like 100,000 open arrays)
1444 actually cause crashes on some versions of Perl on some machines
1445 <http://fast-matrix.cpantesters.org/?dist=JSON-Parse%200.48_01>, so
1446 they're not really suitable for distribution. The tests are found,
1447 however, in the repository under xt/jpts.t
1448 <https://github.com/benkasminbullock/JSON-
1449 Parse/blob/42e099ed38a3e85daed46f53bf367fa2b828e152/xt/jpts.t> and the
1450 subdirectory xt/jpts <https://github.com/benkasminbullock/JSON-
1451 Parse/blob/42e099ed38a3e85daed46f53bf367fa2b828e152/xt/jpts>, so if you
1452 are interested in the results, please copy that and try it. There is
1453 also a test for the validjson script as xt/validjson.t
1454 <https://github.com/benkasminbullock/JSON-
1455 Parse/blob/42e099ed38a3e85daed46f53bf367fa2b828e152/xt/validjson.t> in
1456 the repository. These are author tests, so you may need to install
1457 extra modules to run them. These author tests are run automatically
1458 before any code is uploaded to CPAN.
1459
1461 See Changes <https://github.com/benkasminbullock/JSON-
1462 Parse/blob/42e099ed38a3e85daed46f53bf367fa2b828e152/Changes> in the
1463 distribution for a full list of changes.
1464 This module started out under the name "JSON::Argo". It was originally
1466 a way to escape from having to use the other JSON modules on CPAN. The
1467 biggest issue that I had with the other modules was the way that
1468 Unicode was handled. Insisting on the pure Perl method of dealing with
1469 JSON strings, which are required to be in Unicode anyway, seems to me
1470 little more than superstition, something like telling programmers not
1471 to step on cracks in the pavement. This module completely bypasses
1472 that. See "Handling of Unicode" for the details of how this module
1473 differs from the other modules.
1474 The reason it only parsed JSON was that when I started this I didn't
1476 know the Perl extension language XS very well (I still don't know it
1477 very well), and I was not confident about making a JSON producer, so it
1478 only parsed JSON, which was the main job I needed to do. It originally
1479 used lex and yacc in the form of flex and bison, since discarded. I
1480 also found out that someone else had a JSON parser called Argo in Java,
1481 so to save confusion I dropped the name JSON::Argo and renamed this
1482 JSON::Parse, keeping the version numbers continuous.
1483 The module has since been completely rewritten, twice, mostly in an
1485 attempt to improve performance, after I found that JSON::XS was much
1486 faster than the original JSON::Parse. (The first rewrite of the module
1487 was not released to CPAN, this is the second one, which explains why
1488 some files have names like Json3.xs). I also hoped to make something
1489 useful which wasn't in any existing CPAN module by offering the high-
1490 speed validator, "valid_json".
1491 I also rewrote the module due to some bugs I found, for example up to
1493 version 0.09 it was failing to accept whitespace after an object key
1494 string, so a JSON input of the form "{ "x" : "y" }", with whitespace
1495 between the "x" and the colon, ":", would cause it to fail. That was
1496 one big reason I created the random testing regime described in
1497 "TESTING" above. I believe that the module is now compliant with the
1498 JSON specification.
1499 After starting JSON::Create, I realised that some edge case handling in
1501 JSON::Parse needed to be improved. This resulted in the addition of the
1502 hash collision and literal-overriding methods introduced in versions
1503 0.37 and 0.38 of this module.
1504 Version 0.42 fixed a very serious bug where long strings could overflow
1506 an internal buffer, and could cause a segmentation fault.
1507 Version 0.48 removed an experimental feature called $json_diagnostics
1509 which made the module's errors be produced in JSON format, and replaced
1510 it with the current "diagnostics_hash" method, for the benefit of
1511 "JSON::Repair".
1512 Version 0.49 brought the module into conformance with the "JSON Parsing
1514 Test Suite".
1515 Version 0.54 removed support for the Solaris operating system.
1517
1519 Shlomi Fish (SHLOMIF) fixed some memory leaks in version 0.40.
1520 kolmogorov42 (https://github.com/kolmogorov42) reported a very serious
1521 bug which led to version 0.42.
1522
1524 Ben Bullock, <bkb@cpan.org>
1525
1527 This package and associated files are copyright (C) 2013-2020 Ben
1528 Bullock.
1529 You can use, copy, modify and redistribute this package and associated
1531 files under the Perl Artistic Licence or the GNU General Public
1532 Licence.
1533perl v5.32.0 2020-07-28 JSON::Parse(3)