Pod::Escapes(3perl)

📦
version 5.44.0 · 14 versions
, in arch rolling

💖 Pod::Escapes 💖

okay so bestie, welcome to Pod::Escapes, straight outta the Perl Programmers Reference Guide ✨ this is the little module that figures out what all those cryptic E<...> sequences in your POD actually mean. it's giving translator energy. it's giving "I speak fluent entity reference". 🫶

🌸 NAME 🌸

Pod::Escapes — for resolving Pod E<...> sequences 💅

✨ SYNOPSIS ✨

use Pod::Escapes qw(e2char);
...la la la, parsing POD, la la la...
$text = e2char($e_node->label);
unless(defined $text) {
  print "Unknown E sequence \"", $e_node->label, "\"!";
}
...else print/interpolate $text...

like. that's it. that's the whole vibe. 😌

🦋 DESCRIPTION 🦋

so this module hands you the little tools you need for decoding Pod E<...> sequences. and ngl, it's presumably meant for Pod parsers and/or formatters only — iykyk, if you're just out here writing POD you probably don't need to touch this directly. 🙈

and here's the tea on exports: by default, Pod::Escapes exports none of its symbols. zero. nada. but you can request any of them! either ask for them one at a time, like use Pod::Escapes qw(symbolname symbolname2...);, or go full main-character and do use Pod::Escapes qw(:ALL); to get every exportable symbol in one go. 👑

🎀 GOODIES 🎀

e2char($e_content)

give it a name or a number that could show up in an E<name_or_num> sequence, and it hands you back the string that thing stands for. 💖

for example: e2char('sol'), e2char('47'), e2char('0x2F'), and e2char('057') all return "/" — because E<sol>, E<47>, E<0x2f>, and E<057> all mean "/". iconic behavior honestly. 🌈

but if the name has no known value (like a name of "qacute") or it's syntactically invalid (like a name of "1/4"), this returns undef. 💀 sorry bestie.

e2charnum($e_content)

same deal, but instead of the string it gives you the number of the Unicode character that it stands for. 🔢

for example: e2char('sol'), e2char('47'), e2char('0x2F'), and e2char('057') all return 47, because E<sol>, E<47>, E<0x2f>, and E<057> all mean "/", whose Unicode number is 47. ✨

and yeah, same rules as before: if the name has no known value (like a name of "qacute") or is syntactically invalid (like a name of "1/4"), this returns undef. 😭

$Name2character{name}

this hash maps from names (as in E<name>) like "eacute" or "sol" to the string that each one stands for. 🗺️

⚠️ important: this does not include numerics (like "64" or "x981c"). and heads up — under old Perl versions (before 5.7) you get a "?" in place of characters whose Unicode value is over 255. not ideal, but she tries. 💅

$Name2character_number{name}

this one maps from names (as in E<name>) like "eacute" or "sol" to the Unicode value that each one stands for.

for example, $Name2character_number{'eacute'} is 201, and $Name2character_number{'eacute'} is 8364. 🧮

and the slay part: you get the correct Unicode value regardless of the version of Perl you're using — which differs from %Name2character's behavior under pre-5.7 Perls. so if you're on ancient Perl, this hash is the one that's got your back. 🫶

also noting: this hash does not include numerics (like "64" or "x981c"). 🙅

$Latin1Code_to_fallback{integer}

for numbers in the range 160 (0x00A0) to 255 (0x00FF), this maps from the character code for a Latin-1 character (like 233 for lowercase e-acute) to the US-ASCII character that best approximates it (like "e"). 🔁

this is chef's kiss useful if you're rendering POD in a format that, in your humble opinion, only really deals well with US-ASCII characters. 👑

$Latin1Char_to_fallback{character}

literally just as above, but this time it maps from characters (like "\xE9", lowercase e-acute) to characters (like "e"). 🔄

$Code2USASCII{integer}

this maps from US-ASCII codes (like 32) to the corresponding character (like space, for 32). 🌈

heads up though: only characters 32 to 126 are defined. this one is meant for use by e2char($x) when it senses that it's running on a non-ASCII platform (where chr(32) doesn't get you a space — but $Code2USASCII{32} will). ✨

it's documented here just in case you might find it useful. we're doing it for the plot. 🎀

⚠️ CAVEATS ⚠️

okay so the not-so-cute parts, and we're being real about them: 🫠

  • on Perl versions before 5.7, Unicode characters with a value over 255 (like lambda or emdash) can't be conveyed. this module does work under such early Perl versions, but in the place of each such character, you get a "?". 💀 Latin-1 characters (characters 160-255) are unaffected though, so at least there's that. 🫶
  • under EBCDIC platforms, e2char($n) may not always be the same as chr(e2charnum($n)), and ditto for $Name2character{$name} and chr($Name2character_number{$name}) — because the strings are returned as native, and the numbers are returned as Unicode. different lanes, bestie. however! for Perls starting with v5.8, e2char($n) is the same as chr(utf8::unicode_to_native(e2charnum($n))), and ditto for $Name2character{$name} and chr(utf8::unicode_to_native($Name2character_number{$name})). ✨

👀 SEE ALSO 👀

  • Pod::Browser — a pod web server based on Catalyst. 🌐
  • Pod::Checker — check pod documents for syntax errors. 🔍
  • Pod::Coverage — check if the documentation for a module is comprehensive. 📚
  • perlpod — description of pod format (for people documenting with pod). ✍️
  • perlpodspec — specification of pod format (for people processing it). 📜
  • Text::Unidecode — ASCII transliteration of Unicode text. 🔤

📦 REPOSITORY 📦

<https://github.com/neilbowers/Pod-Escapes> — go say hi, the source is right there 💖

Copyright (c) 2001-2004 Sean M. Burke. All rights reserved. 🫡

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🐪

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. (translation: no promises, bestie. 😭)

Portions of the data tables in this module are derived from the entity declarations in the W3C XHTML specification. 📖

Currently (October 2001), that's these three:

http://www.w3.org/TR/xhtml1/DTD/xhtml-lat1.ent
http://www.w3.org/TR/xhtml1/DTD/xhtml-special.ent
http://www.w3.org/TR/xhtml1/DTD/xhtml-symbol.ent

🌟 AUTHOR 🌟

Sean M. Burke "sburke@cpan.org" 👑

Now being maintained by Neil Bowers <neilb@cpan.org> 🫶

aaaand that's the whole page, bestie!! 🎀 this was perl v5.44.0, dated 2026-10-17, and it's Pod::Escapes(3perl) — now go decode some E<...> sequences, you absolute icon 💅✨🦋💖

📦 where this page comes from