Debian Codegraph @

upstream/debian-unstable/man3/charnames.3perl

raw
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.