JSON::Parse(3)

πŸ“¦
version 0.62 Β· 11 versions
, in opensuse-leap 16.0

πŸŽ€ NAME πŸŽ€

JSON::Parse β€” Parse JSON, bestie. That's the whole entire assignment. This is from the User Contributed Perl Documentation stack, section 3, and the manual name is folded right here like a little name tag. πŸ’–

✨ 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. Periodt.

πŸ¦‹ VERSION πŸ¦‹

This documents version 0.62 of JSON::Parse corresponding to git commit d04630086f6c92fea720cba4568faa0cbbdde5a6 β€” raw URL right here: 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".) Iconic, honestly.

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"). Like, actual fatal, bestie.

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 ✨

Okay so bestie, listen πŸ’– β€” if you need to parse JSON and the options that parse_json and parse_json_safe give you are just not it, you can make your own little JSON parsing object with new, sprinkle whatever options you want onto it, and then run it with parse or read. Main character energy, honestly πŸ‘‘

The options include copying JSON literals (true, false, null) with copy_literals, turning off the fatal errors with warn_only, catching duplicate keys in objects with detect_collisions, setting the maximum depth of nested objects and arrays with set_max_depth, producing machine-readable parsing errors with diagnostics_hash, and setting the JSON literals to whatever values you want with the methods under "Methods for manipulating literals".

Heads up bestie: these methods only affect the object you made with new. They do not globally change how parse_json or parse_json_safe behave. No cap. 🫢

check

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

This does the exact same thing as assert_valid_json, except its whole vibe can be modified with the diagnostics_hash method.

🎲 This method was added in version 0.48. It's lowkey here for the benefit of JSON::Repair.

copy_literals

$jp->copy_literals (1);

Give it a true value and it copies the JSON literal values (null, true, and false) into brand-new Perl scalar values, so no read-only values end up in your output. Slay ✨

Give it a false value and it uses read-only scalars instead:

$jp->copy_literals (0);

The copy_literals (1) behaviour is literally what parse_json_safe does. The copy_literals (0) behaviour is what parse_json does.

If you also set user-defined literals with set_true, set_false and set_null, those take precedence over this. Periodt.

🎲 This method was added in version 0.38.

detect_collisions

$jp->detect_collisions (1);

This switches on a check for hash key collisions β€” that's non-unique names in JSON objects, aka the chaos gremlin of data πŸ’€. If a collision shows up, an error message Name is not unique is printed, and it also hands you 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 $@;

which 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.

(Yeah, this example is included as collide.pl <https://fastapi.metacpan.org/source/BKB/JSON-Parse-0.62/examples/collide.pl> in the distribution. Iconic πŸŽ€)

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 one is a whole glow-up for your errors ✨ β€” it turns diagnostics produced by errors from a plain boring string into a hash reference packed with various fields. Warning though: this is incompatible with warn_only. Can't have both, bestie πŸ™ˆ

This replaces the previous experimental global variable $json_diagnostics, which got yeeted from the module. The hash keys and values are identical to the ones provided in the object returned by $json_diagnostics, with one extra key: error as string, which returns the usual error.

This requires Perl version 5.14 or later. Ngl, fair.

There's an example of using this method to "repair" broken JSON 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. That's a lot of layers, like an onion or my playlist πŸ§…πŸŽ§

🎲 This method was added in version 0.58.

new

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

Create a new JSON::Parse object. Fresh out the box, your own little parser πŸ’–

🎲 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.

It was renamed from run in version 0.60. Glow-up era ✨

read

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

Read a file, parse the JSON inside it, 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 πŸ¦‹

You can switch it off again with 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. So failed parsing returns the undefined value, undef, and prints a warning instead of Just Ending Things πŸ’€

You can switch it off again with any false value:

$jp->warn_only ('');

🎲 This method was added in version 0.41.

🌸 Methods for manipulating literals 🌸

These methods alter what gets written into the Perl structure when the parser sees a literal value β€” true, false or null β€” in the input JSON.

And yeah, this many methods is genuinely necessary, because a user might want the output for false to be undef:

$jp->set_false (undef);

So nope, we can't use one single function like $jp->false (undef) to cover both setting and deleting values. iykyk 😌

🎲 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";

and it prints

Yes, that is so true

To override the previous value, just 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 β€” like, Perl will evaluate it as false in an if statement β€” it prints a warning: User-defined value for JSON true evaluates as false. You can switch that 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 does absolutely nothing if no user-defined value is in place. It does not return a value. Chillest method ever, fr fr 🫢

🎲 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 example above, 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. Matching the ecosystem, we love to see it πŸ‘‘

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 β€” like, Perl will evaluate it as false in an if statement β€” it prints a warning: User-defined value for JSON false evaluates as true. You can switch that 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. Like, if you genuinely want to set the JSON false literal to turn into the string "false", go off bestie:

$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 back in the old versions of this module. And no, these names are not deprecated and will never be removed from the module. They're legacy icons, respect them πŸ’…

The names ending in _to_perl seem pretty silly in retrospect, since surely it's obvious that you're programming in Perl. But we stan them anyway πŸŽ€

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 get mapped to Perl like this, bestie:

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. It's giving "we tried our best" 😭

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 doesn't 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".

On top of that, JSON::Parse rejects UTF-8 which encodes non-characters such as U+FFFF and ill-formed characters such as incomplete halves of surrogate pairs. Not today, malformed bytes πŸš«πŸ’€

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

ok so surrogate pairs πŸ’œ β€” the ones that look like "\uD834\uDD1E" β€” those get handled too, no big deal. But if the second half of the surrogate pair is missing, you get an "Unexpected character" error or an "Unexpected end of input" error thrown at you 😭. And if the second half of the surrogate pair is there but contains an impossible value, you get a "Not surrogate pair" error. So like, the parser really does check πŸ‘‘

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. So check it:

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, so regardless of whether Perl thinks the input string is Unicode. Escapes like \u87f9 get converted into the equivalent UTF-8 bytes and the particular string they occur in gets 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 β€” and this is the fun bit β€” JSON::Parse also upgrades the remaining part of the string into a character string, even when it's not marked as a character string. Like so:

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.)

So yeah β€” in general that would be an unsafe practice πŸ™ˆ, but JSON::Parse can do it this way because JSON is a text-only, Unicode-only format. To make sure invalid inputs are never upgraded, JSON::Parse checks each input byte to make sure it forms UTF-8. See also UTF-8 only. Doing things this way, instead of the way Perl does it, was literally one of the original motivations for writing this module. iconic πŸ’…

🌈 JSON arrays

JSON arrays become Perl array references, periodt. And the elements of the Perl array are in the same order as they appear in the JSON. πŸ“

So this

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, and the value part of each member is mapped to the value of the Perl hash. main character energy ✨

So

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.)

So here the key "a" could be either 1 or 2 😭. As you can see in the example, parse_json overwrites the first value with the second value. parse_json_safe halts and prints a warning. And if you use new, you can switch key collision detection on and off with the detect_collisions method. πŸŽ€

The rationale for parse_json not giving 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. lowkey sad but fair πŸ₯²

🌸 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. (Heads up: 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.) πŸ‘‘

okay so most of the other CPAN modules out there lowkey use the same methods as JSON::Tiny, which means the example above? yeah, you can just adapt it and go πŸ’…. Also peep "Interoperability" in JSON::Create for a whole bunch of examples, iykyk.

πŸŽ€ Modifying the values πŸŽ€

So here's the tea: parse_json maps all the literals to read-only values. Which means if you try to modify the boolean values in the hash reference that parse_json hands back, Perl will hit you with Modification of a read-only value attempted errors, no cap:

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

And because the hash values are read-only scalars, $p->{hocus} = 99 is literally doing this:

undef = 99;

😭 so if you actually need to modify the returned hash reference, just delete the value first, bestie:

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

Same energy with array references β€” delete the value before you go altering it:

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

✨ but bestie, important lil plot twist: the return values from parsing bare literals are not read-only scalars, so this:

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

produces no error at all 🫢 β€” that's because Perl copies the scalar. slay.

🚫 RESTRICTIONS 🚫

So this module is kinda strict with what it'll accept as input. Here's the rundown πŸ‘‘

🌸 JSON only 🌸

JSON::Parse is a strict parser, periodt. It only accepts input that exactly meets the criteria of "RFC 8259". Which means, for example, JSON::Parse does not accept:

  • single quotes (') instead of double quotes (")
  • numbers with leading zeros, like 0123
  • control characters (0x00 - 0x1F) in strings
  • missing commas between array or hash elements like ["a" "b"]
  • trailing commas like ["a","b","c",]
  • trailing non-whitespace, like the second ] in ["a"]]

And if you need to process JSON-like text with tolerance for errors? You may find JSON::Repair by the same authors as JSON::Parse useful πŸ’–.

πŸ¦‹ No incremental parsing πŸ¦‹

JSON::Parse does not parse incrementally, fr fr. It only parses fully-formed JSON strings which include all the opening and closing brackets. This is, like, 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. So claims to offer incremental JSON parsing in other modules' documentation should be diligently verified πŸ‘€ (vibe check those docs, bestie).

🧚 UTF-8 only 🧚

JSON::Parse only parses the UTF-8 format. If your 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. And a BOM marker in the input? It consists of bytes 0xFE and 0xFF, both of which are invalid as UTF-8 β€” so yeah, that's gonna 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. iconic.

Also, 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 πŸ’…

okay so bestie, here's the tea on errors: valid_json is the chill one and does not produce error messages. parse_json and assert_valid_json straight-up die when they hit invalid input. parse_json_safe uses carp from Carp to pass error messages as warnings instead. πŸ’€

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. no cap.

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. periodt.

🎭 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 ✨

ok so here's the tea on speed πŸ’… on the author's computer, this module parses at, like, approximately the same speed as JSON::XS β€” with tiny little variations depending on what kind of input you throw at it. But for validation, valid_json is straight-up faster than literally any other module the author knows about, and up to ten times faster than JSON::XS. ate and left no crumbs πŸ”₯

Some special input types β€” like floating point numbers with an exponential part, e.g. 1e09 β€” seem to be about two or three times faster to parse with this module than with JSON::XS. Why? Because in JSON::Parse the exponential parsing is handled by the system's strtod function, whereas JSON::XS has its own built-in exponential parser. So these results may be system-dependent, bestie, no cap πŸ¦‹

Right now 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. And as of version 0.33, despite some progress improving JSON::Parse, the author hasn't been able to fully work out the reason behind that better speed 😭

There's benchmarking code in the github repository under the directory benchmarks for anyone who wants 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. And 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 live 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 πŸ‘€

🌈 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 πŸ˜•.

ngl this next bit is the vibes-based tier list and it's giving comprehensive πŸ’…

πŸ’œ Modules by the same author

  • JSON::Create β€” πŸ‘ JSON::Create is a companion module to JSON::Parse by the same author. bestie duo fr fr 🫢
  • 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. lowkey the safe backup plan 🧚
  • 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. the classic πŸ‘‘
  • 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]

It's part of the Mojolicious standalone web framework β€” a "pure Perl" JSON reader/writer πŸ’…. Fun lore: as of version 8.70 of Mojolicious, it actually depends on JSON::PP, but it'll load Cpanel::JSON::XS if that's available. Bestie stays flexible 😌.

🧚 Combination modules πŸŽ€

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

  • JSON::Any β€” Author: ETHER Β· Date: 2015-06-10 Β· Version: 1.39 πŸ‘Ž This one is now deprecated, bestie. It combines JSON::DWIW, JSON::XS versions one and two, and JSON::Syck. A whole group project that didn't survive the semester.
  • JSON::MaybeXS β€” ⭐⭐ Author: ETHER Β· Date: 2020-11-13 Β· Version: 1.004003 A module that combines Cpanel::JSON::XS, JSON::XS, and JSON::PP. The original JSON combines JSON::XS and JSON::PP, but this one prioritizes Cpanel::JSON::XS over JSON::XS. It's giving main character energy among the combination modules, ngl.
  • JSON::XS::VersionOneAndTwo β€” Author: LBROCARD Β· Date: 2008-02-13 Β· Version: 0.31 πŸ‘Ž A "combination module" that supports two different interfaces of JSON::XS. Except plot twist: JSON::XS is now onto version 4. So yeah. That's a whole era that's passed 🫠.
  • Mojo::JSON::MaybeXS β€” ⭐ 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 that make Mojolicious depend on Cpanel::JSON::XS if available. It got ate by progress, honestly.
  • Test2::Tools::JSON β€” Author: AKIYM Β· Date: 2019-08-07 Β· Version: 0.05
  • Test::Deep::JSON β€” ⭐ Author: MOTEMEN Β· Date: 2018-04-24 Β· Version: 0.05 Compare JSON with Test::Deep. As of version 0.05, it relies on JSON::MaybeXS. Cute.
  • Test::JSON β€” ⭐ 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 😭. RIP.
  • Test::JSON::Entails β€” Author: VOJ Β· Date: 2012-09-14 Β· Version: 0.2 πŸ‘Ž Tests 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, and instead be testing Perl hashes and arrays πŸ’€. Name vibe check: failed.
  • Test::JSON::More β€” 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. Obsessed with the flexibility 🫢.

These untangle numbers, strings, and booleans into JSON types. The whole "wait is that a string or a number" saga β€” solved.

  • JSON::TypeInference β€” Author: AEREAL Β· Date: 2015-10-26 Β· Version: v1.0.2 πŸ˜• Virtually undocumented, it's not clear what this does. Honestly? Same, bestie. Mystery icon.
  • JSON::Types β€” ⭐ 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. So slay.
  • JSON::Types::Flexible β€” Author: PINE Β· Date: 2017-04-01 Β· Version: 0.03 The module is barely documented, but from looking at the test file (in the JSON-Types-Flexible-0.03 distribution, at the path t/json/types/flexible/class.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 Β· 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). Detective mode: activated πŸ”₯.

πŸ‘‘ Special-purpose modules ⭐

  • App::JSON::to β€” ⭐ 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 Β· 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. Iconic behavior, genuinely.

  • Config::JSON β€” Author: RIZEN Β· Date: 2014-12-25 Β· Version: 1.5202 Configuration files in JSON, with hash comments also allowed.
  • Devel::JSON β€” ⭐ 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 Β· Date: 2012-07-27 Β· Version: v1.0.4 "Embed JSON data structures directly into your Perl code". Relies on JSON.
  • JSON::Builder β€” Author: KNI Β· Date: 2015-04-16 Β· Version: 0.04 Create JSON under memory limitations. Frugal king πŸ’œ.
  • JSON::Color β€” ⭐ Author: PERLANCAR Β· Date: 2021-05-07 Β· Version: 0.131 🌈 This module generates JSON colorized with ANSI escape sequences. Aesthetic AND functional, we love to see it πŸ’–.
  • JSON_File β€” ⭐ Author: GETTY Β· Date: 2014-09-11 Β· Version: 0.004
  • JSON::MultiValueOrdered β€” 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.) Go read that if you're nosy like me πŸ™ˆ.

  • JSON::String β€” Author: BRUMMETT Β· Date: 2015-02-04 Β· Version: v0.2.0 Automatically change a JSON string when a data structure changes, using tied scalars. Witchcraft, but make it Perl.

🧚 Patch, path, pointer, schema, and transform modules πŸŽ€

  • JSON::Assert β€” Author: SGREEN Β· Date: 2017-07-07 Β· Version: 0.08 "Asserts JSONPaths into a JSON data structure for correct values/matches"
  • JSON::Conditional β€” Author: LNATION Β· Date: 2021-03-29 Β· Version: 1.00
  • JSON::GRDDL β€” Author: TOBYINK Β· Date: 2014-09-11 Β· Version: 0.002
  • JSON::Hyper β€” ⭐ Author: TOBYINK Β· Date: 2012-10-12 Β· Version: 0.011
  • JSON::JQ β€” Author: DONGXU Β· Date: 2021-05-16 Β· Version: 0.06 Perl access to the jq tool via Alien::LibJQ.
  • JSON::MergePatch β€” ⭐ Author: SOJIRO Β· Date: 2016-02-24 Β· Version: 0.04
  • JSON::Patch β€” 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. Ma'am, that's not JSON, that's just Perl πŸ’€.
  • JSON::Path β€” ⭐ Author: POPEFELIX Β· Date: 2021-01-28 Β· Version: 0.431 Search nested hashref/arrayref structures using JSONPath.
  • JSON::Pointer β€” ⭐ Author: ZIGOROU Β· Date: 2015-08-13 Β· Version: 0.07 Extract parts of a JSON string. Surgical πŸ’….
  • JSON::Schema::ToJSON β€” ⭐ Author: LEEJO Β· Date: 2021-04-06 Β· Version: 0.19 "Generate example JSON structures from JSON Schema definitions"
  • JSON::T β€” ⭐ Author: TOBYINK Β· Date: 2014-09-28 Β· Version: 0.104 Transform JSON using JsonT.
  • JSON::Transform β€” ⭐ Author: ETJ Β· Date: 2020-01-01 Β· Version: 0.03
  • JSON::Validator β€” ⭐⭐ 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. Gatekeeping, but useful 🌟.
  • Template::Plugin::JSON β€” 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 but with ✨extra lore✨.

  • JSON::Diffable β€” ⭐ Author: PHAYLON Β· Date: 2014-12-10 Β· Version: 0.000002 "A relaxed and easy diffable JSON variant"
  • JSON::Relaxed β€” Author: MIKO Β· Date: 2016-04-30 Β· Version: 0.05
"An extension of JSON that allows for better human-readability".

okay so that's the tail of that tagline, and we are moving on into the next batch of modules, bestie, keep up πŸ’…

πŸŽ€ JSON::WithComments

[Author: RJRAY; Date: "2017-09-02"; Version: 0.003]

🌐 Web interactions via JSON 🌐

eeeee this is the category for all the girlies who talk to servers πŸ’»βœ¨

πŸ” Crypt::JWT

[⭐⭐ Author: MIK; Date: "2021-05-01"; Version: 0.033]

This module covers JSON Web Tokens, JSON Web Signature, and JSON Web Encryption. Three J-things at once, main character energy fr fr πŸ‘‘

πŸ›°οΈ JSON::API

[⭐ Author: GFRANKS; Date: "2019-07-01"; Version: "v1.1.1"]

Combines LWP::UserAgent and JSON into one unified module so you can chat with a web server via JSON. it's giving "one module to rule the HTTP requests" 🫢

🧸 LWP::JSON::Tiny

[⭐ Author: SKINGTON; Date: "2018-05-11"; Version: 0.014]

🌍 WWW::JSON

[⭐ 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. little add-ons, little sprinkles, we love to see it 🌸

🍬 JSON::XS::Sugar

[Author: MAXMIND; Date: "2015-04-01"; Version: 1.01]

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

πŸŽ€ Silki::JSON

[⭐ 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. science-fair vibes, honestly adorable 🧚

πŸ”¬ JSON::Decode::Marpa

[Author: PERLANCAR; Date: "2014-08-27"; Version: 0.02]

πŸ¦‹ JSON::Decode::Regexp

[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; Date: "2019-06-18"; Version: 1.08]

πŸ› Pegex::JSON

[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. oops, a little accident, it happens 😭

🧰 App::JSON::Tools

[Author: KABLAMO; Date: "2016-08-05"; Version: 0.01]

Undocumented command-line tools for JSON.

πŸ™ˆ App::JSONPretty

[⭐ 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; Date: "2013-12-18"; Version: 0.01]

πŸ“ Jasonify

[Author: BOBK; Date: "2020-03-04"; Version: "v0.20.064"]

πŸ’€ JS::JSON

[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; 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; Date: "2019-07-13"; Version: 0.202]

πŸ“¨ JSON::JSend

[Author: HOEKIT; Date: "2016-04-23"; Version: 0.02]

πŸ“ JSON::Lines

[⭐ 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; 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; Date: "2013-06-26"; Version: "v0.0.3"]

JavaScript object notation object notator. say that five times fast, I dare you πŸ’€

🌊 JSON::SL

[⭐ Author: MNUNBERG; Date: "2017-11-10"; Version: "v1.0.7"]

πŸ“– JSON::Streaming::Reader

[⭐ Author: MART; Date: "2012-11-24"; Version: 0.06]

✍️ JSON::Streaming::Writer

[Author: MART; Date: "2012-11-24"; Version: 0.03]

🧰 JSON::Util

[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; 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; Date: "2021-01-24"; Version: 1.1]

🐜 Text::JSON::Nibble

[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, bestie:

validjson *.json

The default behaviour is to just do nothing if the input is valid. iconic, honestly, no notes. 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.

look at all those valid files, they're all slaying simultaneously πŸŽ‰πŸ’–

πŸ“¦ DEPENDENCIES πŸ“¦

  • Carp

🎁 EXPORTS 🎁

The module exports nothing by default. (we respect boundaries here 🫢)

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';

okay so grab :all if you want the whole squad in your namespace at once, no cap ✨

πŸ§ͺ TESTING

Internal testing code

Okay so like, this module is obsessed with testing itself, and honestly? Iconic behavior. πŸ’… The module incorporates extensive testing related to the production of error messages and validation of input. Some of that testing code ships with the module in the /t/ subdirectory of the distribution.

The more extensive testing code lives in the git repository β€” and ngl, it is not supplied in the CPAN distribution. There's a script, randomjson.pl (https://github.com/benkasminbullock/JSON-Parse/d04630086f6c92fea720cba4568faa0cbbdde5a6/randomjson.pl), that generates a set number of bytes of random JSON and checks that the module's bytewise validation of input is correct. The way it does this is genuinely so clever: it takes a valid fragment, then adds each possible byte from 0 to 255 to see whether the module correctly identifies it as valid or invalid at that point, then randomly picks one of the valid bytes and adds it to the fragment and continues the process until a complete valid JSON input is formed. And the module has undergone about a billion repetitions of this test. A BILLION. πŸ”₯

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. Slay. ✨

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. Honestly? We won 😌

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

Shoutout time, because we love our besties:

  • 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> πŸ¦‹

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. 🌈

okay that's literally the whole page bestie, you made it to the end πŸŽ€ β€” this was the JSON::Parse(3) page as shipped with perl v5.42.0, dated 2022-07-16. Go forth and parse some JSON, you absolute icon πŸ’…βœ¨

πŸ“¦ where this page comes from