Provided by: libjson-parse-perl_0.62-1build4_amd64 bug

NAME

       JSON::Parse - Parse JSON

SYNOPSIS

           use JSON::Parse 'parse_json';
           my $json = '["golden", "fleece"]';
           my $perl = parse_json ($json);
           # Same effect as $perl = ['golden', 'fleece'];

       Convert JSON into Perl.

VERSION

       This documents version 0.62 of JSON::Parse corresponding to git commit
       d04630086f6c92fea720cba4568faa0cbbdde5a6 <https://github.com/benkasminbullock/JSON-
       Parse/commit/d04630086f6c92fea720cba4568faa0cbbdde5a6> released on Sat Jul 16 08:23:13
       2022 +0900.

DESCRIPTION

       A module for parsing JSON. (JSON means "JavaScript Object Notation" and it is specified in
       "RFC 8259".)

       JSON::Parse offers the function "parse_json", which takes a string containing JSON, and
       returns an equivalent Perl structure. It also offers validation of JSON via "valid_json",
       which returns true or false depending on whether the JSON is correct or not, and
       "assert_valid_json", which produces a descriptive fatal error if the JSON is invalid. A
       function "read_json" reads JSON from a file, and there is a safer version of "parse_json"
       called "parse_json_safe" which doesn't throw exceptions.

       For special cases of parsing, there are also methods "new" and "parse", which create a
       JSON parsing object and run it on text. See "METHODS".

       JSON::Parse accepts only UTF-8 as input. See "UTF-8 only" and "Handling of Unicode".

FUNCTIONS

   assert_valid_json
           use JSON::Parse 'assert_valid_json';
           eval {
               assert_valid_json ('["xyz":"b"]');
           };
           if ($@) {
               print "Your JSON was invalid: $@\n";
           }
           # Prints "Unexpected character ':' parsing array"

       produces output

           Your JSON was invalid: JSON error at line 1, byte 7/11: Unexpected character ':' parsing array starting from byte 1: expecting whitespace: 'n', '\r', '\t', ' ' or comma: ',' or end of array: ']' at /usr/home/ben/projects/json-parse/examples/assert.pl line 6.

       (This example is included as assert.pl <https://fastapi.metacpan.org/source/BKB/JSON-
       Parse-0.62/examples/assert.pl> in the distribution.)

       This is the underlying function for "valid_json". It runs at the same speed, but it throws
       an error if the JSON is wrong, rather than returning 1 or 0. See "DIAGNOSTICS" for the
       error format, which is identical to "parse_json".

       This cannot detect key collisions in the JSON since it does not store values. See "Key
       collisions" for more on this module's handling of non-unique names in the JSON.

       The method equivalent to this is "check".

       The behaviour of disallowing empty inputs was changed in version 0.49.

   parse_json
           use JSON::Parse 'parse_json';
           my $perl = parse_json ('{"x":1, "y":2}');

       This function converts JSON into a Perl structure, either an array reference, a hash
       reference, or a scalar.

       If the first argument does not contain a complete valid JSON text, is the undefined value,
       an empty string, or a string containing only whitespace "parse_json" throws a fatal error
       ("dies").

       If the argument contains valid JSON, the return value is either a hash reference, an array
       reference, or a scalar. If the input JSON text is a serialized object, a hash reference is
       returned:

           use JSON::Parse ':all';
           my $perl = parse_json ('{"a":1, "b":2}');
           print ref $perl, "\n";

       produces output

           HASH

       (This example is included as hash.pl <https://fastapi.metacpan.org/source/BKB/JSON-
       Parse-0.62/examples/hash.pl> in the distribution.)

       If the input JSON text is a serialized array, an array reference is returned:

           use JSON::Parse ':all';
           my $perl = parse_json ('["a", "b", "c"]');
           print ref $perl, "\n";

       produces output

           ARRAY

       (This example is included as array.pl <https://fastapi.metacpan.org/source/BKB/JSON-
       Parse-0.62/examples/array.pl> in the distribution.)

       Otherwise a Perl scalar is returned.

       The behaviour of allowing a scalar was added in version 0.32 of this module. This brings
       it into line with the new specification for JSON. The behaviour of disallowing empty
       inputs was changed in version 0.49.

       The function "parse_json_safe" offers a version of this function with various safety
       features enabled. The method "parse" is equivalent to this.

   parse_json_safe
       This is almost the same thing as "parse_json", but has the following differences:

       Does not throw exceptions
           If the JSON is invalid, a warning is printed and the undefined value is returned, as
           if calling "parse_json" like this:

               eval {
                   $out = parse_json ($json);
               };
               if ($@) {
                   carp $@;
                   $out = undef;
               }

       Detects key collisions
           This switches on "detect_collisions", so that if the JSON contains non-unique names, a
           warning is printed and the undefined value is returned. See "Key collisions" for an
           explanation of what a key collision is.

       Booleans are not read-only
           This switches on "copy_literals" so that JSON true, false and null values are copied.
           These values can be modified, but they will not be converted back into "true" and
           "false" by JSON::Create.

       Errors are reported by carp
           Parsing errors are reported by "carp" in Carp, so the error line number refers to the
           caller's line.

       As the name implies, this is meant to be a "safety-first" version of "parse_json".

       ๐ŸŽฒ This function was added in version 0.38.

   read_json
           use JSON::Parse 'read_json';
           my $p = read_json ('filename');

       This is exactly the same as "parse_json" except that it reads the JSON from the specified
       file rather than a scalar. The file must be in the UTF-8 encoding, and is opened as a
       character file using :encoding(utf8) (see PerlIO::encoding and perluniintro). The output
       is marked as character strings.

       The method equivalent is "read".

       This is a convenience function written in Perl. You may prefer to read the file yourself
       using another module if you need faster performance.

       This was renamed from "json_file_to_perl" in version 0.59. The old name will also continue
       to work indefinitely.

   valid_json
           use JSON::Parse 'valid_json';
           if (valid_json ($json)) {
               # do something
           }

       "valid_json" returns 1 if its argument is valid JSON and 0 if not. It runs several times
       faster than "parse_json". This gain in speed is obtained because it discards the input
       data after reading it, rather than storing it into Perl variables.

       This does not supply the actual errors which caused invalidity. Use "assert_valid_json" to
       get error messages when the JSON is invalid.

       This cannot detect duplicate keys in JSON objects because it does not store values. See
       "Key collisions" for more on this module's handling of non-unique names in the JSON.

METHODS

       If you need to parse JSON and you are not satisfied with the parsing options offered by
       "parse_json" and "parse_json_safe", you can create a JSON parsing object with "new" and
       set various options on the object, then use it with "parse" or "read".

       There are options to copy JSON literals ("true", "false", "null") with "copy_literals",
       switch off fatal errors with "warn_only", detect duplicate keys in objects with
       "detect_collisions", set the maximum depth of nested objects and arrays with
       "set_max_depth", produce machine-readable parsing errors with "diagnostics_hash", and set
       the JSON literals to user defined values with the methods described under "Methods for
       manipulating literals".

       These methods only affect the object created with "new"; they do not globally affect the
       behaviour of "parse_json" or "parse_json_safe".

   check
           eval {
               $jp->check ($json);
           };

       This does the same thing as "assert_valid_json", except its behaviour can be modified
       using the "diagnostics_hash" method.

       ๐ŸŽฒ This method was added in version 0.48. This is for the benefit of JSON::Repair.

   copy_literals
           $jp->copy_literals (1);

       With a true value, copy JSON literal values ("null", "true", and "false") into new Perl
       scalar values, and don't put read-only values into the output.

       With a false value, use read-only scalars:

           $jp->copy_literals (0);

       The "copy_literals (1)" behaviour is the behaviour of "parse_json_safe". The
       "copy_literals (0)" behaviour is the behaviour of "parse_json".

       If the user also sets user-defined literals with "set_true", "set_false" and "set_null",
       that takes precedence over this.

       ๐ŸŽฒ This method was added in version 0.38.

   detect_collisions
           $jp->detect_collisions (1);

       This switches on a check for hash key collisions (non-unique names in JSON objects). If a
       collision is found, an error message "Name is not unique" is printed, which also gives the
       non-unique name and the byte position where the start of the colliding string was found:

           use JSON::Parse;
           my $jp = JSON::Parse->new ();
           $jp->detect_collisions (1);
           eval {
               $jp->parse ('{"animals":{"cat":"moggy","cat":"feline","cat":"neko"}}');
           };
           print "$@\n" if $@;

       produces output

           JSON error at line 1, byte 28/55: Name is not unique: "cat" parsing object starting from byte 12 at /usr/home/ben/projects/json-parse/examples/../blib/lib/JSON/Parse.pm line 131.

       (This example is included as collide.pl <https://fastapi.metacpan.org/source/BKB/JSON-
       Parse-0.62/examples/collide.pl> in the distribution.)

       The "detect_collisions (1)" behaviour is the behaviour of "parse_json_safe". The
       "detect_collisions (0)" behaviour is the behaviour of "parse_json".

       ๐ŸŽฒ This method was added in version 0.38.

   diagnostics_hash
           $jp->diagnostics_hash (1);

       This changes diagnostics produced by errors from a simple string into a hash reference
       containing various fields. This is incompatible with "warn_only".

       This replaces the previous experimental global variable $json_diagnostics, which was
       removed from the module. The hash keys and values are identical to those provided in the
       object returned by $json_diagnostics, with the addition of a key "error as string" which
       returns the usual error.

       This requires Perl version 5.14 or later.

       An example of the use of this method to "repair" broken JSON is in the module
       "JSON::Repair".

       ๐ŸŽฒ This method was added in version 0.46.

   get_max_depth
          my $max_depth = $jp->get_max_depth ();

       This returns the maximum nesting depth of objects or arrays in the input JSON. The default
       value is 10,000.

       ๐ŸŽฒ This method was added in version 0.58.

   new
           my $jp = JSON::Parse->new ();

       Create a new JSON::Parse object.

       ๐ŸŽฒ This method was added in version 0.38.

   parse
           my $out = $jp->parse ($json);

       This does the same thing as "parse_json", except its behaviour can be modified using
       object methods.

       ๐ŸŽฒ This method was added in version 0.38.

       This was renamed from "run" in version 0.60.

   read
           my $json = $jp->read ($file);

       Read a file, parse the contained JSON, and return the output. This method is equivalent to
       the function "read_json".

       ๐ŸŽฒ This method was added in version 0.60.

   set_max_depth
           $jp->set_max_depth (42);

       Set the maximum nesting depth of objects or arrays in the input JSON. The default value is
       10,000.

       ๐ŸŽฒ This method was added in version 0.58.

   upgrade_utf8
           $jp->upgrade_utf8 (1);

       Upgrade input from bytes to characters automatically.

       This can be switched off again using any false value:

           $jp->upgrade_utf8 (0);

       ๐ŸŽฒ This method was added in version 0.61.

   warn_only
           $jp->warn_only (1);

       Warn, don't die, on error. Failed parsing returns the undefined value, "undef", and prints
       a warning.

       This can be switched off again using any false value:

           $jp->warn_only ('');

       ๐ŸŽฒ This method was added in version 0.41.

   Methods for manipulating literals
       These methods alter what is written into the Perl structure when the parser sees a literal
       value, "true", "false" or "null" in the input JSON.

       This number of methods is needed because of the possibility that a user wants to set the
       output for "false" to be "undef":

           $jp->set_false (undef);

       Thus, we cannot use a single function "$jp->false (undef)" to cover both setting and
       deleting of values.

       ๐ŸŽฒ This facility was added in version 0.38.

       set_true

           $jp->set_true ("Yes, that is so true");

       Supply a scalar to be used in place of the JSON "true" literal.

       This example puts the string "Yes, that is so true" into the hash or array when we hit a
       "true" literal, rather than the default read-only scalar:

           use JSON::Parse;
           my $json = '{"yes":true,"no":false}';
           my $jp = JSON::Parse->new ();
           $jp->set_true ('Yes, that is so true');
           my $out = $jp->parse ($json);
           print $out->{yes}, "\n";

       prints

           Yes, that is so true

       To override the previous value, call it again with a new value. To delete the value and
       revert to the default behaviour, use "delete_true".

       If you give this a value which is not "true", as in Perl will evaluate it as a false in an
       if statement, it prints a warning "User-defined value for JSON true evaluates as false".
       You can switch this warning off with "no_warn_literals".

       ๐ŸŽฒ This method was added in version 0.38.

       delete_true

           $jp->delete_true ();

       Delete the user-defined true value. See "set_true".

       This method is "safe" in that it has absolutely no effect if no user-defined value is in
       place. It does not return a value.

       ๐ŸŽฒ This method was added in version 0.38.

       set_false

           $jp->set_false (JSON::PP::Boolean::false);

       Supply a scalar to be used in place of the JSON "false" literal.

       In the above example, when we hit a "false" literal, we put "JSON::PP::Boolean::false" in
       the output, similar to JSON::PP and other CPAN modules like Mojo::JSON or JSON::XS.

       To override the previous value, call it again with a new value. To delete the value and
       revert to the default behaviour, use "delete_false".

       If you give this a value which is not "false", as in Perl will evaluate it as a false in
       an if statement, it prints a warning "User-defined value for JSON false evaluates as
       true".  You can switch this warning off with "no_warn_literals".

       ๐ŸŽฒ This method was added in version 0.38.

       delete_false

           $jp->delete_false ();

       Delete the user-defined false value. See "set_false".

       This method is "safe" in that it has absolutely no effect if no user-defined value is in
       place. It does not return a value.

       ๐ŸŽฒ This method was added in version 0.38.

       set_null

           $jp->set_null (0);

       Supply a scalar to be used in place of the JSON "null" literal.

       To override the previous value, call it again with a new value. To delete the value and
       revert to the default behaviour, use "delete_null".

       ๐ŸŽฒ This method was added in version 0.38.

       delete_null

           $jp->delete_null ();

       Delete the user-defined null value. See "set_null".

       This method is "safe" in that it has absolutely no effect if no user-defined value is in
       place. It does not return a value.

       ๐ŸŽฒ This method was added in version 0.38.

       no_warn_literals

           $jp->no_warn_literals (1);

       Use a true value to switch off warnings about setting boolean values to contradictory
       things. For example if you want to set the JSON "false" literal to turn into the string
       "false",

           $jp->no_warn_literals (1);
           $jp->set_false ("false");

       See also "Contradictory values for "true" and "false"".

       This also switches off the warning "User-defined value overrules copy_literals".

       ๐ŸŽฒ This method was added in version 0.38.

OLD INTERFACE

       The following alternative function names are accepted. These are the names used for the
       functions in old versions of this module. These names are not deprecated and will never be
       removed from the module.

       The names ending in "_to_perl" seem quite silly in retrospect since surely it is obvious
       that one is programming in Perl.

   json_to_perl
       This is exactly the same function as "parse_json".

   json_file_to_perl
       This is exactly the same function as "read_json". The function was renamed in version
       0.59, after the same function in "File::JSON::Slurper".

   run
       This is the old name for "parse".

   validate_json
       This is exactly the same function as "assert_valid_json".

Mapping from JSON to Perl

       JSON elements are mapped to Perl as follows:

   JSON numbers
       JSON numbers become Perl numbers, either integers or double-precision floating point
       numbers, or possibly strings containing the number if parsing of a number by the usual
       methods fails somehow.

       JSON does not allow leading zeros, like 0123, or leading plus signs, like +100, in
       numbers, so these cause an "Unexpected character" error. JSON also does not allow numbers
       of the form 1., but it does allow things like 0e0 or 1E999999. As far as possible these
       are accepted by JSON::Parse.

   JSON strings
       JSON strings become Perl strings. The JSON escape characters such as "\t" for the tab
       character (see section 2.5 of "RFC 8259") are mapped to the equivalent ASCII character.

       Handling of Unicode

       Inputs must be in the UTF-8 format. See "UTF-8 only".

       In addition, JSON::Parse rejects UTF-8 which encodes non-characters such as "U+FFFF" and
       ill-formed characters such as incomplete halves of surrogate pairs.

       Unicode encoding points in the input of the form "\u3000" are converted into the
       equivalent UTF-8 bytes.

       Surrogate pairs in the form "\uD834\uDD1E" are also handled. If the second half of the
       surrogate pair is missing, an "Unexpected character" or "Unexpected end of input" error is
       thrown. If the second half of the surrogate pair is present but contains an impossible
       value, a "Not surrogate pair" error is thrown.

       If the input to "parse_json" is marked as Unicode characters, the output strings will be
       marked as Unicode characters. If the input is not marked as Unicode characters, the output
       strings will not be marked as Unicode characters. Thus,

           use JSON::Parse ':all';
           # The scalar $sasori looks like Unicode to Perl
           use utf8;
           my $sasori = '["่ "]';
           my $p = parse_json ($sasori);
           print utf8::is_utf8 ($p->[0]);
           # Prints 1.

       but

           use JSON::Parse ':all';
           # The scalar $ebi does not look like Unicode to Perl
           no utf8;
           my $ebi = '["ๆตท่€"]';
           my $p = parse_json ($ebi);
           print utf8::is_utf8 ($p->[0]);
           # Prints nothing.

       Escapes of the form \uXXXX (see page three of "RFC 8259") are mapped to ASCII if XXXX is
       less than 0x80, or to UTF-8 if XXXX is greater than or equal to 0x80.

       Strings containing \uXXXX escapes greater than 0x80 are also upgraded to character
       strings, regardless of whether the input is a character string or a byte string, thus
       regardless of whether Perl thinks the input string is Unicode, escapes like \u87f9 are
       converted into the equivalent UTF-8 bytes and the particular string in which they occur is
       marked as a character string:

           use JSON::Parse ':all';
           no utf8;
           # ่Ÿน
           my $kani = '["\u87f9"]';
           my $p = parse_json ($kani);
           print "It's marked as a character string" if utf8::is_utf8 ($p->[0]);
           # Prints "It's marked as a character string" because it's upgraded
           # regardless of the input string's flags.

       This is modelled on the behaviour of Perl's "chr":

           no utf8;
           my $kani = '87f9';
           print "hex is character string\n" if utf8::is_utf8 ($kani);
           # prints nothing
           $kani = chr (hex ($kani));
           print "chr makes it a character string\n" if utf8::is_utf8 ($kani);
           # prints "chr makes it a character string"

       However, JSON::Parse also upgrades the remaining part of the string into a character
       string, even when it's not marked as a character string. For example,

           use JSON::Parse ':all';
           use Unicode::UTF8 'decode_utf8';
           no utf8;
           my $highbytes = "ใ‹";
           my $not_utf8 = "$highbytes\\u3042";
           my $test = "{\"a\":\"$not_utf8\"}";
           my $out = parse_json ($test);
           # JSON::Parse does something unusual here in promoting the first part
           # of the string into UTF-8.
           print "JSON::Parse gives this: ", $out->{a}, "\n";
           # Perl cannot assume that $highbytes is in UTF-8, so it has to just
           # turn the initial characters into garbage.
           my $add_chr = $highbytes . chr (0x3042);
           print "Perl's output is like this: ", $add_chr, "\n";
           # In fact JSON::Parse's behaviour is equivalent to this:
           my $equiv = decode_utf8 ($highbytes) . chr (0x3042);
           print "JSON::Parse did something like this: ", $equiv, "\n";
           # With character strings switched on, Perl and JSON::Parse do the same
           # thing.
           use utf8;
           my $is_utf8 = "ใ‹";
           my $test2 = "{\"a\":\"$is_utf8\\u3042\"}";
           my $out2 = parse_json ($test2);
           print "JSON::Parse: ", $out2->{a}, "\n";
           my $add_chr2 = $is_utf8 . chr (0x3042);
           print "Native Perl: ", $add_chr2, "\n";

       produces output

           JSON::Parse gives this: ใ‹ใ‚
           Perl's output is like this: รฃยย‹ใ‚
           JSON::Parse did something like this: ใ‹ใ‚
           JSON::Parse: ใ‹ใ‚
           Native Perl: ใ‹ใ‚

       (This example is included as unicode-details.pl
       <https://fastapi.metacpan.org/source/BKB/JSON-Parse-0.62/examples/unicode-details.pl> in
       the distribution.)

       Although in general the above would be an unsafe practice, JSON::Parse can do things this
       way because JSON is a text-only, Unicode-only format. To ensure that invalid inputs are
       never upgraded, JSON::Parse checks each input byte to make sure that it forms UTF-8. See
       also "UTF-8 only". Doing things this way, rather than the way that Perl does it, was one
       of the original motivations for writing this module.

   JSON arrays
       JSON arrays become Perl array references. The elements of the Perl array are in the same
       order as they appear in the JSON.

       Thus

           my $p = parse_json ('["monday", "tuesday", "wednesday"]');

       has the same result as a Perl declaration of the form

           my $p = [ 'monday', 'tuesday', 'wednesday' ];

   JSON objects
       JSON objects become Perl hashes. The members of the JSON object become key and value pairs
       in the Perl hash. The string part of each object member becomes the key of the Perl hash.
       The value part of each member is mapped to the value of the Perl hash.

       Thus

           my $j = <<EOF;
           {"monday":["blue", "black"],
            "tuesday":["grey", "heart attack"],
            "friday":"Gotta get down on Friday"}
           EOF

           my $p = parse_json ($j);

       has the same result as a Perl declaration of the form

           my $p = {
               monday => ['blue', 'black'],
               tuesday => ['grey', 'heart attack'],
               friday => 'Gotta get down on Friday',
           };

       Key collisions

       A key collision is something like the following.

           use JSON::Parse qw/parse_json parse_json_safe/;
           my $j = '{"a":1, "a":2}';
           my $p = parse_json ($j);
           print "Ambiguous key 'a' is ", $p->{a}, "\n";
           my $q = parse_json_safe ($j);

       produces output

           JSON::Parse::parse_json_safe: Name is not unique: "a" parsing object starting from byte 1 at /usr/home/ben/projects/json-parse/examples/key-collision.pl line 8.
           Ambiguous key 'a' is 2

       (This example is included as key-collision.pl
       <https://fastapi.metacpan.org/source/BKB/JSON-Parse-0.62/examples/key-collision.pl> in the
       distribution.)

       Here the key "a" could be either 1 or 2. As seen in the example, "parse_json" overwrites
       the first value with the second value. "parse_json_safe" halts and prints a warning. If
       you use "new" you can switch key collision on and off with the "detect_collisions" method.

       The rationale for "parse_json" not to give warnings is that Perl doesn't give information
       about collisions when storing into hash values, and checking for collisions for every key
       will degrade performance for the sake of an unlikely occurrence. The JSON specification
       says "The names within an object SHOULD be unique." (see "RFC 8259", page 5), although
       it's not a requirement.

       For performance, "valid_json" and "assert_valid_json" do not store hash keys, thus they
       cannot detect this variety of problem.

   Literals
       false

       "parse_json" maps the JSON false literal to a readonly scalar which evaluates to the empty
       string, or to zero in a numeric context. (This behaviour changed from version 0.36 to
       0.37. In versions up to 0.36, the false literal was mapped to a readonly scalar which
       evaluated to 0 only.) "parse_json_safe" maps the JSON literal to a similar scalar without
       the readonly constraints. If you use a parser created with "new", you can choose either of
       these behaviours with "copy_literals", or you can tell JSON::Parse to put your own value
       in place of falses using the "set_false" method.

       null

       "parse_json" maps the JSON null literal to a readonly scalar $JSON::Parse::null which
       evaluates to "undef". "parse_json_safe" maps the JSON literal to the undefined value. If
       you use a parser created with "new", you can choose either of these behaviours with
       "copy_literals", or you can tell JSON::Parse to put your own value in place of nulls using
       the "set_null" method.

       true

       "parse_json" maps the JSON true literal to a readonly scalar which evaluates to 1.
       "parse_json_safe" maps the JSON literal to the value 1. If you use a parser created with
       "new", you can choose either of these behaviours with "copy_literals", or you can tell
       JSON::Parse to put your own value in place of trues using the "set_true" method.

       Round trips and compatibility

       The Perl versions of literals produced by "parse_json" will be converted back to JSON
       literals if you use "create_json" in JSON::Create. However, JSON::Parse's literals are
       incompatible with the other CPAN JSON modules. For compatibility with other CPAN modules,
       create a JSON::Parse object with "new", and set JSON::Parse's literals with "set_true",
       "set_false", and "set_null".

       A round trip with JSON::Tiny

       This example demonstrates round-trip compatibility using JSON::Tiny, version 0.58:

           use utf8;
           use JSON::Tiny '0.58', qw(decode_json encode_json);
           use JSON::Parse;
           use JSON::Create;
           my $cream = '{"clapton":true,"hendrix":false}';
           my $jp = JSON::Parse->new ();
           my $jc = JSON::Create->new (sort => 1);

           print "First do a round-trip of our modules:\n\n";
           print $jc->create ($jp->parse ($cream)), "\n\n";

           print "Now do a round-trip of JSON::Tiny:\n\n";
           print encode_json (decode_json ($cream)), "\n\n";

           print "๐Ÿฅด First, incompatible mode:\n\n";
           print 'tiny(parse): ', encode_json ($jp->parse ($cream)), "\n";
           print 'create(tiny): ', $jc->create (decode_json ($cream)), "\n\n";

           # Set our parser to produce these things as literals:
           $jp->set_true (JSON::Tiny::true);
           $jp->set_false (JSON::Tiny::false);

           print "๐Ÿ”„ Compatibility with JSON::Parse:\n\n";
           print 'tiny(parse):', encode_json ($jp->parse ($cream)), "\n\n";
           $jc->bool ('JSON::Tiny::_Bool');

           print "๐Ÿ”„ Compatibility with JSON::Create:\n\n";
           print 'create(tiny):', $jc->create (decode_json ($cream)), "\n\n";

           print "๐Ÿ”„ JSON::Parse and JSON::Create are still compatible too:\n\n";
           print $jc->create ($jp->parse ($cream)), "\n";

       produces output

           First do a round-trip of our modules:

           {"clapton":true,"hendrix":false}

           Now do a round-trip of JSON::Tiny:

           {"clapton":true,"hendrix":false}

           ๐Ÿฅด First, incompatible mode:

           tiny(parse): {"clapton":1,"hendrix":""}
           create(tiny): {"clapton":1,"hendrix":0}

           ๐Ÿ”„ Compatibility with JSON::Parse:

           tiny(parse):{"clapton":true,"hendrix":false}

           ๐Ÿ”„ Compatibility with JSON::Create:

           create(tiny):{"clapton":true,"hendrix":false}

           ๐Ÿ”„ JSON::Parse and JSON::Create are still compatible too:

           {"clapton":true,"hendrix":false}

       (This example is included as json-tiny-round-trip-demo.pl
       <https://fastapi.metacpan.org/source/BKB/JSON-Parse-0.62/examples/json-tiny-round-trip-
       demo.pl> in the distribution.)

       Most of the other CPAN modules use similar methods to JSON::Tiny, so the above example can
       easily be adapted. See also "Interoperability" in JSON::Create for various examples.

       Modifying the values

       "parse_json" maps all the literals to read-only values. Because of this, attempting to
       modifying the boolean values in the hash reference returned by "parse_json" will cause
       "Modification of a read-only value attempted" errors:

           my $in = '{"hocus":true,"pocus":false,"focus":null}';
           my $p = json_parse ($in);
           $p->{hocus} = 99;
           # "Modification of a read-only value attempted" error occurs

       Since the hash values are read-only scalars, "$p->{hocus} = 99" is like this:

           undef = 99;

       If you need to modify the returned hash reference, then delete the value first:

           my $in = '{"hocus":true,"pocus":false,"focus":null}';
           my $p = json_parse ($in);
           delete $p->{pocus};
           $p->{pocus} = 99;
           # OK

       Similarly with array references, delete the value before altering:

           my $in = '[true,false,null]';
           my $q = json_parse ($in);
           delete $q->[1];
           $q->[1] = 'magic';

       Note that the return values from parsing bare literals are not read-only scalars, so

           my $true = JSON::Parse::json_parse ('true');
           $true = 99;

       produces no error. This is because Perl copies the scalar.

RESTRICTIONS

       This module imposes the following restrictions on its input.

       JSON only
           JSON::Parse is a strict parser. It only accepts input which exactly meets the criteria
           of "RFC 8259". That means, for example, JSON::Parse does not accept single quotes (')
           instead of double quotes ("), or numbers with leading zeros, like 0123. JSON::Parse
           does not accept control characters (0x00 - 0x1F) in strings, missing commas between
           array or hash elements like "["a" "b"]", or trailing commas like "["a","b","c",]". It
           also does not accept trailing non-whitespace, like the second "]" in "["a"]]".

           You may find "JSON::Repair" by the same authors as JSON::Parse useful if you need to
           process JSON-like text with tolerance for errors.

       No incremental parsing
           JSON::Parse does not parse incrementally. It only parses fully-formed JSON strings
           which include all opening and closing brackets. This is an inherent part of the design
           of the module. Incremental parsing in the style of XML::Parser would require some kind
           of callback structure to deal with the elements of the partially digested structures,
           but JSON::Parse was never designed to do this; it merely converts what it sees into a
           Perl structure. Claims to offer incremental JSON parsing in other modules'
           documentation should be diligently verified.

       UTF-8 only
           JSON::Parse only parses the UTF-8 format. If input is in a different Unicode encoding
           than UTF-8, convert the input before handing it to this module. For example, for the
           UTF-16 format,

               use Encode 'decode';
               my $input_utf8 = decode ('UTF-16', $input);
               my $perl = parse_json ($input_utf8);

           or, for a file, use ":encoding" (see PerlIO::encoding and perluniintro):

               open my $input, "<:encoding(UTF-16)", 'some-json-file';

           JSON::Parse does not try to determine the nature of the octet stream using BOM
           markers. A BOM marker in the input consists of bytes 0xFE and 0xFF, both of which are
           invalid as UTF-8, and thus will cause a fatal error.

           This restriction to UTF-8 applies regardless of whether Perl thinks that the input
           string is a character string or a byte string. Non-UTF-8 input will cause an
           "Unexpected character" error.

           The latest specification for JSON, "RFC 8259", specifies it to be a UTF-8 only format.

           JSON::Parse does not accept Unicode non-characters (U+FFFF, UFDDO, etc.), UTF-8
           representing surrogate pair code points, or bytes outside the range of Unicode code
           points as UTF-8 bytes.

DIAGNOSTICS

       "valid_json" does not produce error messages. "parse_json" and "assert_valid_json" die on
       encountering invalid input. "parse_json_safe" uses "carp" in Carp to pass error messages
       as warnings.

       Error messages have the line number, and the byte number where appropriate, of the input
       which caused the problem. The line number is formed simply by counting the number of "\n"
       (linefeed, ASCII 0x0A) characters in the whitespace part of the JSON.

       In "parse_json" and "assert_valid_json", parsing errors are fatal, so to continue after an
       error occurs, put the parsing into an "eval" block:

           my $p;
           eval {
               $p = parse_json ($j);
           };
           if ($@) {
               # handle error
           }

       The following error messages are produced:

       Unexpected character
           An unexpected character (byte) was encountered in the input. For example, when looking
           at the beginning of a string supposedly containing JSON, if the module encounters a
           plus sign, it will give an error like this:

               assert_valid_json ('+');

           gives output

               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'

           The message always includes a list of what characters are allowed.

           If there is some recognizable structure being parsed, the error message will include
           its starting point in the form "starting from byte n":

               assert_valid_json ('{"this":"\a"}');

           gives output

               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'

           A feature of JSON is that parsing it requires only one byte to be examined at a time.
           Thus almost all parsing problems can be handled using the "Unexpected character" error
           type, including spelling errors in literals:

               assert_valid_json ('[true,folse]');

           gives output

               JSON error at line 1, byte 8/12: Unexpected character 'o' parsing literal starting from byte 7: expecting 'a'

           and the missing second half of a surrogate pair:

               assert_valid_json ('["\udc00? <-- should be a second half here"]');

           gives output

               JSON error at line 1, byte 9/44: Unexpected character '?' parsing unicode escape starting from byte 3: expecting '\'

           All kinds of errors can occur parsing numbers, for example a missing fraction,

               assert_valid_json ('[1.e9]');

           gives output

               JSON error at line 1, byte 4/6: Unexpected character 'e' parsing number starting from byte 2: expecting digit: '0-9'

           and a leading zero,

               assert_valid_json ('[0123]');

           gives output

               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'

           The error message is this complicated because all of the following are valid here:
           whitespace: "[0 ]"; comma: "[0,1]", end of array: "[0]", dot: "[0.1]", or exponential:
           "[0e0]".

           These are all handled by this error.  Thus the error messages are a little confusing
           as diagnostics.

           Versions of this module prior to 0.29 gave more informative messages like "leading
           zero in number". (The messages weren't documented.) The reason to change over to the
           single message was because it makes the parsing code simpler, and because the testing
           code described in "TESTING" makes use of the internals of this error to check that the
           error message produced actually do correspond to the invalid and valid bytes allowed
           by the parser, at the exact byte given.

           This is a bytewise error, thus for example if a miscoded UTF-8 appears in the input,
           an error message saying what bytes would be valid at that point will be printed.

               no utf8;
               use JSON::Parse 'assert_valid_json';

               # Error in first byte:

               my $bad_utf8_1 = chr (hex ("81"));
               eval { assert_valid_json ("[\"$bad_utf8_1\"]"); };
               print "$@\n";

               # Error in third byte:

               my $bad_utf8_2 = chr (hex ('e2')) . chr (hex ('9C')) . 'b';
               eval { assert_valid_json ("[\"$bad_utf8_2\"]"); };
               print "$@\n";

           prints

               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.

               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.

       Unexpected end of input
           The end of the string was encountered before the end of whatever was being parsed was.
           For example, if a quote is missing from the end of the string, it will give an error
           like this:

               assert_valid_json ('{"first":"Suzuki","second":"Murakami","third":"Asada}');

           gives output

               JSON error at line 1: Unexpected end of input parsing string starting from byte 47

       Not surrogate pair
           While parsing a string, a surrogate pair was encountered. While trying to turn this
           into UTF-8, the second half of the surrogate pair turned out to be an invalid value.

               assert_valid_json ('["\uDC00\uABCD"]');

           gives output

               JSON error at line 1: Not surrogate pair parsing unicode escape starting from byte 11

       Empty input
           This error occurs for an input which is an empty (no length or whitespace only) or an
           undefined value.

               assert_valid_json ('');

           gives output

               JSON error: Empty input parsing initial state

           Prior to version 0.49, this error was produced by "assert_valid_json" only, but it is
           now also produced by "parse_json".

       Name is not unique
           This error occurs when parsing JSON when the user has chosen "detect_collisions". For
           example an input like

               my $p = JSON::Parse->new ();
               $p->detect_collisions (1);
               $p->run ('{"hocus":1,"pocus":2,"hocus":3}');

           gives output

               JSON error at line 1, byte 23/31: Name is not unique: "hocus" parsing object starting from byte 1 at blib/lib/JSON/Parse.pm line 131.

           where the JSON object has two keys with the same name, "hocus". The terminology "name
           is not unique" is from the JSON specification.

       Contradictory values for "true" and "false"
           User-defined value for JSON false evaluates as true
               This happens if you set JSON false to map to a true value:

                   $jp->set_false (1);

               To switch off this warning, use "no_warn_literals".

               ๐ŸŽฒ This warning was added in version 0.38.

           User-defined value for JSON true evaluates as false
               This happens if you set JSON true to map to a false value:

                   $jp->set_true (undef);

               To switch off this warning, use "no_warn_literals".

               ๐ŸŽฒ This warning was added in version 0.38.

           User-defined value overrules copy_literals
               This warning is given if you set up literals with "copy_literals" then you also
               set up your own true, false, or null values with "set_true", "set_false", or
               "set_null".

               ๐ŸŽฒ This warning was added in version 0.38.

PERFORMANCE

       On the author's computer, the module's speed of parsing is approximately the same as
       JSON::XS, with small variations depending on the type of input. For validation,
       "valid_json" is faster than any other module known to the author, and up to ten times
       faster than JSON::XS.

       Some special types of input, such as floating point numbers containing an exponential
       part, like "1e09", seem to be about two or three times faster to parse with this module
       than with JSON::XS. In JSON::Parse, parsing of exponentials is done by the system's
       "strtod" function, but JSON::XS contains its own parser for exponentials, so these results
       may be system-dependent.

       At the moment the main place JSON::XS wins over JSON::Parse is in strings containing
       escape characters, where JSON::XS is about 10% faster on the module author's computer and
       compiler. As of version 0.33, despite some progress in improving JSON::Parse, I haven't
       been able to fully work out the reason behind the better speed.

       There is some benchmarking code in the github repository under the directory "benchmarks"
       for those wishing to test these claims. The script benchmarks/bench
       <https://github.com/benkasminbullock/JSON-
       Parse/d04630086f6c92fea720cba4568faa0cbbdde5a6/benchmarks/bench> is an adaptation of the
       similar script in the JSON::XS distribution. The script benchmarks/pub-bench.pl
       <https://github.com/benkasminbullock/JSON-
       Parse/d04630086f6c92fea720cba4568faa0cbbdde5a6/benchmarks/pub-bench.pl> runs the
       benchmarks and prints them out as POD.

       The following benchmark tests used version 0.58_01 of JSON::Parse, version 4.03 of
       "JSON::XS", and version 4.25 of "Cpanel::JSON::XS" on Perl version v5.32.0 compiled with
       Clang version FreeBSD clang version 10.0.1 on FreeBSD 12.2. The files in the "benchmarks"
       directory of JSON::Parse. short.json and long.json are the benchmarks used by "JSON::XS".

       short.json
               Repetitions: 10 x 100 = 1000
               --------------+------------+------------+
               module        |      1/min |        min |
               --------------|------------|------------|
               Cpanel        | 313007.761 |  0.0000319 |
               JP::valid     | 838860.800 |  0.0000119 |
               JSON::Parse   | 310689.185 |  0.0000322 |
               JSON::XS      | 303935.072 |  0.0000329 |
               --------------+------------+------------+

       long.json
               Repetitions: 10 x 100 = 1000
               --------------+------------+------------+
               module        |      1/min |        min |
               --------------|------------|------------|
               Cpanel        |   5611.860 |  0.0017819 |
               JP::valid     |  13586.991 |  0.0007360 |
               JSON::Parse   |   4924.048 |  0.0020308 |
               JSON::XS      |   6406.452 |  0.0015609 |
               --------------+------------+------------+

       words-array.json
               Repetitions: 10 x 100 = 1000
               --------------+------------+------------+
               module        |      1/min |        min |
               --------------|------------|------------|
               Cpanel        |  34749.826 |  0.0002878 |
               JP::valid     | 270600.258 |  0.0000370 |
               JSON::Parse   |  34017.064 |  0.0002940 |
               JSON::XS      |  35726.610 |  0.0002799 |
               --------------+------------+------------+

       exp.json
               Repetitions: 10 x 100 = 1000
               --------------+------------+------------+
               module        |      1/min |        min |
               --------------|------------|------------|
               Cpanel        |  46759.242 |  0.0002139 |
               JP::valid     | 117817.528 |  0.0000849 |
               JSON::Parse   |  46759.242 |  0.0002139 |
               JSON::XS      |  19195.899 |  0.0005209 |
               --------------+------------+------------+

       literals.json
               Repetitions: 10 x 100 = 1000
               --------------+------------+------------+
               module        |      1/min |        min |
               --------------|------------|------------|
               Cpanel        |  33026.016 |  0.0003028 |
               JP::valid     | 384798.532 |  0.0000260 |
               JSON::Parse   |  40840.351 |  0.0002449 |
               JSON::XS      |  33689.189 |  0.0002968 |
               --------------+------------+------------+

       cpantesters.json
               Repetitions: 10 x 100 = 1000
               --------------+------------+------------+
               module        |      1/min |        min |
               --------------|------------|------------|
               Cpanel        |    212.377 |  0.0470860 |
               JP::valid     |   1309.043 |  0.0076392 |
               JSON::Parse   |    207.491 |  0.0481949 |
               JSON::XS      |    226.439 |  0.0441620 |
               --------------+------------+------------+

SEE ALSO

       RFC 8259
           JSON is specified in RFC 8259 "The JavaScript Object Notation (JSON) Data Interchange
           Format" <http://www.ietf.org/rfc/rfc8259.txt>.

       json.org
           <https://json.org> is the website for JSON, authored by Douglas Crockford.

   Other CPAN modules for parsing and producing JSON
       The โญ represents the number of votes this module has received on metacpan, on a
       logarithmic scale. Modules which we recommend are marked with ๐Ÿ‘. Deprecated modules and
       modules which are definitely buggy (bug reports/pull requests ignored) and abandoned (no
       releases for several years) are marked with ๐Ÿ‘Ž and/or ๐Ÿ›. Modules we can't work out are
       marked with ๐Ÿ˜•.

       Modules by the same author
           JSON::Create
               ๐Ÿ‘ JSON::Create is a companion module to JSON::Parse by the same author.

           JSON::Repair
               JSON::Repair is an example module which demonstrates using JSON::Parse to apply
               some kinds of heuristics to repair "relaxed JSON" or otherwise broken JSON into
               compliant JSON.

           JSON::Server
               JSON::Server is a module which offers a JSON-only, UTF-8 only server using
               "JSON::Parse" and "JSON::Create".

           JSON::Tokenize
               JSON::Tokenize is part of the JSON::Parse distribution, a tokenizer which reduces
               a JSON string to tokens. This makes the JSON::Parse tokenizer available to people
               who want to write their own JSON parsers.

           JSON::Whitespace
               JSON::Whitespace is for manipulating the "insignificant whitespace" part of JSON.

       Reading and writing JSON
           Cpanel::JSON::XS
               [โญโญ Author: RURBAN <https://metacpan.org/author/RURBAN>; Date: "2021-04-12";
               Version: 4.26]

               This is a fork of JSON::XS. Please see the module for details about the reasons
               for the fork.

           File::JSON::Slurper
               [โญ Author: NEILB <https://metacpan.org/author/NEILB>; Date: "2020-11-18";
               Version: 1.00]

               Slurp a JSON file into a data structure, and the reverse. It relies on
               "JSON::MaybeXS".

           Glib::JSON
               [โญ Author: EBASSI <https://metacpan.org/author/EBASSI>; Date: "2015-04-19";
               Version: 0.002]

               Uses the JSON library from Glib, a library of C functions for the Linux GNOME
               desktop project, so it is independent of the other CPAN modules. Judging from the
               fairly sparse documentation, it seems to be a module where you build the JSON on
               the fly rather than converting a Perl structure wholesale into JSON.

           JSON
               [โญโญ Author: ISHIGAKI <https://metacpan.org/author/ISHIGAKI>; Date: "2021-01-24";
               Version: 4.03]

               This calls on either JSON::PP or JSON::XS.

           JSON::DWIW
               [Author: DOWENS <https://metacpan.org/author/DOWENS>; Date: "2010-09-29"; Version:
               0.47]

               ๐Ÿ‘Ž๐Ÿ› This module "Does What I Want", where "I" refers to the module's author.
               Development seems to have ceased in 2010, there is a long list of unfixed bugs,
               and some of the module's features seem to predate Unicode support in Perl. It is
               written in XS, and it claims to accept a wide variety of non-JSON formats such as
               comments, single-quoted strings, trailing commas, etc.

           JSON::Parser::Regexp
               [Author: RAJ <https://metacpan.org/author/RAJ>; Date: "2021-03-16"; Version: 0.04]

               Uses Regexp::Grammars to parse JSON.

           JSON::PP
               [โญโญ Author: ISHIGAKI <https://metacpan.org/author/ISHIGAKI>; Date: "2021-01-23";
               Version: 4.06]

               This is part of the Perl core, installed when you install Perl. "PP" stands for
               "Pure Perl", which means it is in Perl-only without the XS (C-based) parsing. This
               is slower but may be necessary if you cannot install modules requiring a C
               compiler.

           JSON::Slurper
               [โญ Author: SRCHULO <https://metacpan.org/author/SRCHULO>; Date: "2019-10-30";
               Version: 0.12]

               Convenient file slurping and spurting of data using JSON. Uses "JSON::PP" or
               "Cpanel::JSON::XS" if available. The basic idea seems to be that it uses context
               to return arrays or hashes as required, and read and write files without extra
               stages of opening and closing the file.

           JSON::Syck
               [โญโญ Author: TODDR <https://metacpan.org/author/TODDR>; Date: "2020-10-26";
               Version: 1.34]

               ๐Ÿ‘Ž๐Ÿ› Takes advantage of a similarity between YAML (yet another markup language)
               and JSON to provide a JSON parser/producer using YAML::Syck.

               We have never tried this module, but it seems to be semi-deprecated (the ABSTRACT
               says "consider using JSON::XS instead!")  and there are a lot of bug reports
               <https://github.com/toddr/YAML-Syck/issues> about things like failing to process
               equals signs. However, the maintainer is fixing some of the bugs and making new
               releases, so we're not really sure.

           JSON::Tiny
               [โญโญ Author: DAVIDO <https://metacpan.org/author/DAVIDO>; Date: "2017-11-12";
               Version: 0.58]

               This is a fork of "Mojo::JSON".

           JSON::XS
               [โญโญโญ Author: MLEHMANN <https://metacpan.org/author/MLEHMANN>; Date:
               "2020-10-27"; Version: 4.03]

               This is an all-purpose JSON module in XS, which means it requires a C compiler to
               install.

           JSON::YAJL
               [โญ Author: LBROCARD <https://metacpan.org/author/LBROCARD>; Date: "2011-08-05";
               Version: 0.10]

               ๐Ÿ‘Ž๐Ÿ› Wraps a C library called yajl. The module has been abandoned since ten years
               ago. Bug reports include serious errors, and pull requests have been ignored.

           Mojo::JSON
               [โญโญโญ Author: SRI <https://metacpan.org/author/SRI>; Date: "2021-04-13";
               Version: 9.17]

               Part of the Mojolicious standalone web framework, "pure Perl" JSON reader/writer.
               As of version 8.70 of Mojolicious, this actually depends on "JSON::PP" but will
               load "Cpanel::JSON::XS" if it is available.

       Combination modules
           These modules rely on more than one back-end module to process JSON for you.

           JSON::Any
               [โญ Author: ETHER <https://metacpan.org/author/ETHER>; Date: "2015-06-10";
               Version: 1.39]

               ๐Ÿ‘Ž This now-deprecated module combines "JSON::DWIW", "JSON::XS" versions one and
               two, and "JSON::Syck".

           JSON::MaybeXS
               [โญโญ Author: ETHER <https://metacpan.org/author/ETHER>; Date: "2020-11-13";
               Version: 1.004003]

               A module which combines "Cpanel::JSON::XS", "JSON::XS", and "JSON::PP". The
               original "JSON" combines "JSON::XS" and "JSON::PP", but this prioritizes
               "Cpanel::JSON::XS" over "JSON::XS".

           JSON::XS::VersionOneAndTwo
               [Author: LBROCARD <https://metacpan.org/author/LBROCARD>; Date: "2008-02-13";
               Version: 0.31]

               ๐Ÿ‘Ž A "combination module" which supports two different interfaces of "JSON::XS".
               However, JSON::XS is now onto version 4.

           Mojo::JSON::MaybeXS
               [โญ Author: DBOOK <https://metacpan.org/author/DBOOK>; Date: "2019-08-07";
               Version: 1.002]

               ๐Ÿ‘Ž This pulls in "JSON::MaybeXS" instead of "Mojo::JSON" for Mojolicious users. It
               seems to have been rendered obsolete by modern versions of Mojolicious due to
               changes to make that depend on "Cpanel::JSON::XS" if available.

       Test-related modules
           Test2::Tools::JSON
               [Author: AKIYM <https://metacpan.org/author/AKIYM>; Date: "2019-08-07"; Version:
               0.05]

           Test::Deep::JSON
               [โญ Author: MOTEMEN <https://metacpan.org/author/MOTEMEN>; Date: "2018-04-24";
               Version: 0.05]

               Compare JSON with Test::Deep. As of version 0.05, it relies on "JSON::MaybeXS".

           Test::JSON
               [โญ Author: OVID <https://metacpan.org/author/OVID>; Date: "2009-08-09"; Version:
               0.11]

               ๐Ÿ‘Ž This offers a way to compare two different JSON strings to see if they refer to
               the same object. The most recent version, 0.11, was released in 2009, and it
               relies on the deprecated "JSON::Any", which makes it essentially abandoned.

           Test::JSON::Entails
               [Author: VOJ <https://metacpan.org/author/VOJ>; Date: "2012-09-14"; Version: 0.2]

               ๐Ÿ‘Ž Test whether one JSON or Perl structure entails/subsumes another. The most
               recent version is from 2012, and it relies on "JSON::Any", so it is probably
               abandoned. Also, oddly but not uniquely for CPAN modules with the name JSON in the
               title, it seems to not actually have that much to do with JSON, which is a data
               serialisation format, but actually be testing Perl hashes and arrays.

           Test::JSON::More
               [Author: BAYASHI <https://metacpan.org/author/BAYASHI>; Date: "2016-04-28";
               Version: 0.02]

               JSON Test Utility. As of version 0.02, it relies on "JSON" but it is able to use
               "JSON::XS" instead, and so probably "Cpanel::JSON::XS" would be OK too. According
               to the documentation, it can test JSON for validity and compare JSON strings with
               keys in a different order, and presumably with different whitespace.

       Type-related modules
           These untangle numbers, strings, and booleans into JSON types.

           JSON::TypeInference
               [Author: AEREAL <https://metacpan.org/author/AEREAL>; Date: "2015-10-26"; Version:
               "v1.0.2"]

               ๐Ÿ˜• Virtually undocumented, it's not clear what this does.

           JSON::Types
               [โญ Author: TYPESTER <https://metacpan.org/author/TYPESTER>; Date: "2012-10-17";
               Version: 0.05]

               Change the type of a Perl variable so that it comes out as a number, a string, or
               a boolean in the output JSON.

           JSON::Types::Flexible
               [Author: PINE <https://metacpan.org/author/PINE>; Date: "2017-04-01"; Version:
               0.03]

               The module is barely documented, but from looking at the test file
               <https://metacpan.org/source/PINE/JSON-Types-
               Flexible-0.03/t%2Fjson%2Ftypes%2Fflexible%2Fclass.t>, this seems to enable you to
               change the output type of a number or a string so that you can, for example, make
               the number 1 come out as either a number, 1, a string "1", or a boolean, "true",
               in the output JSON.

           JSON::Typist
               [โญ Author: RJBS <https://metacpan.org/author/RJBS>; Date: "2021-05-03"; Version:
               0.007]

               "Replace mushy strings and numbers with rigidly typed replacements"

               Since Perl muddles strings and numbers, this enables you to work out whether your
               input JSON was "123" (a string) or 123 (a number).

       Special-purpose modules
           App::JSON::to
               [โญ Author: DOLMEN <https://metacpan.org/author/DOLMEN>; Date: "2015-03-04";
               Version: 1.000]

               Convert JSON data to other formats. It reads your JSON file or input and converts
               it into either YAML or Perl native format using Data::Dumper.

           boolean
               [โญโญ Author: INGY <https://metacpan.org/author/INGY>; Date: "2016-07-08";
               Version: 0.46]

               ๐Ÿ‘ This module offers "true" and "false" literals in Perl, so you just have

                   use boolean;
                   my $something = true;

               This is very useful for dealing with JSON.

           Config::JSON
               [Author: RIZEN <https://metacpan.org/author/RIZEN>; Date: "2014-12-25"; Version:
               1.5202]

               Configuration files in JSON, with hash comments also allowed.

           Devel::JSON
               [โญ Author: DOLMEN <https://metacpan.org/author/DOLMEN>; Date: "2017-09-03";
               Version: 1.001]

               For one-liners.

                   If you use this module from the command-line, the last value of your one-liner
                   (-e) code will be serialized as JSON data.

           Inline::JSON
               [Author: KILNA <https://metacpan.org/author/KILNA>; Date: "2012-07-27"; Version:
               "v1.0.4"]

               "Embed JSON data structures directly into your Perl code". Relies on "JSON".

           JSON::Builder
               [Author: KNI <https://metacpan.org/author/KNI>; Date: "2015-04-16"; Version: 0.04]

               Create JSON under memory limitations.

           JSON::Color
               [โญ Author: PERLANCAR <https://metacpan.org/author/PERLANCAR>; Date: "2021-05-07";
               Version: 0.131]

               ๐ŸŒˆ This module generates JSON colorized with ANSI escape sequences.

           JSON_File
               [โญ Author: GETTY <https://metacpan.org/author/GETTY>; Date: "2014-09-11";
               Version: 0.004]

           JSON::MultiValueOrdered
               [Author: TOBYINK <https://metacpan.org/author/TOBYINK>; Date: "2020-01-27";
               Version: 0.006]

               "JSON::MultiValueOrdered" is a special-purpose module for parsing JSON objects
               which have key collisions (something like "{"a":1,"a":2}") within objects.

               (JSON::Parse's handling of key collisions is discussed in "Key collisions" in this
               document.)

           JSON::String
               [Author: BRUMMETT <https://metacpan.org/author/BRUMMETT>; Date: "2015-02-04";
               Version: "v0.2.0"]

               Automatically change a JSON string when a data structure changes using tied
               scalars.

       Patch, path, pointer, schema, and transform modules
           JSON::Assert
               [Author: SGREEN <https://metacpan.org/author/SGREEN>; Date: "2017-07-07"; Version:
               0.08]

               "Asserts JSONPaths into a JSON data structure for correct values/matches"

           JSON::Conditional
               [Author: LNATION <https://metacpan.org/author/LNATION>; Date: "2021-03-29";
               Version: 1.00]

           JSON::GRDDL
               [Author: TOBYINK <https://metacpan.org/author/TOBYINK>; Date: "2014-09-11";
               Version: 0.002]

           JSON::Hyper
               [โญ Author: TOBYINK <https://metacpan.org/author/TOBYINK>; Date: "2012-10-12";
               Version: 0.011]

           JSON::JQ
               [Author: DONGXU <https://metacpan.org/author/DONGXU>; Date: "2021-05-16"; Version:
               0.06]

               Perl access to the "jq" tool via Alien::LibJQ.

           JSON::MergePatch
               [โญ Author: SOJIRO <https://metacpan.org/author/SOJIRO>; Date: "2016-02-24";
               Version: 0.04]

           JSON::Patch
               [Author: MIXAS <https://metacpan.org/author/MIXAS>; Date: "2018-10-25"; Version:
               0.04]

               ๐Ÿ˜• We don't know what this does, or how it relates to JSON. The example in the
               synopsis section of the document doesn't show any JSON, it shows an example of
               altering nested hashes in Perl.

           JSON::Path
               [โญ Author: POPEFELIX <https://metacpan.org/author/POPEFELIX>; Date: "2021-01-28";
               Version: 0.431]

               Search nested hashref/arrayref structures using JSONPath.

           JSON::Pointer
               [โญ Author: ZIGOROU <https://metacpan.org/author/ZIGOROU>; Date: "2015-08-13";
               Version: 0.07]

               Extract parts of a JSON string.

           JSON::Schema::ToJSON
               [โญ Author: LEEJO <https://metacpan.org/author/LEEJO>; Date: "2021-04-06";
               Version: 0.19]

               "Generate example JSON structures from JSON Schema definitions"

           JSON::T
               [โญ Author: TOBYINK <https://metacpan.org/author/TOBYINK>; Date: "2014-09-28";
               Version: 0.104]

               Transform JSON using JsonT

           JSON::Transform
               [โญ Author: ETJ <https://metacpan.org/author/ETJ>; Date: "2020-01-01"; Version:
               0.03]

           JSON::Validator
               [โญโญ Author: JHTHORSEN <https://metacpan.org/author/JHTHORSEN>; Date:
               "2021-04-28"; Version: 4.17]

               "Validate data against a JSON schema" - you can decide what the JSON is supposed
               to contain.

           Template::Plugin::JSON
               [Author: ETHER <https://metacpan.org/author/ETHER>; Date: "2019-03-07"; Version:
               0.08]

               "Adds a .json vmethod for all TT values." - for use with Template.

       JSON extensions
           These modules extend JSON with comments and other things.

           JSON::Diffable
               [โญ Author: PHAYLON <https://metacpan.org/author/PHAYLON>; Date: "2014-12-10";
               Version: 0.000002]

               "A relaxed and easy diffable JSON variant"

           JSON::Relaxed
               [Author: MIKO <https://metacpan.org/author/MIKO>; Date: "2016-04-30"; Version:
               0.05]

               "An extension of JSON that allows for better human-readability".

           JSON::WithComments
               [Author: RJRAY <https://metacpan.org/author/RJRAY>; Date: "2017-09-02"; Version:
               0.003]

           JSONY
               [โญ Author: INGY <https://metacpan.org/author/INGY>; Date: "2020-04-27"; Version:
               "v0.1.21"]

               "Relaxed JSON with a little bit of YAML"

       Web interactions via JSON
           Crypt::JWT
               [โญโญ Author: MIK <https://metacpan.org/author/MIK>; Date: "2021-05-01"; Version:
               0.033]

               Module covers JSON Web Tokens, JSON Web Signature, and JSON Web Encryption.

           JSON::API
               [โญ Author: GFRANKS <https://metacpan.org/author/GFRANKS>; Date: "2019-07-01";
               Version: "v1.1.1"]

               Combines LWP::UserAgent and JSON to make a unified module to communicate with a
               web server via JSON.

           LWP::JSON::Tiny
               [โญ Author: SKINGTON <https://metacpan.org/author/SKINGTON>; Date: "2018-05-11";
               Version: 0.014]

           WWW::JSON
               [โญ Author: ANTIPASTA <https://metacpan.org/author/ANTIPASTA>; Date: "2015-05-27";
               Version: 1.02]

               "Make working with JSON Web API's as painless as possible"

       Extension modules
           These modules extend the existing modules with some extra bits.

           JSON::XS::Sugar
               [Author: MAXMIND <https://metacpan.org/author/MAXMIND>; Date: "2015-04-01";
               Version: 1.01]

               Provides booleans and number/string forcing for "JSON::XS".

           Silki::JSON
               [โญ Author: DROLSKY <https://metacpan.org/author/DROLSKY>; Date: "2011-09-19";
               Version: 0.29]

               Switches on formatting and strict utf8 in a "JSON::XS" object.

       Demonstration modules
           These modules provide a JSON parser as a demonstration of another technology.

           JSON::Decode::Marpa
               [Author: PERLANCAR <https://metacpan.org/author/PERLANCAR>; Date: "2014-08-27";
               Version: 0.02]

           JSON::Decode::Regexp
               [Author: PERLANCAR <https://metacpan.org/author/PERLANCAR>; Date: "2018-03-25";
               Version: 0.101]

               ๐Ÿ›๐ŸฆŸ๐Ÿฆ‹๐Ÿž JSON parser as a single Perl Regex, originally by Randal Schwartz. This
               may be ingenious, but it's not remotely a useful JSON parser. For example, looking
               at the string part, it provides no Unicode validation, no support for Unicode
               escapes <https://metacpan.org/release/JSON-Decode-
               Regexp/source/lib/JSON/Decode/Regexp.pm#L141> and it allows invalid escapes such
               as "\xFF" <https://metacpan.org/release/JSON-Decode-
               Regexp/source/lib/JSON/Decode/Regexp.pm#L137>.

           MarpaX::Demo::JSONParser
               [Author: RSAVAGE <https://metacpan.org/author/RSAVAGE>; Date: "2019-06-18";
               Version: 1.08]

           Pegex::JSON
               [Author: INGY <https://metacpan.org/author/INGY>; Date: "2020-01-22"; Version:
               0.31]

               ๐Ÿ› Based on Pegex.  See our bug report <https://github.com/pegex-parser/pegex-
               json-pm/issues/3>.

       Other modules
           Modules which are parts of bigger distributions have not been included here except by
           accident.

           App::JSON::Tools
               [Author: KABLAMO <https://metacpan.org/author/KABLAMO>; Date: "2016-08-05";
               Version: 0.01]

               Undocumented command-line tools for JSON.

           App::JSONPretty
               [โญ Author: MSTROUT <https://metacpan.org/author/MSTROUT>; Date: "2011-02-02";
               Version: 1]

               ๐Ÿ‘Ž๐Ÿ› JSON prettification script. For whatever reason the script encapsulates the
               entirety of an old version of the "JSON" module dating from before "JSON::PP" was
               included in the Perl core.

               If you need this kind of script, there is something called json_xs which comes
               with "JSON::XS", or equivalently cpanel_json_xs in the forked module
               "Cpanel::JSON::XS".

           ARGV::JSON
               [โญ Author: MOTEMEN <https://metacpan.org/author/MOTEMEN>; Date: "2013-12-18";
               Version: 0.01]

           Jasonify
               [Author: BOBK <https://metacpan.org/author/BOBK>; Date: "2020-03-04"; Version:
               "v0.20.064"]

           JS::JSON
               [Author: INGY <https://metacpan.org/author/INGY>; Date: "2008-08-30"; Version:
               0.02]

               ๐Ÿ‘Ž This is JavaScript code which was uploaded to CPAN. The original JavaScript is
               now obsolete since the thing it codes is included in all modern web browsers.

           JSON::Eval
               [Author: TOBYINK <https://metacpan.org/author/TOBYINK>; Date: "2019-10-27";
               Version: 0.002]

               Eval Perl code found in JSON. This module enables one to encode and decode Perl
               scalar references and code references to JSON.

           JSON::ize
               [โญ Author: MAJENSEN <https://metacpan.org/author/MAJENSEN>; Date: "2019-07-13";
               Version: 0.202]

           JSON::JSend
               [Author: HOEKIT <https://metacpan.org/author/HOEKIT>; Date: "2016-04-23"; Version:
               0.02]

           JSON::Lines
               [โญ Author: LNATION <https://metacpan.org/author/LNATION>; Date: "2021-03-29";
               Version: 1.00]

               "JSON Lines is a convenient format for storing structured data that may be
               processed one record at a time."

           JSON::Meth
               [โญ Author: ZOFFIX <https://metacpan.org/author/ZOFFIX>; Date: "2015-11-28";
               Version: 1.001007]

               ๐Ÿ˜• Claims to be "no nonsense JSON encoding/decoding as method calls on data". From
               the documentation:

                   Don't make me think and give me what I want! This module automatically figures
                   out whether you want to encode a Perl data structure to JSON or decode a JSON
                   string to a Perl data structure.

           JSON::ON
               [Author: EWILHELM <https://metacpan.org/author/EWILHELM>; Date: "2013-06-26";
               Version: "v0.0.3"]

               JavaScript object notation object notator.

           JSON::SL
               [โญ Author: MNUNBERG <https://metacpan.org/author/MNUNBERG>; Date: "2017-11-10";
               Version: "v1.0.7"]

           JSON::Streaming::Reader
               [โญ Author: MART <https://metacpan.org/author/MART>; Date: "2012-11-24"; Version:
               0.06]

           JSON::Streaming::Writer
               [Author: MART <https://metacpan.org/author/MART>; Date: "2012-11-24"; Version:
               0.03]

           JSON::Util
               [Author: JKUTEJ <https://metacpan.org/author/JKUTEJ>; Date: "2015-09-03"; Version:
               0.06]

               Relies on JSON::MaybeXS and the author's other module IO::Any, so that you can put
               either a file name or a JSON string as the argument and it tries to work out which
               one you have given it. That is ingenious, but it seems that if you are a
               programmer who cannot distinguish whether your input string is a file name or
               JSON, you have a very serious problem.

           JSON::XS::ByteString
               [โญ Author: CINDY <https://metacpan.org/author/CINDY>; Date: "2020-04-18";
               Version: 1.004]

               ๐Ÿ˜• The README <https://metacpan.org/source/CINDY/JSON-XS-ByteString-1.004/README>
               claims it is a "thin wrapper around JSON::XS", but it contains a complete
               implementation of JSON <https://metacpan.org/source/CINDY/JSON-XS-
               ByteString-1.004/ByteString.xs>, which seems to have partly been copy-pasted from
               the JSON::XS source code, but internally it doesn't make any reference to
               JSON::XS. The licence and copyright statement don't mention JSON::XS's original
               author at all so we're not sure if this is a fork, a wrapper, or a
               reimplementation.

               We haven't tried downloading this or installing it, but according to the
               documentation, this module encodes numbers with quotes around them, so "{this =>
               2}" turns into "{"this":"2"}".

           JSON_minify
               [Author: RCOSCALI <https://metacpan.org/author/RCOSCALI>; Date: "2021-01-24";
               Version: 1.1]

           Text::JSON::Nibble
               [Author: DAEMON <https://metacpan.org/author/DAEMON>; Date: "2017-05-02"; Version:
               1.01]

               Nibble complete JSON objects from buffers.

               This seems to be for extracting JSON from the midst of noise.

SCRIPT

       A script "validjson" is supplied with the module. This runs "assert_valid_json" on its
       inputs, so run it like this.

            validjson *.json

       The default behaviour is to just do nothing if the input is valid. For invalid input it
       prints what the problem is:

           validjson ids.go
           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'.

       If you need confirmation, use its --verbose option:

           validjson -v *.json

           atoms.json is valid JSON.
           ids.json is valid JSON.
           kanjidic.json is valid JSON.
           linedecomps.json is valid JSON.
           radkfile-radicals.json is valid JSON.

DEPENDENCIES

       Carp

EXPORTS

       The module exports nothing by default. Functions "parse_json", "parse_json_safe",
       "read_json", "valid_json" and "assert_valid_json", as well as the old function names
       "validate_json", "json_file_to_perl", and "json_to_perl", can be exported on request.

       All of the functions can be exported using the tag ':all':

           use JSON::Parse ':all';

TESTING

   Internal testing code
       The module incorporates extensive testing related to the production of error messages and
       validation of input. Some of the testing code is supplied with the module in the /t/
       subdirectory of the distribution.

       More extensive testing code is in the git repository. This is not supplied in the CPAN
       distribution. A script, randomjson.pl <https://github.com/benkasminbullock/JSON-
       Parse/d04630086f6c92fea720cba4568faa0cbbdde5a6/randomjson.pl>, generates a set number of
       bytes of random JSON and checks that the module's bytewise validation of input is correct.
       It does this by taking a valid fragment, then adding each possible byte from 0 to 255 to
       see whether the module correctly identifies it as valid or invalid at that point, then
       randomly picking one of the valid bytes and adding it to the fragment and continuing the
       process until a complete valid JSON input is formed. The module has undergone about a
       billion repetitions of this test.

       This setup relies on a C file, json-random-test.c
       <https://github.com/benkasminbullock/JSON-
       Parse/d04630086f6c92fea720cba4568faa0cbbdde5a6/json-random-test.c>, which isn't in the
       CPAN distribution, and it also requires Json3.xs
       <https://github.com/benkasminbullock/JSON-
       Parse/d04630086f6c92fea720cba4568faa0cbbdde5a6/Json3.xs> to be edited to make the macro
       "TESTRANDOM" true (uncomment line 7 of the file). The testing code uses C setjmp/longjmp,
       so it's not guaranteed to work on all operating systems and is commented out for CPAN
       releases.

       A pure C version called random-test.c <https://github.com/benkasminbullock/JSON-
       Parse/d04630086f6c92fea720cba4568faa0cbbdde5a6/random-test.c> also exists. This applies
       exactly the same tests, and requires no Perl at all.

       If you're interested in testing your own JSON parser, the outputs generated by
       randomjson.pl <https://github.com/benkasminbullock/JSON-
       Parse/d04630086f6c92fea720cba4568faa0cbbdde5a6/randomjson.pl> are quite a good place to
       start. The default is to produce UTF-8 output, which looks pretty horrible since it tends
       to produce long strings of UTF-8 garbage. (This is because it chooses randomly from 256
       bytes and the end-of-string marker """ has only a 1/256 chance of being chosen, so the
       strings tend to get long and messy). You can mess with the internals of JSON::Parse by
       setting MAXBYTE in json-common.c to 0x80, recompiling (you can ignore the compiler
       warnings), and running randomjson.pl again to get just ASCII random JSON things. This
       breaks the UTF-8 functionality of JSON::Parse, so please don't install that version.

   JSON Parsing Test Suite
       JSON::Parse version 0.58 passes most of the JSON Parsing Test Suite, with the exception
       that JSON::Parse rejects various erroneous UTF-8 inputs, for example JSON::Parse will
       throw an error for non-character code points like Unicode U+FFFF and U+10FFFF. This parser
       only accepts valid UTF-8 as input. See "UTF-8 only".

       In our opinion it would be a disservice to users of this module to allow bytes containing
       useless fragments such as incomplete parts of surrogate pairs, or invalid characters, just
       because the JSON specification doesn't actually explicitly demand rejecting these kinds of
       garbage inputs. Please see the function "daft_test" in the file xt/JPXT.pm for exactly
       which of these elements of the test suite we do not comply with. We note that this comment
       from Douglas Crockford, the inventor of JSON, JSON parser
       <https://github.com/douglascrockford/JSON-c/blob/master/utf8_decode.c#L38-L43>, dated
       2005, agrees with our opinion on this point.

       JSON::Parse version 0.58 also introduced "get_max_depth" and "set_max_depth" to prevent
       the stack overflow errors caused by some very deeply nested inputs such as those of the
       JSON Parsing Test Suite.

ACKNOWLEDGEMENTS

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

AUTHOR

       Ben Bullock, <bkb@cpan.org>

COPYRIGHT & LICENCE

       This package and associated files are copyright (C) 2013-2022 Ben Bullock.

       You can use, copy, modify and redistribute this package and associated files under the
       Perl Artistic Licence or the GNU General Public Licence.