JSON::MaybeUTF8(3)

💖 JSON::MaybeUTF8 — NAME ✨

okay bestie, so this is the JSON::MaybeUTF8 manual page (it's JSON::MaybeUTF8(3), living in the User Contributed Perl Documentation section, iykyk) — and it's literally just here to give you explicit text/UTF-8 JSON functions. That's the whole vibe. Explicit. No guessing. Periodt. 💅

---

🌸 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 => '...' }));

like, look at that. STDOUT gets :encoding(UTF-8), STDERR gets :raw, and then each one gets the right encoder for its vibe. that's the entire point, bestie 🫶

---

🦋 DESCRIPTION 🦋

So this module combines JSON::MaybeXS with Unicode::UTF8 to hand you 4 functions that cover all the combinations of JSON and UTF-8 encoding/decoding. all four combos. every single one. no gaps 🔥

The idea (and honestly it's giving main character energy) is to make the UTF-8-or-not behaviour more explicit in code that deals with multiple transport layers — think database, cache and I/O. When you've got layers stacked on layers, you want zero ambiguity about which encoding is which. ngl that's the whole mood.

And yes, it's a trivial wrapper around two other modules. it's not doing anything wild, it's just being clear about it. iconic.

💀 BOM removal 💀

The $JSON::Maybe::UTF8::REMOVE_BOM flag is set by default, and the reason is <https://github.com/rurban/Cpanel-JSON-XS/issues/125>. like, that's just how it is.

If you'd rather disable it, just drop this in your code:

$JSON::Maybe::UTF8::REMOVE_BOM = 0;

⚠️ heads up bestie: this only affects things when Cpanel::JSON::XS is used — and that's the one JSON::MaybeXS prefers if it can be loaded. so if it's not loaded, this flag is lowkey not doing anything for you 🙈

🎀 decode_json_utf8 🎀

You give it a UTF-8-encoded JSON byte string, it gives you back a Perl data structure. it may optionally remove the UTF-8 BOM — <https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8> — if it exists. if there's no BOM, no drama 🌈

⭐ encode_json_utf8 ⭐

You give it a Perl data structure, it gives you back a UTF-8-encoded JSON byte string. slay.

🧚 decode_json_text 🧚

You give it a JSON string composed of Unicode characters (that's in Perl's internal encoding, for the record), it gives you back a Perl data structure. ✨

👑 encode_json_text 👑

You give it a Perl data structure, it gives you back a JSON string composed of Unicode characters (again — Perl's internal encoding). 💜

👑 encode_json_text 👑 (yes, it's listed twice 💀)

okay so the source lists encode_json_text a second time here, and this one is doing something a little different, so listen up:

You give it a Perl data structure, and you get back a formatted JSON string composed of Unicode characters (Perl's internal encoding, same as before).

It's 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. honestly? diffable JSON is a love language. obsessed.

---

🍓 AUTHOR 🍓

Tom Molesworth <TEAM@cpan.org>

---

🌈 LICENSE 🌈

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

---

and that's the whole page, bestie 🎀 — brought to you by perl v5.42.2, dated 2026-02-15. go forth and encode explicitly 💖✨