view release on metacpan or  search on metacpan

lib/JSON/Parse.pod  view on Meta::CPAN

    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.

=head1 RESTRICTIONS

This module imposes the following restrictions on its input.

=over

=item JSON only

JSON::Parse is a strict parser. It only accepts input which exactly
meets the criteria of L</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 C<["a" "b"]>, or trailing commas
like C<["a","b","c",]>. It also does not accept trailing
non-whitespace, like the second "]" in C<["a"]]>. 

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

=item 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 L<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.

=item 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 C<:encoding> (see L<PerlIO::encoding> and
L<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 C<0xFE>
and C<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 L</Unexpected character> error.

The latest specification for JSON, L</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.

=back

=head1 DIAGNOSTICS

L</valid_json> does not produce error messages. L</parse_json> and
L</assert_valid_json> die on encountering invalid
input. L</parse_json_safe> uses L<Carp/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 L</parse_json> and L</assert_valid_json>, parsing errors are fatal,
so to continue after an error occurs, put the parsing into an C<eval>
block:

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

The following error messages are produced:

=over



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