/ 
JSON-Repair-0.05
River stage zero No dependents
/ JSON::Repair

NAME

JSON::Repair - reformat JSON to strict compliance

SYNOPSIS

use JSON::Repair 'repair_json';

VERSION

This documents version 0.05 of JSON::Repair corresponding to git commit bdce379d249b33dc4af7c84089d7e9a2de110caf released on Wed Mar 8 09:28:46 2017 +0900.

DESCRIPTION

The module has some heuristics with which it tries to guess what kind of "relaxed" JSON might have been used and then convert those into strictly compliant JSON.

FUNCTIONS

repair_json

my $repaired = repair_json ($json, %options);

This alters its input in various ways to make it compliant with the JSON specification, or prints an error message if $json cannot be repaired, and returns the undefined value.

Repairs applied

Strip trailing commas
use JSON::Repair ':all';
print repair_json (q/{"answer":["bob dylan",42,],}/), "\n";

produces output

{"answer":["bob dylan",42]}

(This example is included as trailing-commas.pl in the distribution.)

Change single quotes to double quotes in keys
use JSON::Repair ':all';
print repair_json ("{'answer':42}"), "\n";

produces output

{"answer":42}

(This example is included as single-quotes.pl in the distribution.)

Add missing object-end, string-end and array-end markers
use JSON::Repair ':all';
my $r = repair_json ('{"stuff":["good');
print "$r\n";

produces output

{"stuff":["good"]}

(This example is included as missing-ends.pl in the distribution.)

Add quotes to unquoted keys
use JSON::Repair ':all';
print repair_json ("{how many roads must a man walk down:42}",
                   verbose => undef), "\n";

produces output

{"how many roads must a man walk down":42}

(This example is included as unquoted-keys.pl in the distribution.)

Add missing commas to objects and arrays

The module can add missing commas between the end of object or array values.

use JSON::Repair ':all';
print repair_json (q![1 2 3 4 {"six":7 "eight":9}]!), "\n";

produces output

[1, 2, 3, 4, {"six":7, "eight":9}]

(This example is included as missing-commas.pl in the distribution.)

Remove comments

The module removes C and C++ comments and hash comments (Perl-style comments) from JSON.

This example uses the example from the synopsis of JSON::Relaxed:

use JSON::Repair ':all';
my $rjson = <<'(RAW)';
/* Javascript-like comments are allowed */
{
  // single or double quotes allowed
  a : 'Larry',
  b : "Curly",
   
  // nested structures allowed like in JSON
  c: [
     {a:1, b:2},
  ],
   
  // like Perl, trailing commas are allowed
  d: "more stuff",
}
(RAW)
print repair_json ($rjson, verbose => undef);

produces output

{
    "a ": "Larry",
  "b ": "Curly",
   
    "c": [
     {"a":1, "b":2}
  ],
   
    "d": "more stuff"
}

(This example is included as comments.pl in the distribution.)

This example demonstrates removing hash comments:

use JSON::Repair 'repair_json';
print repair_json (<<'EOF');
{
  # specify rate in requests/second
  rate: 1000
}
EOF

produces output

{
    "rate": 1000
}

(This example is included as hash-comments.pl in the distribution.)

The facility to remove hash comments was added in version 0.02 of the module. It currently uses "C::Tokenize" for the C/C++ comment regexes.

Sort out broken numbers

JSON does not allow various kinds of numbers, such as decimals without a leading zero, like .123, decimals with an exponent but without a fraction, like 1.e9, or integers with a leading zero. JSON::Repair adds or removes digits to make them parseable.

use JSON::Repair ':all';
print repair_json ('[.123,0123,1.e9]');

produces output

[0.123,123,1.0e9]

(This example is included as numbers.pl in the distribution.)

JSON::Repair strips leading zeros like 0123 without converting the result to octal (base 8). It doesn't attempt to repair hexadecimal (base 16) numbers.

The facility to reinterpret numbers was added in version 0.02 of the module.

Convert unprintable and whitespace characters to escapes in strings

Strings containing unprintable ASCII characters and some kinds of whitespace are not allowed in JSON. This converts them into valid escapes.

use JSON::Repair 'repair_json';
my $badstring = '"' . chr (9) . chr (0) . "\n" . '"';
print repair_json ($badstring), "\n";

produces output

"\t\u0000\n"

(This example is included as strings.pl in the distribution.)

This was added in version 0.04 of the module.

Empty inputs are converted into the empty string

Completely empty inputs are converted into "".

Options

Valid options are

verbose
my $okjson = repair_json ($json, verbose => 1);

Give a true value to make the module print messages about the operations applied. This facility is largely for debugging the module itself. The messages may be poorly formatted and opaque, and are not guaranteed to be the same in future versions of the module.

EXPORTS

"repair_json" is exported on demand. The tag ":all" exports all functions.

use JSON::Repair ':all';

DEPENDENCIES

JSON::Parse

This module relies on "diagnostics_hash" in JSON::Parse to find the errors in the input. Most of the work of the module is done by JSON::Parse's diagnostics, and then this applies a few heuristic rules to guess what might have caused the error.

C::Tokenize

This module uses the regular expression for C comments from C::Tokenize.

Carp

Carp is used to report errors.

Perl 5.14

Unfortunately "diagnostics_hash" in JSON::Parse is only available for Perl 5.14 or later, because it relies on "croak_sv" in perlapi, which was introduced in Perl 5.14. I'm not sure if there is a way to get the same behaviour with earlier versions of Perl.

SCRIPT

A script repairjson is installed with the module which runs "repair_json" on the files given as arguments:

repairjson file1.json file2.json

The output is the repaired JSON.

The script was added in version 0.02 of the module.

SEE ALSO

See the section "SEE ALSO" in JSON::Parse for a comprehensive list of JSON modules on CPAN and more information about JSON itself.

AUTHOR

Ben Bullock, <bkb@cpan.org>

COPYRIGHT & LICENCE

This package and associated files are copyright (C) 2016-2017 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.