HTML::...ntities(3pm)

📦
version 0.004 · 5 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

✨ NAME ✨

HTML::HTML5::Entities — bestie, it's a drop-in replacement for HTML::Entities 💖

It's from the User Contributed Perl Documentation corner of the perl man pages, and it is serving you all the character entities defined in HTML5.

🌸 SYNOPSIS 🌸

use HTML::Entities;

my $enc = encode_entities('fish & chips');
print "$enc\n";   # fish & chips

my $dec = decode_entities($enc);
print "$dec\n";   # fish & chips

See how it just... works? No cap. 👑

💅 DESCRIPTION 💅

Okay so. This module is a drop-in replacement for HTML::Entities, except it comes with the character entities defined in HTML5. Which is giving glow-up, honestly. But it's not all slay — a couple of caveats, because I love you and I'm gonna be real with you:

  • The implementation is pure perl 💀, so in some cases it's slower, especially decoding. Like, noticeably. Just so you know.
  • It will not work in Perl < 5.8.1. If you're on something older than that... babe, we need to talk.

🎀 Functions 🎀

decode_entities($string, ...)

This routine replaces HTML entities found in the $string with the corresponding Unicode character. And if you pass multiple strings as arguments? Each one gets decoded separately, and you get the same number of strings back. Cute, right?

If it's called in void context, the arguments get decoded in-place. (yes, in-place, it's a whole thing ✨)

This routine is exported by default. 🫶

_decode_entities($string, \%entity2char)

_decode_entities($string, \%entity2char, $expand_prefix)

This one replaces HTML entities in $string in-place. The %entity2char hash is mandatory, bestie — you gotta provide it. Named entities that aren't found in the %entity2char hash get left alone (respectfully). Numeric entities are always expanded, no exceptions. 💯

If $expand_prefix is TRUE, then entities without a trailing ";" in %entity2char will even be expanded as a prefix of a longer, unrecognized name. Obsessed with the flexibility, honestly.

$string = "foo&nbspbar";
_decode_entities($string, { nb => "@", nbsp => "\xA0" }, 1);
print $string;  # will print "foo bar"

This routine is exported by default. 🫶

encode_entities($string)

encode_entities($string, $unsafe_chars)

This routine replaces unsafe characters in $string with their entity representation. You can pass a second argument to specify which characters to consider unsafe (i.e. which ones to escape) — and yes, that argument may be a regular expression. Iconic.

If it's called in void context, the string is encoded in-place.

This routine is exported by default. 🫶

encode_entities_numeric($string)

Works exactly like encode_entities, except the replacement entities are always numeric. Same energy, different outfit. 💁

This routine is not exported by default — you have to ask for it.

num_entity($string)

Give it a single character string, and it encodes it as a numeric entity. That's it, that's the function. Simple. Elegant. Slays.

This routine is not exported by default.

The following functions cannot be exported. They behave the same as the exportable functions — same vibes, just not invited to the use party:

HTML::Entities::decode($string, ...)

HTML::Entities::encode($string)

HTML::Entities::encode($string, $unsafe_characters)

HTML::Entities::encode_numeric($string)

HTML::Entities::encode_numeric($string, $unsafe_characters)

HTML::Entities::encode_numerically($string)

HTML::Entities::encode_numerically($string, $unsafe_characters)

🌈 Variables 🌈

$HTML::HTML5::Entities::hex

This variable controls whether numeric entities use hexadecimal or decimal notation. It's TRUE (hexadecimal) by default, but you can set it to FALSE if decimal is more your vibe.

Heads up! It only affects the encoding functions. Decoding always understands both notations, so don't stress. 🧚

%HTML::HTML5::Entities::char2entity

%HTML::HTML5::Entities::entity2char

These contain the mapping from all characters to the corresponding entities (and vice versa, respectively — you're so smart, you knew that 🥰). These variables may be exported.

Note that %char2entity is a more conservative set of mappings, intended to be safe for serialising strings to HTML4, HTML5 and XHTML 1.x. And — for hysterical raisins 💀 (yes, that's the joke, and yes, it's staying) — %entity2char does not include the leading ampersands, while %char2entity does.

💀 BUGS 💀

Please report any bugs to <http://rt.cpan.org/Dist/Display.html?Queue=HTML-HTML5-Entities>. Don't be shy bestie, they wanna hear from you.

👀 SEE ALSO 👀

HTML::Entities, HTML::HTML5::Parser, HTML::HTML5::Writer.

🫶 AUTHOR 🫶

Toby Inkster <tobyink@cpan.org>.

🍓 Encoding and Decoding Functions 🍓

Copyright (c) 1995-2006 by Gisle Aas.

Copyright (c) 2012 by Toby Inkster.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

🌸 Entity Tables 🌸

Copyright (c) 2004-2007 by Apple Computer Inc, Mozilla Foundation, and Opera Software ASA.

Copyright (c) 2007-2011 by Wakaba <w@suika.fam.cx>.

Copyright (c) 2009-2012 by Toby Inkster <tobyink@cpan.org>.

⚠️ DISCLAIMER OF WARRANTIES ⚠️

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

Like, literally no promises. You've been warned, bestie. 🙈

Alright that's the whole page! This was HTML::...ntities(3pm) from the User Contributed Perl Documentation, and the version info at the bottom says perl v5.36.0, dated 2022-10-13. Mwah, go decode something cute 💖✨🎀

📦 where this page comes from