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

NAME

6       JSON::Parse - Read JSON into a Perl variable
7

SYNOPSIS

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

VERSION

17       This documents version 0.55 of JSON::Parse corresponding to git commit
18       739c1e12e85756c703242229caef685615ba77ca
19       <https://github.com/benkasminbullock/JSON-
20       Parse/commit/739c1e12e85756c703242229caef685615ba77ca> released on Tue
21       Oct 24 07:11:47 2017 +0900.
22

DESCRIPTION

24       A module for parsing JSON. (JSON means "JavaScript Object Notation" and
25       it is specified in "RFC 7159".)
26
27       JSON::Parse offers the function "parse_json", which takes a string
28       containing JSON, and returns an equivalent Perl structure. It also
29       offers validation of JSON via "valid_json", which returns true or false
30       depending on whether the JSON is correct or not, and
31       "assert_valid_json", which produces a descriptive fatal error if the
32       JSON is invalid. A function "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
36       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
39       JSON::Parse accepts only UTF-8 as input. See "UTF-8 only" and "Handling
40       of Unicode".
41

FUNCTIONS

43   parse_json
44           use JSON::Parse 'parse_json';
45           my $perl = parse_json ('{"x":1, "y":2}');
46
47       This function converts JSON into a Perl structure, either an array
48       reference, a hash reference, or a scalar.
49
50       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
54       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
58           use JSON::Parse ':all';
59           my $perl = parse_json ('{"a":1, "b":2}');
60           print ref $perl, "\n";
61
62       produces output
63
64           HASH
65
66       (This example is included as hash.pl
67       <https://fastapi.metacpan.org/source/BKB/JSON-
68       Parse-0.55/examples/hash.pl> in the distribution.)
69
70       If the input JSON text is a serialized array, an array reference is
71       returned:
72
73           use JSON::Parse ':all';
74           my $perl = parse_json ('["a", "b", "c"]');
75           print ref $perl, "\n";
76
77       produces output
78
79           ARRAY
80
81       (This example is included as array.pl
82       <https://fastapi.metacpan.org/source/BKB/JSON-
83       Parse-0.55/examples/array.pl> in the distribution.)
84
85       Otherwise a Perl scalar is returned.
86
87       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
92       The function "parse_json_safe" offers a version of this function with
93       various safety features enabled.
94
95   json_file_to_perl
96           use JSON::Parse 'json_file_to_perl';
97           my $p = json_file_to_perl ('filename');
98
99       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
105       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
108   valid_json
109           use JSON::Parse 'valid_json';
110           if (valid_json ($json)) {
111               # do something
112           }
113
114       "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
119       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
122       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
126   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
136       produces output
137
138           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
140       (This example is included as assert.pl
141       <https://fastapi.metacpan.org/source/BKB/JSON-
142       Parse-0.55/examples/assert.pl> in the distribution.)
143
144       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
149       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
153       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
157   parse_json_safe
158       This is almost the same thing as "parse_json", but has the following
159       differences:
160
161       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
165               eval {
166                   $out = parse_json ($json);
167               };
168               if ($@) {
169                   carp $@;
170                   $out = undef;
171               }
172
173       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
179       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
184       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
188       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 "jpts.t" in t for details.
192
193       This function was added in version 0.38.
194

OLD INTERFACE

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
200   json_to_perl
201       This is exactly the same function as "parse_json".
202
203   validate_json
204       This is exactly the same function as "assert_valid_json".
205

Mapping from JSON to Perl

207       JSON elements are mapped to Perl as follows:
208
209   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
214       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
220   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
225       Handling of Unicode
226
227       Inputs must be in the UTF-8 format. See "UTF-8 only".
228
229       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
234           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
242       but
243
244           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
252       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
256       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
263           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
272       This is modelled on the behaviour of Perl's "chr":
273
274           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
282       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
286           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
313       produces output
314
315           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
321       (This example is included as unicode-details.pl
322       <https://fastapi.metacpan.org/source/BKB/JSON-
323       Parse-0.55/examples/unicode-details.pl> in the distribution.)
324
325       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
333       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
339   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
343       Thus
344
345           my $p = parse_json ('["monday", "tuesday", "wednesday"]');
346
347       has the same result as a Perl declaration of the form
348
349           my $p = [ 'monday', 'tuesday', 'wednesday' ];
350
351   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
357       Thus
358
359           my $j = <<EOF;
360           {"monday":["blue", "black"],
361            "tuesday":["grey", "heart attack"],
362            "friday":"Gotta get down on Friday"}
363           EOF
364
365           my $p = parse_json ($j);
366
367       has the same result as a Perl declaration of the form
368
369           my $p = {
370               monday => ['blue', 'black'],
371               tuesday => ['grey', 'heart attack'],
372               friday => 'Gotta get down on Friday',
373           };
374
375       Key collisions
376
377       A key collision is something like the following.
378
379           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
385       produces output
386
387           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
390       (This example is included as key-collision.pl
391       <https://fastapi.metacpan.org/source/BKB/JSON-Parse-0.55/examples/key-
392       collision.pl> in the distribution.)
393
394       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
399       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
406       For performance, "valid_json" and "assert_valid_json" do not store hash
407       keys, thus they cannot detect this variety of problem.
408
409   Literals
410       null
411
412       "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
419       true
420
421       "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
427       false
428
429       "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
439       Round trips and compatibility
440
441       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
448       This example demonstrates round-trip compatibility using JSON::Tiny
449       version 0.54:
450
451           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
474       produces output
475
476           First do a round-trip of our modules:
477
478           {"hendrix":false,"clapton":true,"fripp":false,"bruce":true}
479
480           Now do a round-trip of JSON::Tiny:
481
482           {"bruce":true,"clapton":true,"fripp":false,"hendrix":false}
483
484           First, incompatible mode:
485
486           tiny(parse): {"bruce":1,"clapton":1,"fripp":"","hendrix":""}
487           create(tiny): {"fripp":0,"bruce":1,"clapton":1,"hendrix":0}
488
489           Compatibility with JSON::Parse:
490
491           tiny(parse):{"bruce":true,"clapton":true,"fripp":false,"hendrix":false}
492
493           Compatibility with JSON::Create:
494
495           create(tiny):{"hendrix":false,"fripp":false,"bruce":true,"clapton":true}
496
497           JSON::Parse and JSON::Create are still compatible too:
498
499           {"fripp":false,"bruce":true,"clapton":true,"hendrix":false}
500
501       (This example is included as json-tiny-round-trip-demo.pl
502       <https://fastapi.metacpan.org/source/BKB/JSON-Parse-0.55/examples/json-
503       tiny-round-trip-demo.pl> in the distribution.)
504
505       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
509       Modifying the values
510
511       "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
516           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
521       Since the hash values are read-only scalars, "$p->{hocus} = 99" is like
522       this:
523
524           undef = 99;
525
526       If you need to modify the returned hash reference, then delete the
527       value first:
528
529           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
535       Similarly with array references, delete the value before altering:
536
537           my $in = '[true,false,null]';
538           my $q = json_parse ($in);
539           delete $q->[1];
540           $q->[1] = 'magic';
541
542       Note that the return values from parsing bare literals are not read-
543       only scalars, so
544
545           my $true = JSON::Parse::json_parse ('true');
546           $true = 99;
547
548       produces no error. This is because Perl copies the scalar.
549

METHODS

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
560       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
563   new
564           my $jp = JSON::Parse->new ();
565
566       Create a new JSON::Parse object.
567
568       This method was added in version 0.38.
569
570   run
571           my $out = $jp->run ($json);
572
573       This does the same thing as "parse_json", except its behaviour can be
574       modified using the methods below.
575
576       This method was added in version 0.38.
577
578   check
579           eval {
580               $jp->check ($json);
581           };
582
583       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
587       This method was added in version 0.48, for the benefit of JSON::Repair.
588
589   copy_literals
590           $jp->copy_literals (1);
591
592       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
596       With a false value, use read-only scalars:
597
598           $jp->copy_literals (0);
599
600       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
604       If the user also sets user-defined literals with "set_true",
605       "set_false" and "set_null", that takes precedence over this.
606
607       This method was added in version 0.38.
608
609   warn_only
610           $jp->warn_only (1);
611
612       Warn, don't die, on error. Failed parsing returns the undefined value,
613       "undef", and prints a warning.
614
615       This can be switched off again using any false value:
616
617           $jp->warn_only ('');
618
619       This method was documented in version 0.38, but only implemented in
620       version 0.41.
621
622   detect_collisions
623           $jp->detect_collisions (1);
624
625       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
630           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
638       produces output
639
640           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
642       (This example is included as collide.pl
643       <https://fastapi.metacpan.org/source/BKB/JSON-
644       Parse-0.55/examples/collide.pl> in the distribution.)
645
646       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
650       This method was added in version 0.38.
651
652   diagnostics_hash
653           $jp->diagnostics_hash (1);
654
655       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
659       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
665       This requires Perl version 5.14 or later.
666
667       This method was added in version 0.46.
668
669   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
674       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
678           $jp->set_false (undef);
679
680       Thus, we cannot use a single function "$jp->false (undef)" to cover
681       both setting and deleting of values.
682
683       These methods were added in version 0.38.
684
685       set_true
686
687           $jp->set_true ("Yes, that is so true");
688
689       Supply a scalar to be used in place of the JSON "true" literal.
690
691       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
695           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
702       prints
703
704           Yes, that is so true
705
706       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
710       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
715       This method was added in version 0.38.
716
717       delete_true
718
719           $jp->delete_true ();
720
721       Delete the user-defined true value. See "set_true".
722
723       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
726       This method was added in version 0.38.
727
728       set_false
729
730           $jp->set_false (JSON::PP::Boolean::false);
731
732       Supply a scalar to be used in place of the JSON "false" literal.
733
734       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
738       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
742       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
747       This method was added in version 0.38.
748
749       delete_false
750
751           $jp->delete_false ();
752
753       Delete the user-defined false value. See "set_false".
754
755       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
758       This method was added in version 0.38.
759
760       set_null
761
762           $jp->set_null (0);
763
764       Supply a scalar to be used in place of the JSON "null" literal.
765
766       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
770       This method was added in version 0.38.
771
772       delete_null
773
774           $jp->delete_null ();
775
776       Delete the user-defined null value. See "set_null".
777
778       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
781       This method was added in version 0.38.
782
783       no_warn_literals
784
785           $jp->no_warn_literals (1);
786
787       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
791           $jp->no_warn_literals (1);
792           $jp->set_false ("false");
793
794       See also "Contradictory values for "true" and "false"".
795
796       This also switches off the warning "User-defined value overrules
797       copy_literals".
798
799       This method was added in version 0.38.
800

RESTRICTIONS

802       This module imposes the following restrictions on its input.
803
804       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
814       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
825       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
831               use Encode 'decode';
832               my $input_utf8 = decode ('UTF-16', $input);
833               my $perl = parse_json ($input_utf8);
834
835           or, for a file, use ":encoding" (see PerlIO::encoding and
836           perluniintro):
837
838               open my $input, "<:encoding(UTF-16)", 'some-json-file';
839
840           JSON::Parse does not determine the nature of the octet stream, as
841           described in part 3 of "RFC 7159".
842
843           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

DIAGNOSTICS

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
853       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
858       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
862           my $p;
863           eval {
864               $p = parse_json ($j);
865           };
866           if ($@) {
867               # handle error
868           }
869
870       The following error messages are produced:
871
872   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
878           assert_valid_json ('+');
879
880       gives output
881
882           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
884       The message always includes a list of what characters are allowed.
885
886       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
889           assert_valid_json ('{"this":"\a"}');
890
891       gives output
892
893           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
895       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
900           assert_valid_json ('[true,folse]');
901
902       gives output
903
904           JSON error at line 1, byte 8/12: Unexpected character 'o' parsing literal starting from byte 7: expecting 'a'
905
906       and the missing second half of a surrogate pair:
907
908           assert_valid_json ('["\udc00? <-- should be a second half here"]');
909
910       gives output
911
912           JSON error at line 1, byte 9/44: Unexpected character '?' parsing unicode escape starting from byte 3: expecting '\'
913
914       All kinds of errors can occur parsing numbers, for example a missing
915       fraction,
916
917           assert_valid_json ('[1.e9]');
918
919       gives output
920
921           JSON error at line 1, byte 4/6: Unexpected character 'e' parsing number starting from byte 2: expecting digit: '0-9'
922
923       and a leading zero,
924
925           assert_valid_json ('[0123]');
926
927       gives output
928
929           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
931       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
935       These are all handled by this error.  Thus the error messages are a
936       little confusing as diagnostics.
937
938       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
946       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
950           no utf8;
951           use JSON::Parse 'assert_valid_json';
952
953           # Error in first byte:
954
955           my $bad_utf8_1 = chr (hex ("81"));
956           eval { assert_valid_json ("[\"$bad_utf8_1\"]"); };
957           print "$@\n";
958
959           # Error in third byte:
960
961           my $bad_utf8_2 = chr (hex ('e2')) . chr (hex ('9C')) . 'b';
962           eval { assert_valid_json ("[\"$bad_utf8_2\"]"); };
963           print "$@\n";
964
965       prints
966
967           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
969           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
971   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
976           assert_valid_json ('{"first":"Suzuki","second":"Murakami","third":"Asada}');
977
978       gives output
979
980           JSON error at line 1: Unexpected end of input parsing string starting from byte 47
981
982   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
987           assert_valid_json ('["\uDC00\uABCD"]');
988
989       gives output
990
991           JSON error at line 1: Not surrogate pair parsing unicode escape starting from byte 11
992
993   Empty input
994       This error occurs for an input which is an empty (no length or
995       whitespace only) or an undefined value.
996
997           assert_valid_json ('');
998
999       gives output
1000
1001           JSON error: Empty input parsing initial state
1002
1003       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
1007   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
1011           my $p = JSON::Parse->new ();
1012           $p->detect_collisions (1);
1013           $p->run ('{"hocus":1,"pocus":2,"hocus":3}');
1014
1015       gives output
1016
1017           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
1019       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
1022   Contradictory values for "true" and "false"
1023       User-defined value for JSON false evaluates as true
1024
1025       This happens if you set JSON false to map to a true value:
1026
1027           $jp->set_false (1);
1028
1029       To switch off this warning, use "no_warn_literals".
1030
1031       This warning was added in version 0.38.
1032
1033       User-defined value for JSON true evaluates as false
1034
1035       This happens if you set JSON true to map to a false value:
1036
1037           $jp->set_true (undef);
1038
1039       To switch off this warning, use "no_warn_literals".
1040
1041       This warning was added in version 0.38.
1042
1043   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
1048       This warning was added in version 0.38.
1049

PERFORMANCE

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
1057       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
1064       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
1070       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/739c1e12e85756c703242229caef685615ba77ca/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/739c1e12e85756c703242229caef685615ba77ca/benchmarks/pub-
1078       bench.pl> runs the benchmarks and prints them out as POD.
1079
1080       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
1086       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
1096       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
1106       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
1116       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
1126       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
1136       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

SEE ALSO

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
1152       json.org
1153           <http://json.org> is the website for JSON, authored by Douglas
1154           Crockford.
1155
1156       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
1162       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
1168       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
1173   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
1178           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
1184           JSON::XS
1185               This is an all-purpose JSON module in XS, which means it
1186               requires a C compiler to install.
1187
1188           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
1192           JSON::DWIW
1193               "Does what I want" module.
1194
1195           JSON::YAJL
1196               Wraps a C library called yajl.
1197
1198           JSON::Util
1199               Relies on JSON::MaybeXS.
1200
1201           Pegex::JSON
1202               Based on Pegex.
1203
1204           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
1209           Inline::JSON
1210               Relies on "JSON".
1211
1212           Glib::JSON
1213               Uses the JSON library from Glib, a library of C functions for
1214               the Linux GNOME desktop project.
1215
1216           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
1221           JSON::Tiny
1222               This is a fork of "Mojo::JSON".
1223
1224           File::JSON::Slurper
1225               Slurp a JSON file into a data structure, and the reverse. It
1226               relies on "JSON::MaybeXS".
1227
1228       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
1234               (JSON::Parse's handling of key collisions is discussed in "Key
1235               collisions" in this document.)
1236
1237           boolean
1238               This module offers "true" and "false" literals similar to JSON.
1239
1240           Devel::JSON
1241               For one-liners.
1242
1243           App::JSON::to
1244               Convert JSON data to other formats.
1245
1246           JSON::Color
1247               This module generates JSON, colorized with ANSI escape
1248               sequences.
1249
1250           Config::JSON
1251               Configuration files in JSON
1252
1253           JSON::String
1254               Automatically change a JSON string when a data structure
1255               changes.
1256
1257           JSON::Builder
1258               Create JSON under memory limitations.
1259
1260           JSON::Pointer
1261               Extract parts of a JSON string.
1262
1263           Inline::JSON
1264               Include JSON in a Perl program.
1265
1266           JSON::Path
1267               Search nested hashref/arrayref structures using JSONPath.
1268
1269       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
1275           Test::JSON::More
1276               JSON Test Utility. As of version 0.02, it relies on "JSON".
1277
1278           Test::Deep::JSON
1279               Compare JSON with Test::Deep. As of version 0.03, it relies on
1280               "JSON".
1281
1282       Type-related modules
1283           These untangle numbers, strings, and booleans into JSON types.
1284
1285           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
1292           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
1297           JSON::Any
1298               This module combines "JSON::DWIW", "JSON::XS" versions one and
1299               two, and "JSON::Syck".
1300
1301           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
1305           Mojo::JSON::MaybeXS
1306               This pulls in "JSON::MaybeXS" instead of "Mojo::JSON".
1307
1308       JSON extensions
1309           These modules extend JSON with comments and other things.
1310
1311           JSON::Relaxed
1312               "An extension of JSON that allows for better human-
1313               readability".
1314
1315           JSONY
1316               "Relaxed JSON with a little bit of YAML"
1317
1318           JSON::Diffable
1319               "A relaxed and easy diffable JSON variant"
1320
1321       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

SCRIPT

1338       A script "validjson" is supplied with the module. This runs
1339       "assert_valid_json" on its inputs, so run it like this.
1340
1341            validjson *.json
1342
1343       The default behaviour is to just do nothing if the input is valid. For
1344       invalid input it prints what the problem is:
1345
1346           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
1349       If you need confirmation, use its --verbose option:
1350
1351           validjson -v *.json
1352
1353           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

TEST RESULTS

1360       The CPAN testers results are at the usual place.
1361
1362       The ActiveState test results are at
1363       <http://code.activestate.com/ppm/JSON-Parse/>.
1364

DEPENDENCIES

1366       Carp
1367

EXPORTS

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
1374       All of the functions can be exported using the tag ':all':
1375
1376           use JSON::Parse ':all';
1377

TESTING

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
1384       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/739c1e12e85756c703242229caef685615ba77ca/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
1397       This setup relies on a C file, json-random-test.c
1398       <https://github.com/benkasminbullock/JSON-
1399       Parse/blob/739c1e12e85756c703242229caef685615ba77ca/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/739c1e12e85756c703242229caef685615ba77ca/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
1408       A pure C version called random-test.c
1409       <https://github.com/benkasminbullock/JSON-
1410       Parse/blob/739c1e12e85756c703242229caef685615ba77ca/random-test.c> also
1411       exists. This applies exactly the same tests, and requires no Perl at
1412       all.
1413
1414       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/739c1e12e85756c703242229caef685615ba77ca/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
1428   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
1442       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/739c1e12e85756c703242229caef685615ba77ca/xt/jpts.t> and the
1450       subdirectory xt/jpts <https://github.com/benkasminbullock/JSON-
1451       Parse/blob/739c1e12e85756c703242229caef685615ba77ca/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/739c1e12e85756c703242229caef685615ba77ca/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

HISTORY

1461       See Changes <https://github.com/benkasminbullock/JSON-
1462       Parse/blob/739c1e12e85756c703242229caef685615ba77ca/Changes> in the
1463       distribution for a full list of changes.
1464
1465       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
1475       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
1484       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
1492       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
1500       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
1505       Version 0.42 fixed a very serious bug where long strings could overflow
1506       an internal buffer, and could cause a segmentation fault.
1507
1508       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
1513       Version 0.49 brought the module into conformance with the "JSON Parsing
1514       Test Suite".
1515
1516       Version 0.54 removed support for the Solaris operating system.
1517

ACKNOWLEDGEMENTS

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

AUTHOR

1524       Ben Bullock, <bkb@cpan.org>
1525
1527       This package and associated files are copyright (C) 2013-2017 Ben
1528       Bullock.
1529
1530       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.
1533
1534
1535
1536perl v5.30.0                      2019-07-26                    JSON::Parse(3)
Impressum