| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "charnames 3perl" |
| 58 |
.TH charnames 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
charnames \- access to Unicode character names and named character sequences; also define character names |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 4 |
| 68 |
\& use charnames \*(Aq:full\*(Aq; |
| 69 |
\& print "\eN{GREEK SMALL LETTER SIGMA} is called sigma.\en"; |
| 70 |
\& print "\eN{LATIN CAPITAL LETTER E WITH VERTICAL LINE BELOW}", |
| 71 |
\& " is an officially named sequence of two Unicode characters\en"; |
| 72 |
\& |
| 73 |
\& use charnames \*(Aq:loose\*(Aq; |
| 74 |
\& print "\eN{Greek small\-letter sigma}", |
| 75 |
\& "can be used to ignore case, underscores, most blanks," |
| 76 |
\& "and when you aren\*(Aqt sure if the official name has hyphens\en"; |
| 77 |
\& |
| 78 |
\& use charnames \*(Aq:short\*(Aq; |
| 79 |
\& print "\eN{greek:Sigma} is an upper\-case sigma.\en"; |
| 80 |
\& |
| 81 |
\& use charnames qw(cyrillic greek); |
| 82 |
\& print "\eN{sigma} is Greek sigma, and \eN{be} is Cyrillic b.\en"; |
| 83 |
\& |
| 84 |
\& use utf8; |
| 85 |
\& use charnames ":full", ":alias" => { |
| 86 |
\& e_ACUTE => "LATIN SMALL LETTER E WITH ACUTE", |
| 87 |
\& mychar => 0xE8000, # Private use area |
| 88 |
\& "自転車に乗る人" => "BICYCLIST" |
| 89 |
\& }; |
| 90 |
\& print "\eN{e_ACUTE} is a small letter e with an acute.\en"; |
| 91 |
\& print "\eN{mychar} allows me to name private use characters.\en"; |
| 92 |
\& print "And I can create synonyms in other languages,", |
| 93 |
\& " such as \eN{自転車に乗る人} for "BICYCLIST (U+1F6B4)\en"; |
| 94 |
\& |
| 95 |
\& use charnames (); |
| 96 |
\& print charnames::viacode(0x1234); # prints "ETHIOPIC SYLLABLE SEE" |
| 97 |
\& printf "%04X", charnames::vianame("GOTHIC LETTER AHSA"); # prints |
| 98 |
\& # "10330" |
| 99 |
\& print charnames::vianame("LATIN CAPITAL LETTER A"); # prints 65 on |
| 100 |
\& # ASCII platforms; |
| 101 |
\& # 193 on EBCDIC |
| 102 |
\& print charnames::string_vianame("LATIN CAPITAL LETTER A"); # prints "A" |
| 103 |
.Ve |
| 104 |
.SH DESCRIPTION |
| 105 |
.IX Header "DESCRIPTION" |
| 106 |
Pragma \f(CW\*(C`use charnames\*(C'\fR is used to gain access to the names of the |
| 107 |
Unicode characters and named character sequences, and to allow you to define |
| 108 |
your own character and character sequence names. |
| 109 |
.PP |
| 110 |
All forms of the pragma enable use of the following 3 functions: |
| 111 |
.IP \(bu 4 |
| 112 |
"charnames::string_vianame(\fIname\fR)" for run-time lookup of a |
| 113 |
either a character name or a named character sequence, returning its string |
| 114 |
representation |
| 115 |
.IP \(bu 4 |
| 116 |
"charnames::vianame(\fIname\fR)" for run-time lookup of a |
| 117 |
character name (but not a named character sequence) to get its ordinal value |
| 118 |
(code point) |
| 119 |
.IP \(bu 4 |
| 120 |
"charnames::viacode(\fIcode\fR)" for run-time lookup of a code point to get its |
| 121 |
Unicode name. |
| 122 |
.PP |
| 123 |
Starting in Perl v5.16, any occurrence of \f(CW\*(C`\eN{\fR\f(CICHARNAME\fR\f(CW}\*(C'\fR sequences |
| 124 |
in a double-quotish string automatically loads this module with arguments |
| 125 |
\&\f(CW\*(C`:full\*(C'\fR and \f(CW\*(C`:short\*(C'\fR (described below) if it hasn't already been loaded with |
| 126 |
different arguments, in order to compile the named Unicode character into |
| 127 |
position in the string. Prior to v5.16, an explicit \f(CW\*(C`use\ charnames\*(C'\fR was |
| 128 |
required to enable this usage. (However, prior to v5.16, the form \f(CW"use\ charnames\ ();"\fR did not enable \f(CW\*(C`\eN{\fR\f(CICHARNAME\fR\f(CW}\*(C'\fR.) |
| 129 |
.PP |
| 130 |
Note that \f(CW\*(C`\eN{U+\fR\f(CI...\fR\f(CW}\*(C'\fR, where the \fI...\fR is a hexadecimal number, |
| 131 |
also inserts a character into a string. |
| 132 |
The character it inserts is the one whose Unicode code point |
| 133 |
(ordinal value) is equal to the number. For example, \f(CW"\eN{U+263a}"\fR is |
| 134 |
the Unicode (white background, black foreground) smiley face |
| 135 |
equivalent to \f(CW"\eN{WHITE SMILING FACE}"\fR. |
| 136 |
Also note, \f(CW\*(C`\eN{\fR\f(CI...\fR\f(CW}\*(C'\fR can mean a regex quantifier instead of a character |
| 137 |
name, when the \fI...\fR is a number (or comma separated pair of numbers |
| 138 |
(see "QUANTIFIERS" in perlreref), and is not related to this pragma. |
| 139 |
.PP |
| 140 |
The \f(CW\*(C`charnames\*(C'\fR pragma supports arguments \f(CW\*(C`:full\*(C'\fR, \f(CW\*(C`:loose\*(C'\fR, \f(CW\*(C`:short\*(C'\fR, |
| 141 |
script names and customized aliases. |
| 142 |
.PP |
| 143 |
If \f(CW\*(C`:full\*(C'\fR is present, for expansion of |
| 144 |
\&\f(CW\*(C`\eN{\fR\f(CICHARNAME\fR\f(CW}\*(C'\fR, the string \fICHARNAME\fR is first looked up in the list of |
| 145 |
standard Unicode character names. |
| 146 |
.PP |
| 147 |
\&\f(CW\*(C`:loose\*(C'\fR is a variant of \f(CW\*(C`:full\*(C'\fR which allows \fICHARNAME\fR to be less |
| 148 |
precisely specified. Details are in "LOOSE MATCHES". |
| 149 |
.PP |
| 150 |
If \f(CW\*(C`:short\*(C'\fR is present, and |
| 151 |
\&\fICHARNAME\fR has the form \f(CW\*(C`\fR\f(CISCRIPT\fR\f(CW:\fR\f(CICNAME\fR\f(CW\*(C'\fR, then \fICNAME\fR is looked up |
| 152 |
as a letter in script \fISCRIPT\fR, as described in the next paragraph. |
| 153 |
Or, if \f(CW\*(C`use charnames\*(C'\fR is used |
| 154 |
with script name arguments, then for \f(CW\*(C`\eN{\fR\f(CICHARNAME\fR\f(CW}\*(C'\fR the name |
| 155 |
\&\fICHARNAME\fR is looked up as a letter in the given scripts (in the |
| 156 |
specified order). Customized aliases can override these, and are explained in |
| 157 |
"CUSTOM ALIASES". |
| 158 |
.PP |
| 159 |
For lookup of \fICHARNAME\fR inside a given script \fISCRIPTNAME\fR, |
| 160 |
this pragma looks in the table of standard Unicode names for the names |
| 161 |
.PP |
| 162 |
.Vb 3 |
| 163 |
\& SCRIPTNAME CAPITAL LETTER CHARNAME |
| 164 |
\& SCRIPTNAME SMALL LETTER CHARNAME |
| 165 |
\& SCRIPTNAME LETTER CHARNAME |
| 166 |
.Ve |
| 167 |
.PP |
| 168 |
If \fICHARNAME\fR is all lowercase, |
| 169 |
then the \f(CW\*(C`CAPITAL\*(C'\fR variant is ignored, otherwise the \f(CW\*(C`SMALL\*(C'\fR variant |
| 170 |
is ignored, and both \fICHARNAME\fR and \fISCRIPTNAME\fR are converted to all |
| 171 |
uppercase for look-up. Other than that, both of them follow loose rules if \f(CW\*(C`:loose\*(C'\fR is also specified; strict otherwise. |
| 172 |
.PP |
| 173 |
Note that \f(CW\*(C`\eN{...}\*(C'\fR is compile-time; it's a special form of string |
| 174 |
constant used inside double-quotish strings; this means that you cannot |
| 175 |
use variables inside the \f(CW\*(C`\eN{...}\*(C'\fR. If you want similar run-time |
| 176 |
functionality, use |
| 177 |
\&\fBcharnames::string_vianame()\fR. |
| 178 |
.PP |
| 179 |
Note, starting in Perl 5.18, the name \f(CW\*(C`BELL\*(C'\fR refers to the Unicode character |
| 180 |
U+1F514, instead of the traditional U+0007. For the latter, use \f(CW\*(C`ALERT\*(C'\fR |
| 181 |
or \f(CW\*(C`BEL\*(C'\fR. |
| 182 |
.PP |
| 183 |
It is a syntax error to use \f(CW\*(C`\eN{NAME}\*(C'\fR where \f(CW\*(C`NAME\*(C'\fR is unknown. |
| 184 |
.PP |
| 185 |
For \f(CW\*(C`\eN{NAME}\*(C'\fR, it is a fatal error if \f(CW\*(C`use bytes\*(C'\fR is in effect and the |
| 186 |
input name is that of a character that won't fit into a byte (i.e., whose |
| 187 |
ordinal is above 255). |
| 188 |
.PP |
| 189 |
Otherwise, any string that includes a \f(CW\*(C`\eN{\fR\f(CIcharname\fR\f(CW}\*(C'\fR or |
| 190 |
\&\f(CW\*(C`\eN{U+\fR\f(CIcode\ point\fR\f(CW}\*(C'\fR will automatically have Unicode rules (see |
| 191 |
"Byte and Character Semantics" in perlunicode). |
| 192 |
.SH "LOOSE MATCHES" |
| 193 |
.IX Header "LOOSE MATCHES" |
| 194 |
By specifying \f(CW\*(C`:loose\*(C'\fR, Unicode's loose character name |
| 195 |
matching <http://www.unicode.org/reports/tr44#Matching_Rules> rules are |
| 196 |
selected instead of the strict exact match used otherwise. |
| 197 |
That means that \fICHARNAME\fR doesn't have to be so precisely specified. |
| 198 |
Upper/lower case doesn't matter (except with scripts as mentioned above), nor |
| 199 |
do any underscores, and the only hyphens that matter are those at the |
| 200 |
beginning or end of a word in the name (with one exception: the hyphen in |
| 201 |
U+1180 \f(CW\*(C`HANGUL JUNGSEONG O\-E\*(C'\fR does matter). |
| 202 |
Also, blanks not adjacent to hyphens don't matter. |
| 203 |
The official Unicode names are quite variable as to where they use hyphens |
| 204 |
versus spaces to separate word-like units, and this option allows you to not |
| 205 |
have to care as much. |
| 206 |
The reason non-medial hyphens matter is because of cases like |
| 207 |
U+0F60 \f(CW\*(C`TIBETAN LETTER \-A\*(C'\fR versus U+0F68 \f(CW\*(C`TIBETAN LETTER A\*(C'\fR. |
| 208 |
The hyphen here is significant, as is the space before it, and so both must be |
| 209 |
included. |
| 210 |
.PP |
| 211 |
\&\f(CW\*(C`:loose\*(C'\fR slows down look-ups by a factor of 2 to 3 versus |
| 212 |
\&\f(CW\*(C`:full\*(C'\fR, but the trade-off may be worth it to you. Each individual look-up |
| 213 |
takes very little time, and the results are cached, so the speed difference |
| 214 |
would become a factor only in programs that do look-ups of many different |
| 215 |
spellings, and probably only when those look-ups are through \f(CWvianame()\fR and |
| 216 |
\&\f(CWstring_vianame()\fR, since \f(CW\*(C`\eN{...}\*(C'\fR look-ups are done at compile time. |
| 217 |
.SH ALIASES |
| 218 |
.IX Header "ALIASES" |
| 219 |
Starting in Unicode 6.1 and Perl v5.16, Unicode defines many abbreviations and |
| 220 |
names that were formerly Perl extensions, and some additional ones that Perl |
| 221 |
did not previously accept. The list is getting too long to reproduce here, |
| 222 |
but you can get the complete list from the Unicode web site: |
| 223 |
<http://www.unicode.org/Public/UNIDATA/NameAliases.txt>. |
| 224 |
.PP |
| 225 |
Earlier versions of Perl accepted almost all the 6.1 names. These were most |
| 226 |
extensively documented in the v5.14 version of this pod: |
| 227 |
<http://perldoc.perl.org/5.14.0/charnames.html#ALIASES>. |
| 228 |
.SH "CUSTOM ALIASES" |
| 229 |
.IX Header "CUSTOM ALIASES" |
| 230 |
You can add customized aliases to standard (\f(CW\*(C`:full\*(C'\fR) Unicode naming |
| 231 |
conventions. The aliases override any standard definitions, so, if |
| 232 |
you're twisted enough, you can change \f(CW"\eN{LATIN CAPITAL LETTER A}"\fR to |
| 233 |
mean \f(CW"B"\fR, etc. |
| 234 |
.PP |
| 235 |
Aliases must begin with a character that is alphabetic. After that, each may |
| 236 |
contain any combination of word (\f(CW\*(C`\ew\*(C'\fR) characters, SPACE (U+0020), |
| 237 |
HYPHEN-MINUS (U+002D), LEFT PARENTHESIS (U+0028), and RIGHT PARENTHESIS |
| 238 |
(U+0029). These last two should never have been allowed |
| 239 |
in names, and are retained for backwards compatibility only, and may be |
| 240 |
deprecated and removed in future releases of Perl, so don't use them for new |
| 241 |
names. (More precisely, the first character of a name you specify must be |
| 242 |
something that matches all of \f(CW\*(C`\ep{ID_Start}\*(C'\fR, \f(CW\*(C`\ep{Alphabetic}\*(C'\fR, and |
| 243 |
\&\f(CW\*(C`\ep{Gc=Letter}\*(C'\fR. This makes sure it is what any reasonable person would view |
| 244 |
as an alphabetic character. And, the continuation characters that match \f(CW\*(C`\ew\*(C'\fR |
| 245 |
must also match \f(CW\*(C`\ep{ID_Continue}\*(C'\fR.) Starting with Perl v5.18, any Unicode |
| 246 |
characters meeting the above criteria may be used; prior to that only |
| 247 |
Latin1\-range characters were acceptable. |
| 248 |
.PP |
| 249 |
An alias can map to either an official Unicode character name (not a loose |
| 250 |
matched name) or to a |
| 251 |
numeric code point (ordinal). The latter is useful for assigning names |
| 252 |
to code points in Unicode private use areas such as U+E800 through |
| 253 |
U+F8FF. |
| 254 |
A numeric code point must be a non-negative integer, or a string beginning |
| 255 |
with \f(CW"U+"\fR or \f(CW"0x"\fR with the remainder considered to be a |
| 256 |
hexadecimal integer. A literal numeric constant must be unsigned; it |
| 257 |
will be interpreted as hex if it has a leading zero or contains |
| 258 |
non-decimal hex digits; otherwise it will be interpreted as decimal. |
| 259 |
If it begins with \f(CW"U+"\fR, it is interpreted as the Unicode code point; |
| 260 |
otherwise it is interpreted as native. (Only code points below 256 can |
| 261 |
differ between Unicode and native.) Thus \f(CW\*(C`U+41\*(C'\fR is always the Latin letter |
| 262 |
"A"; but \f(CW0x41\fR can be "NO-BREAK SPACE" on EBCDIC platforms. |
| 263 |
.PP |
| 264 |
Aliases are added either by the use of anonymous hashes: |
| 265 |
.PP |
| 266 |
.Vb 5 |
| 267 |
\& use charnames ":alias" => { |
| 268 |
\& e_ACUTE => "LATIN SMALL LETTER E WITH ACUTE", |
| 269 |
\& mychar1 => 0xE8000, |
| 270 |
\& }; |
| 271 |
\& my $str = "\eN{e_ACUTE}"; |
| 272 |
.Ve |
| 273 |
.PP |
| 274 |
or by using a file containing aliases: |
| 275 |
.PP |
| 276 |
.Vb 1 |
| 277 |
\& use charnames ":alias" => "pro"; |
| 278 |
.Ve |
| 279 |
.PP |
| 280 |
This will try to read \f(CW"unicore/pro_alias.pl"\fR from the \f(CW@INC\fR path. This |
| 281 |
file should return a list in plain perl: |
| 282 |
.PP |
| 283 |
.Vb 10 |
| 284 |
\& ( |
| 285 |
\& A_GRAVE => "LATIN CAPITAL LETTER A WITH GRAVE", |
| 286 |
\& A_CIRCUM => "LATIN CAPITAL LETTER A WITH CIRCUMFLEX", |
| 287 |
\& A_DIAERES => "LATIN CAPITAL LETTER A WITH DIAERESIS", |
| 288 |
\& A_TILDE => "LATIN CAPITAL LETTER A WITH TILDE", |
| 289 |
\& A_BREVE => "LATIN CAPITAL LETTER A WITH BREVE", |
| 290 |
\& A_RING => "LATIN CAPITAL LETTER A WITH RING ABOVE", |
| 291 |
\& A_MACRON => "LATIN CAPITAL LETTER A WITH MACRON", |
| 292 |
\& mychar2 => "U+E8001", |
| 293 |
\& ); |
| 294 |
.Ve |
| 295 |
.PP |
| 296 |
Both these methods insert \f(CW":full"\fR automatically as the first argument (if no |
| 297 |
other argument is given), and you can give the \f(CW":full"\fR explicitly as |
| 298 |
well, like |
| 299 |
.PP |
| 300 |
.Vb 1 |
| 301 |
\& use charnames ":full", ":alias" => "pro"; |
| 302 |
.Ve |
| 303 |
.PP |
| 304 |
\&\f(CW":loose"\fR has no effect with these. Input names must match exactly, using |
| 305 |
\&\f(CW":full"\fR rules. |
| 306 |
.PP |
| 307 |
Also, both these methods currently allow only single characters to be named. |
| 308 |
To name a sequence of characters, use a |
| 309 |
custom translator (described below). |
| 310 |
.SH charnames::string_vianame(\fIname\fP) |
| 311 |
.IX Header "charnames::string_vianame(name)" |
| 312 |
This is a runtime equivalent to \f(CW\*(C`\eN{...}\*(C'\fR. \fIname\fR can be any expression |
| 313 |
that evaluates to a name accepted by \f(CW\*(C`\eN{...}\*(C'\fR under the \f(CW\*(C`:full\*(C'\fR |
| 314 |
option to \f(CW\*(C`charnames\*(C'\fR. In addition, any other options for the |
| 315 |
controlling \f(CW"use charnames"\fR in the same scope apply, like \f(CW\*(C`:loose\*(C'\fR or any |
| 316 |
script list, \f(CW\*(C`:short\*(C'\fR option, or custom aliases you may have defined. |
| 317 |
.PP |
| 318 |
The only differences are due to the fact that \f(CW\*(C`string_vianame\*(C'\fR is run-time |
| 319 |
and \f(CW\*(C`\eN{}\*(C'\fR is compile time. You can't interpolate inside a \f(CW\*(C`\eN{}\*(C'\fR, (so |
| 320 |
\&\f(CW\*(C`\eN{$variable}\*(C'\fR doesn't work); and if the input name is unknown, |
| 321 |
\&\f(CW\*(C`string_vianame\*(C'\fR returns \f(CW\*(C`undef\*(C'\fR instead of it being a syntax error. |
| 322 |
.SH charnames::vianame(\fIname\fP) |
| 323 |
.IX Header "charnames::vianame(name)" |
| 324 |
This is similar to \f(CW\*(C`string_vianame\*(C'\fR. The main difference is that under most |
| 325 |
circumstances, \f(CW\*(C`vianame\*(C'\fR returns an ordinal code |
| 326 |
point, whereas \f(CW\*(C`string_vianame\*(C'\fR returns a string. For example, |
| 327 |
.PP |
| 328 |
.Vb 1 |
| 329 |
\& printf "U+%04X", charnames::vianame("FOUR TEARDROP\-SPOKED ASTERISK"); |
| 330 |
.Ve |
| 331 |
.PP |
| 332 |
prints "U+2722". |
| 333 |
.PP |
| 334 |
This leads to the other two differences. Since a single code point is |
| 335 |
returned, the function can't handle named character sequences, as these are |
| 336 |
composed of multiple characters (it returns \f(CW\*(C`undef\*(C'\fR for these. And, the code |
| 337 |
point can be that of any |
| 338 |
character, even ones that aren't legal under the \f(CW\*(C`use\ bytes\*(C'\fR pragma, |
| 339 |
.PP |
| 340 |
See "BUGS" for the circumstances in which the behavior differs |
| 341 |
from that described above. |
| 342 |
.SH charnames::viacode(\fIcode\fP) |
| 343 |
.IX Header "charnames::viacode(code)" |
| 344 |
Returns the full name of the character indicated by the numeric code. |
| 345 |
For example, |
| 346 |
.PP |
| 347 |
.Vb 1 |
| 348 |
\& print charnames::viacode(0x2722); |
| 349 |
.Ve |
| 350 |
.PP |
| 351 |
prints "FOUR TEARDROP-SPOKED ASTERISK". |
| 352 |
.PP |
| 353 |
The name returned is the "best" (defined below) official name or alias |
| 354 |
for the code point, if |
| 355 |
available; otherwise your custom alias for it, if defined; otherwise \f(CW\*(C`undef\*(C'\fR. |
| 356 |
This means that your alias will only be returned for code points that don't |
| 357 |
have an official Unicode name (nor alias) such as private use code points. |
| 358 |
.PP |
| 359 |
If you define more than one name for the code point, it is indeterminate |
| 360 |
which one will be returned. |
| 361 |
.PP |
| 362 |
As mentioned, the function returns \f(CW\*(C`undef\*(C'\fR if no name is known for the code |
| 363 |
point. In Unicode the proper name for these is the empty string, which |
| 364 |
\&\f(CW\*(C`undef\*(C'\fR stringifies to. (If you ask for a code point past the legal |
| 365 |
Unicode maximum of U+10FFFF that you haven't assigned an alias to, you |
| 366 |
get \f(CW\*(C`undef\*(C'\fR plus a warning.) |
| 367 |
.PP |
| 368 |
The input number must be a non-negative integer, or a string beginning |
| 369 |
with \f(CW"U+"\fR or \f(CW"0x"\fR with the remainder considered to be a |
| 370 |
hexadecimal integer. A literal numeric constant must be unsigned; it |
| 371 |
will be interpreted as hex if it has a leading zero or contains |
| 372 |
non-decimal hex digits; otherwise it will be interpreted as decimal. |
| 373 |
If it begins with \f(CW"U+"\fR, it is interpreted as the Unicode code point; |
| 374 |
otherwise it is interpreted as native. (Only code points below 256 can |
| 375 |
differ between Unicode and native.) Thus \f(CW\*(C`U+41\*(C'\fR is always the Latin letter |
| 376 |
"A"; but \f(CW0x41\fR can be "NO-BREAK SPACE" on EBCDIC platforms. |
| 377 |
.PP |
| 378 |
As mentioned above under "ALIASES", Unicode 6.1 defines extra names |
| 379 |
(synonyms or aliases) for some code points, most of which were already |
| 380 |
available as Perl extensions. All these are accepted by \f(CW\*(C`\eN{...}\*(C'\fR and the |
| 381 |
other functions in this module, but \f(CW\*(C`viacode\*(C'\fR has to choose which one |
| 382 |
name to return for a given input code point, so it returns the "best" name. |
| 383 |
To understand how this works, it is helpful to know more about the Unicode |
| 384 |
name properties. All code points actually have only a single name, which |
| 385 |
(starting in Unicode 2.0) can never change once a character has been assigned |
| 386 |
to the code point. But mistakes have been made in assigning names, for |
| 387 |
example sometimes a clerical error was made during the publishing of the |
| 388 |
Standard which caused words to be misspelled, and there was no way to correct |
| 389 |
those. The Name_Alias property was eventually created to handle these |
| 390 |
situations. If a name was wrong, a corrected synonym would be published for |
| 391 |
it, using Name_Alias. \f(CW\*(C`viacode\*(C'\fR will return that corrected synonym as the |
| 392 |
"best" name for a code point. (It is even possible, though it hasn't happened |
| 393 |
yet, that the correction itself will need to be corrected, and so another |
| 394 |
Name_Alias can be created for that code point; \f(CW\*(C`viacode\*(C'\fR will return the |
| 395 |
most recent correction.) |
| 396 |
.PP |
| 397 |
The Unicode name for each of the control characters (such as LINE FEED) is the |
| 398 |
empty string. However almost all had names assigned by other standards, such |
| 399 |
as the ASCII Standard, or were in common use. \f(CW\*(C`viacode\*(C'\fR returns these names |
| 400 |
as the "best" ones available. Unicode 6.1 has created Name_Aliases for each |
| 401 |
of them, including alternate names, like NEW LINE. \f(CW\*(C`viacode\*(C'\fR uses the |
| 402 |
original name, "LINE FEED" in preference to the alternate. Similarly the |
| 403 |
name returned for U+FEFF is "ZERO WIDTH NO-BREAK SPACE", not "BYTE ORDER |
| 404 |
MARK". |
| 405 |
.PP |
| 406 |
Until Unicode 6.1, the 4 control characters U+0080, U+0081, U+0084, and U+0099 |
| 407 |
did not have names nor aliases. |
| 408 |
To preserve backwards compatibility, any alias you define for these code |
| 409 |
points will be returned by this function, in preference to the official name. |
| 410 |
.PP |
| 411 |
Some code points also have abbreviated names, such as "LF" or "NL". |
| 412 |
\&\f(CW\*(C`viacode\*(C'\fR never returns these. |
| 413 |
.PP |
| 414 |
Because a name correction may be added in future Unicode releases, the name |
| 415 |
that \f(CW\*(C`viacode\*(C'\fR returns may change as a result. This is a rare event, but it |
| 416 |
does happen. |
| 417 |
.SH "CUSTOM TRANSLATORS" |
| 418 |
.IX Header "CUSTOM TRANSLATORS" |
| 419 |
The mechanism of translation of \f(CW\*(C`\eN{...}\*(C'\fR escapes is general and not |
| 420 |
hardwired into \fIcharnames.pm\fR. A module can install custom |
| 421 |
translations (inside the scope which \f(CW\*(C`use\*(C'\fRs the module) with the |
| 422 |
following magic incantation: |
| 423 |
.PP |
| 424 |
.Vb 4 |
| 425 |
\& sub import { |
| 426 |
\& shift; |
| 427 |
\& $^H{charnames} = \e&translator; |
| 428 |
\& } |
| 429 |
.Ve |
| 430 |
.PP |
| 431 |
Here \fBtranslator()\fR is a subroutine which takes \fICHARNAME\fR as an |
| 432 |
argument, and returns text to insert into the string instead of the |
| 433 |
\&\f(CW\*(C`\eN{\fR\f(CICHARNAME\fR\f(CW}\*(C'\fR escape. |
| 434 |
.PP |
| 435 |
This is the only way you can create a custom named sequence of code points. |
| 436 |
.PP |
| 437 |
Since the text to insert should be different |
| 438 |
in \f(CW\*(C`bytes\*(C'\fR mode and out of it, the function should check the current |
| 439 |
state of \f(CW\*(C`bytes\*(C'\fR\-flag as in: |
| 440 |
.PP |
| 441 |
.Vb 9 |
| 442 |
\& use bytes (); # for $bytes::hint_bits |
| 443 |
\& sub translator { |
| 444 |
\& if ($^H & $bytes::hint_bits) { |
| 445 |
\& return bytes_translator(@_); |
| 446 |
\& } |
| 447 |
\& else { |
| 448 |
\& return utf8_translator(@_); |
| 449 |
\& } |
| 450 |
\& } |
| 451 |
.Ve |
| 452 |
.PP |
| 453 |
See "CUSTOM ALIASES" above for restrictions on \fICHARNAME\fR. |
| 454 |
.PP |
| 455 |
Of course, \f(CW\*(C`vianame\*(C'\fR, \f(CW\*(C`viacode\*(C'\fR, and \f(CW\*(C`string_vianame\*(C'\fR would need to be |
| 456 |
overridden as well. |
| 457 |
.SH BUGS |
| 458 |
.IX Header "BUGS" |
| 459 |
\&\fBvianame()\fR normally returns an ordinal code point, but when the input name is of |
| 460 |
the form \f(CW\*(C`U+...\*(C'\fR, it returns a chr instead. In this case, if \f(CW\*(C`use bytes\*(C'\fR is |
| 461 |
in effect and the character won't fit into a byte, it returns \f(CW\*(C`undef\*(C'\fR and |
| 462 |
raises a warning. |
| 463 |
.PP |
| 464 |
Since evaluation of the translation function (see "CUSTOM |
| 465 |
TRANSLATORS") happens in the middle of compilation (of a string |
| 466 |
literal), the translation function should not do any \f(CW\*(C`eval\*(C'\fRs or |
| 467 |
\&\f(CW\*(C`require\*(C'\fRs. This restriction should be lifted (but is low priority) in |
| 468 |
a future version of Perl. |