view release on metacpan or  search on metacpan

lib/ChordPro/lib/JSON/Relaxed.pm  view on Meta::CPAN

It does, however, have some additional extensions to make it really
relaxed.

=head1 LEGACY MODE

The old static method C<from_rjson> has been renamed to C<decode_rjson>,
to conform to many other modules of this kind.
For compatibility with pre-0.060 versions
C<from_rjson> is kept as a synonym for C<decode_rjson>.

For the same reason, the old parser method C<parse> has been renamed
to C<decode>.
For compatibility C<parse> is kept as a synonym for C<decode>.

When called by one of the old names, JSON::Relaxed will operate in
legacy mode. This changes the way errors are handled.

=head1 REALLY RELAXED EXTENSIONS

Extensions are disabled if option C<strict> is set.
Otherwise, most extensions are enabled by default.
Some extensions need an additional option setting.

=head2 Leading commas in lists

For example,

    [ , 1 ]

Enabled by default, overruled by C<strict>.

=head2 Hash keys without values

JSON::Relaxed supports object keys without a specified value.
In that case the hash element is simply assigned the undefined value.

In the following example, a is assigned 1, and b is assigned undef:

    { a:1, b }

Enabled by default, overruled by C<strict>.

=head2 String continuation

Long strings can be aesthetically split over multiple lines by putting
a backslash at the end of the line:

      "this is a " \
      "long string"

Note that this is different from

      "this is a \
    long string"

which B<embeds> the newline into the string, and requires continuation
lines to start at the beginning of the line to prevent unwanted spaces.

Enabled by default, overruled by C<strict>.

=head2 Extended Unicode escapes

Unicode escapes in strings may contain an arbitrary number of hexadecimal
digits enclosed in braces:

    \u{1d10e}

This eliminates the need to use
L<surrogates|https://unicode.org/faq/utf_bom.html#utf16-2>
to obtain the same character:

    \uD834\uDD0E

Enabled by default, overruled by C<strict>.

=head2 Combined hash keys

Hash keys that contain periods are considered subkeys, e.g.

    foo.bar: blech

is equivalent to

    foo: {
        bar: blech
    }

Requires C<combined_keys> or C<prp> option. Overruled by C<strict>.

=head2 Implied outer hash

If the JSON looks like a hash, i.e. a string (key) followed by a
C<:>, the outer C<{> and C<}> are implied.

For example:

    foo : bar

is equivalent to:

    { foo : bar }

Requires C<implied_outer_hash> or C<prp> option. Overruled by C<strict>.

=head2 Garbage after JSON structure

Requires C<extra_tokens_ok> option. Overruled by C<strict>.

Normally, parsing will fail unless the input contains exactly one
valid JSON structure, i.e. a string, a hash or an array.

With C<extra_tokens_ok> the first JSON structure is parsed and the
rest is ignored.

=head2 PRP extensions

Requires C<prp> option. Overruled by C<strict>.

Enables some specific extensions:

The equal sign C<=> can be used as an alternative to C<:> (colon).

Colon (and equal sign) is optional between a key and its hash value.

lib/ChordPro/lib/JSON/Relaxed.pm  view on Meta::CPAN

C<description>, and C<infoText>.

=cut

sub new {
    my ($class, %opts) = @_;
    return JSON::Relaxed::Parser->new(%opts);
}

use parent qw(Exporter);
BEGIN {
    our @EXPORT      = qw(decode_rjson);
    our @EXPORT_OK   = ( @EXPORT, qw(from_rjson) );
    our %EXPORT_TAGS = ( all => [ @EXPORT_OK ] );
}

=head1 MAPPING

=head2 RRJSON to Perl

=over 4

=item *

Numbers are unquoted strings. They will be mapped to numbers if the
repesentation is identical to the source.
For example, the unquoted string C<1> and the quoted string C<"1">
will both yield the number C<1>
The unquoted string C<1.0> will also yield the number C<1>,
but C<"1.0"> will yield the string C<"1.0">.

=item *

Unquoted C<null> will become C<undef>.

=item *

Unquoted C<true> and C<false> will yield JSON::Boolean objects that
test as boolean (true resp. false) and stringify as C<"true"> resp.
C<"false">. See L</"Boolean values"> how to change this behaviour.

Likewise unquoted C<on> and C<off> when option C<prp> is specified.

=item *

Other unquoted strings will be treated as quoted strings.

=back

=head2 Perl to RRJSON

=over 4

=item *

Numbers will be output as numbers.

=item *

Strings will be output as unquoted strings if possible, quoted strings
otherwise. Non-latin characters will be output as C<\u> escapes.
When some of the quotes C<" ' `> are embedded the others will be tried
for the string, e.g. C<"a\"b"> will yield C<'a"b'>.

All quotes are equal, there is no difference in interpretation.

=item *

Boolean objects will be output as unquoted C<true> and C<false>.

=item *

Undefined values will be output as C<null>.

=back

=head2 Boolean values

By default JSON::Boolean objects will be used for unquoted C<true> and
C<false>. The C<booleans> method can be used to change this.

    $parser->booleans = [ false-value, true-value ]

This sets the values to be used for C<true> and C<false>.
Default is

    $parser->booleans = [ $JSON::Boolean::false, $JSON::Boolean::true  ]

A non-array true value establishes the default.

Setting to a false value is the same as

    $parser->booleans = [ 0, 1 ]

With option C<prp>, unquoted C<on> is the same as C<true>, and C<off>
is the same as C<false>.

=head1 ERROR HANDLING

If the document cannot be parsed, JSON::Relaxed will throw an
exception.

In legacy mode, JSON::Relaxed returns an undefined
value and sets error indicators in $JSON::Relaxed::err_id and
$JSON::Relaxed::err_msg.

If parser property C<croak_on_error> is set to a false
value, it will behave as if in legacy mode.

For a full list of error codes, see L<JSON::Relaxed::ErrorCodes>.

=head1 AUTHOR

Johan Vromans F<jv@cpan.org>

Based on original code from Miko O'Sullivan F<miko@idocs.com>.

=head1 SUPPORT

Development of this module takes place on GitHub:
L<https://github.com/sciurius/perl-JSON-Relaxed>.