Debian Codegraph @

upstream/mageia-cauldron/man3pm/charnames.3pm

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