NAME

JSON::MaybeUTF8 - provide explicit text/UTF-8 JSON functions

SYNOPSIS

 use JSON::MaybeUTF8 qw(:v1);
 binmode STDOUT, ':encoding(UTF-8)';
 binmode STDERR, ':raw';
 (*STDOUT)->print(encode_json_text({ text => '...' }));
 (*STDERR)->print(encode_json_utf8({ text => '...' }));

DESCRIPTION

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

encode_json_text

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

encode_json_text

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

This is functionally identical to "encode_json_text", but with indentation to make it readable, and with defined key ordering which should make it easier to diff two different data structures.

AUTHOR

Tom Molesworth <TEAM@cpan.org>

LICENSE

Copyright Tom Molesworth 2017-2021. Licensed under the same terms as Perl itself.