Pod::Escapes -- for resolving Pod E<...> sequences
- 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...
This module provides things that are useful in decoding Pod E<...> sequences. Presumably, it should be used only by Pod parsers and/or formatters.
By default, Pod::Escapes exports none of its symbols. But
you can request any of them to be exported.
Either request them individually, as with
use Pod::Escapes qw(symbolname symbolname2...);
,
or you can do use Pod::Escapes qw(:ALL);
to get all
exportable symbols.
Given a name or number that could appear in a
E<name_or_num>
sequence, this returns the string that
it 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 "/". If
the name has no known value (as with a name of "qacute") or is
syntactally invalid (as with a name of "1/4"), this returns undef.
Given a name or number that could appear in a
E<name_or_num>
sequence, this returns the number of
the Unicode character that this 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. If
the name has no known value (as with a name of "qacute") or is
syntactally invalid (as with a name of "1/4"), this returns undef.
Maps from names (as in E<name>) like "eacute" or "sol"
to the string that each stands for. Note that this does not
include numerics (like "64" or "x981c"). Under old Perl versions
(before 5.7) you get a "?" in place of characters whose Unicode
value is over 255.
Maps from names (as in E<name>) like "eacute" or "sol"
to the Unicode value that each stands for. For example,
$Name2character_number{'eacute'}
is 201, and
$Name2character_number{'eacute'}
is 8364. 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.
Note that this hash does not include numerics (like "64" or "x981c").
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 aproximates it (like "e"). You may find this useful if you are rendering POD in a format that you think deals well only with US-ASCII characters.
Just as above, but maps from characters (like "\xE9", lowercase e-acute) to characters (like "e").
This maps from US-ASCII codes (like 32) to the corresponding
character (like space, for 32). Only characters 32 to 126 are
defined. This 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.
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.
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}).
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.
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
Sean M. Burke sburke@cpan.org