JSON-MaybeUTF8

 view release on metacpan or  search on metacpan

Changes  view on Meta::CPAN

Revision history for JSON-MaybeUTF8

2.000     2021-04-27 17:00:42+08:00 Asia/Kuala_Lumpur
    [API Changes]
    - supports a `format_json_text` function for indented JSON

1.002     2019-03-22 13:47:33+08:00 Asia/Kuala_Lumpur
    Strip BOM characters by default in `decode_json_text` and `decode_json_utf8`.
    This is a workaround for https://github.com/rurban/Cpanel-JSON-XS/issues/125
    and addresses the issue mentioned in 1.001 release notes.

1.001     2019-03-13 13:14:37+08:00 Asia/Kuala_Lumpur
    Retains a separate JSON instance for each function.

    This is due to some reports of valid Unicode string data not decoding
    correctly via `decode_json_text` after a script has been running for some
    time: indications point to possible state corruption in the shared JSON
    object, so this is an attempt to mitigate that.

README  view on Meta::CPAN

    Combines JSON::MaybeXS with Unicode::UTF8 to provide 4 functions that
    handle the combinations of JSON and UTF-8 encoding/decoding.

    The idea is to make the UTF-8-or-not behaviour more explicit in code
    that deals with multiple transport layers such as database, cache and
    I/O.

    This is a trivial wrapper around two other modules.

 BOM removal

    The $JSON::Maybe::UTF8::REMOVE_BOM flag is set by default due to
    https://github.com/rurban/Cpanel-JSON-XS/issues/125. If you would
    prefer to disable this, add $JSON::Maybe::UTF8::REMOVE_BOM = 0; in your
    code.

    Note that this only affects things when Cpanel::JSON::XS is used
    (preferred by JSON::MaybeXS if it can be loaded).

 decode_json_utf8

    Given a UTF-8-encoded JSON byte string, returns a Perl data structure.
    May optionally remove the UTF-8 BOM
    <https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8> if it exists.

 encode_json_utf8

    Given a Perl data structure, returns a UTF-8-encoded JSON byte string.

 decode_json_text

    Given a JSON string composed of Unicode characters (in Perl's internal
    encoding), returns a Perl data structure.

lib/JSON/MaybeUTF8.pm  view on Meta::CPAN

=cut

use feature qw(state);

use JSON::MaybeXS;
use Unicode::UTF8 qw(encode_utf8 decode_utf8);

use Exporter qw(import export_to_level);

=head2 BOM removal

The C<< $JSON::Maybe::UTF8::REMOVE_BOM >> flag is B<set by default> due
to L<https://github.com/rurban/Cpanel-JSON-XS/issues/125>. If you would
prefer to disable this, add C<< $JSON::Maybe::UTF8::REMOVE_BOM = 0; >>
in your code.

Note that this only affects things when L<Cpanel::JSON::XS> is used (preferred by L<JSON::MaybeXS>
if it can be loaded).

=cut

our $REMOVE_BOM = 1;

our @EXPORT_OK = qw(
    decode_json_utf8
    encode_json_utf8
    decode_json_text
    encode_json_text
    format_json_text
);
our %EXPORT_TAGS = (
    v1 => [ qw(

lib/JSON/MaybeUTF8.pm  view on Meta::CPAN

        encode_json_utf8
        decode_json_text
        encode_json_text
    ) ],
    v2 => [ @EXPORT_OK ],
);

=head2 decode_json_utf8

Given a UTF-8-encoded JSON byte string, returns a Perl data
structure. May optionally remove the UTF-8 L<BOM|https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8>
if it exists.

=cut

sub decode_json_utf8 {
    state $json = JSON::MaybeXS->new;
    die 'bad json state' if $json->get_utf8;
    return $json->decode_utf8($_[0]) unless $REMOVE_BOM;
    (my $txt = decode_utf8(shift)) =~ s{^\x{feff}}{};
    return $json->decode($txt);
}

=head2 encode_json_utf8

Given a Perl data structure, returns a UTF-8-encoded JSON
byte string.

=cut

lib/JSON/MaybeUTF8.pm  view on Meta::CPAN

Given a JSON string composed of Unicode characters (in
Perl's internal encoding), returns a Perl data structure.

=cut

sub decode_json_text {
    state $json = JSON::MaybeXS->new;
    die 'bad json state' if $json->get_utf8;
    my $txt = shift;
    $txt =~ s{^\x{feff}}{} if $REMOVE_BOM;
    $json->decode($txt);
}

=head2 encode_json_text

Given a Perl data structure, returns a JSON string composed
of Unicode characters (in Perl's internal encoding).

=cut