

=encoding UTF-8

=head1 NAME

JSON::Repair - reformat JSON to strict compliance

=head1 SYNOPSIS

    use JSON::Repair 'repair_json';

=head1 VERSION

This documents version 0.04 of JSON::Repair corresponding to
git commit L<af08d7e9f635147193cf77860043cb2f7ec96f24|https://github.com/benkasminbullock/json-repair/commit/af08d7e9f635147193cf77860043cb2f7ec96f24> released on Sat Nov 26 15:47:42 2016 +0900.

=head1 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.

=head1 FUNCTIONS

=head2 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 C<$json> cannot be
repaired, and returns the undefined value.

=head3 Repairs applied

=over

=item 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 L<F<trailing-commas.pl>|https://api.metacpan.org/source/BKB/JSON-Repair-0.04/examples/trailing-commas.pl> in the distribution.)


=item 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 L<F<single-quotes.pl>|https://api.metacpan.org/source/BKB/JSON-Repair-0.04/examples/single-quotes.pl> in the distribution.)


=item 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 L<F<missing-ends.pl>|https://api.metacpan.org/source/BKB/JSON-Repair-0.04/examples/missing-ends.pl> in the distribution.)


=item 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 L<F<unquoted-keys.pl>|https://api.metacpan.org/source/BKB/JSON-Repair-0.04/examples/unquoted-keys.pl> in the distribution.)


=item Add missing commas to objects and arrays

    
    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 L<F<missing-commas.pl>|https://api.metacpan.org/source/BKB/JSON-Repair-0.04/examples/missing-commas.pl> in the distribution.)


=item Remove comments

This example uses the example from the synopsis of L<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 L<F<comments.pl>|https://api.metacpan.org/source/BKB/JSON-Repair-0.04/examples/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 L<F<hash-comments.pl>|https://api.metacpan.org/source/BKB/JSON-Repair-0.04/examples/hash-comments.pl> in the distribution.)


The facility to remove hash comments was added in version 0.02 of the
module.

=item Sort out broken numbers

JSON disallows various kinds of numbers such as decimals without a
leading zero like .123, or decimals with an exponent but without a
fraction, like 1.e9. JSON::Repair adds the necessary digits to make
them parseable. It also strips leading zeros, as in 0123.

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


produces output

    [0.123,123,1.0e9]

(This example is included as L<F<numbers.pl>|https://api.metacpan.org/source/BKB/JSON-Repair-0.04/examples/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.

=item 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 L<F<strings.pl>|https://api.metacpan.org/source/BKB/JSON-Repair-0.04/examples/strings.pl> in the distribution.)


This was added in version 0.04 of the module.

=item Empty inputs are converted into the empty string

Completely empty inputs are converted into C<"">.

=back

=head3 Options

Valid options are

=over

=item verbose

Print messages about the operations applied

=back

=head1 EXPORTS

L</repair_json> is exported on demand. The tag ":all" exports all functions.

    use JSON::Repair ':all';

=head1 DEPENDENCIES

=over

=item JSON::Parse

This module relies on L<JSON::Parse/diagnostics_hash> 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.

=item C::Tokenize

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

=item Perl 5.14

Unfortunately L<JSON::Parse/diagnostics_hash> is only available for
Perl 5.14 or later.

=back

=head1 SCRIPT

A script F<repairjson> is installed with the module which runs
L</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.

=head1 SEE ALSO

See the section L<JSON::Parse/SEE ALSO> for a comprehensive list of
JSON modules on CPAN and more information about JSON itself.

=cut

=head1 AUTHOR

Ben Bullock, <bkb@cpan.org>

=head2 Request

If you'd like to see this module continued, let me know that you're
using it. For example, send an email, write a bug report, star the
project's github repository, add a patch, add a C<++> on Metacpan.org,
or write a rating at CPAN ratings. It really does make a
difference. Thanks.

=head1 COPYRIGHT & LICENCE

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



