1charnames(3pm) Perl Programmers Reference Guide charnames(3pm)
2
6 charnames - define character names for "\N{named}" string literal
7 escapes
8
10 use charnames ':full';
11 print "\N{GREEK SMALL LETTER SIGMA} is called sigma.\n";
12 use charnames ':short';
14 print "\N{greek:Sigma} is an upper-case sigma.\n";
15 use charnames qw(cyrillic greek);
17 print "\N{sigma} is Greek sigma, and \N{be} is Cyrillic b.\n";
18 use charnames ":full", ":alias" => {
20 e_ACUTE => "LATIN SMALL LETTER E WITH ACUTE",
21 };
22 print "\N{e_ACUTE} is a small letter e with an acute.\n";
23 use charnames ();
25 print charnames::viacode(0x1234); # prints "ETHIOPIC SYLLABLE SEE"
26 printf "%04X", charnames::vianame("GOTHIC LETTER AHSA"); # prints "10330"
27
29 Pragma "use charnames" supports arguments ":full", ":short", script
30 names and customized aliases. If ":full" is present, for expansion of
31 "\N{CHARNAME}", the string "CHARNAME" is first looked up in the list of
32 standard Unicode character names. If ":short" is present, and
33 "CHARNAME" has the form "SCRIPT:CNAME", then "CNAME" is looked up as a
34 letter in script "SCRIPT". If pragma "use charnames" is used with
35 script name arguments, then for "\N{CHARNAME}" the name "CHARNAME" is
36 looked up as a letter in the given scripts (in the specified order).
37 Customized aliases are explained in "CUSTOM ALIASES".
38 For lookup of "CHARNAME" inside a given script "SCRIPTNAME" this pragma
40 looks for the names
41 SCRIPTNAME CAPITAL LETTER CHARNAME
43 SCRIPTNAME SMALL LETTER CHARNAME
44 SCRIPTNAME LETTER CHARNAME
45 in the table of standard Unicode names. If "CHARNAME" is lowercase,
47 then the "CAPITAL" variant is ignored, otherwise the "SMALL" variant is
48 ignored.
49 Note that "\N{...}" is compile-time, it's a special form of string
51 constant used inside double-quoted strings: in other words, you cannot
52 use variables inside the "\N{...}". If you want similar run-time
53 functionality, use charnames::vianame().
54 For the C0 and C1 control characters (U+0000..U+001F, U+0080..U+009F)
56 as of Unicode 3.1, there are no official Unicode names but you can use
57 instead the ISO 6429 names (LINE FEED, ESCAPE, and so forth). In
58 Unicode 3.2 (as of Perl 5.8) some naming changes take place ISO 6429
59 has been updated, see "ALIASES". Also note that the U+UU80, U+0081,
60 U+0084, and U+0099 do not have names even in ISO 6429.
61 Since the Unicode standard uses "U+HHHH", so can you: "\N{U+263a}" is
63 the Unicode smiley face, or "\N{WHITE SMILING FACE}".
64
66 A few aliases have been defined for convenience: instead of having to
67 use the official names
68 LINE FEED (LF)
70 FORM FEED (FF)
71 CARRIAGE RETURN (CR)
72 NEXT LINE (NEL)
73 (yes, with parentheses) one can use
75 LINE FEED
77 FORM FEED
78 CARRIAGE RETURN
79 NEXT LINE
80 LF
81 FF
82 CR
83 NEL
84 One can also use
86 BYTE ORDER MARK
88 BOM
89 and
91 ZWNJ
93 ZWJ
94 for ZERO WIDTH NON-JOINER and ZERO WIDTH JOINER.
96 For backward compatibility one can use the old names for certain C0 and
98 C1 controls
99 old new
101 HORIZONTAL TABULATION CHARACTER TABULATION
103 VERTICAL TABULATION LINE TABULATION
104 FILE SEPARATOR INFORMATION SEPARATOR FOUR
105 GROUP SEPARATOR INFORMATION SEPARATOR THREE
106 RECORD SEPARATOR INFORMATION SEPARATOR TWO
107 UNIT SEPARATOR INFORMATION SEPARATOR ONE
108 PARTIAL LINE DOWN PARTIAL LINE FORWARD
109 PARTIAL LINE UP PARTIAL LINE BACKWARD
110 but the old names in addition to giving the character will also give a
112 warning about being deprecated.
113
115 This version of charnames supports three mechanisms of adding local or
116 customized aliases to standard Unicode naming conventions (:full)
117 Anonymous hashes
119 use charnames ":full", ":alias" => {
120 e_ACUTE => "LATIN SMALL LETTER E WITH ACUTE",
121 };
122 my $str = "\N{e_ACUTE}";
123 Alias file
125 use charnames ":full", ":alias" => "pro";
126 will try to read "unicore/pro_alias.pl" from the @INC path. This
128 file should return a list in plain perl:
129 (
131 A_GRAVE => "LATIN CAPITAL LETTER A WITH GRAVE",
132 A_CIRCUM => "LATIN CAPITAL LETTER A WITH CIRCUMFLEX",
133 A_DIAERES => "LATIN CAPITAL LETTER A WITH DIAERESIS",
134 A_TILDE => "LATIN CAPITAL LETTER A WITH TILDE",
135 A_BREVE => "LATIN CAPITAL LETTER A WITH BREVE",
136 A_RING => "LATIN CAPITAL LETTER A WITH RING ABOVE",
137 A_MACRON => "LATIN CAPITAL LETTER A WITH MACRON",
138 );
139 Alias shortcut
141 use charnames ":alias" => ":pro";
142 works exactly the same as the alias pairs, only this time,
144 ":full" is inserted automatically as first argument (if no
145 other argument is given).
146
148 Returns the full name of the character indicated by the numeric code.
149 The example
150 print charnames::viacode(0x2722);
152 prints "FOUR TEARDROP-SPOKED ASTERISK".
154 Returns undef if no name is known for the code.
156 This works only for the standard names, and does not yet apply to
158 custom translators.
159 Notice that the name returned for of U+FEFF is "ZERO WIDTH NO-BREAK
161 SPACE", not "BYTE ORDER MARK".
162
164 Returns the code point indicated by the name. The example
165 printf "%04X", charnames::vianame("FOUR TEARDROP-SPOKED ASTERISK");
167 prints "2722".
169 Returns undef if the name is unknown.
171 This works only for the standard names, and does not yet apply to
173 custom translators.
174
176 The mechanism of translation of "\N{...}" escapes is general and not
177 hardwired into charnames.pm. A module can install custom translations
178 (inside the scope which "use"s the module) with the following magic
179 incantation:
180 sub import {
182 shift;
183 $^H{charnames} = \&translator;
184 }
185 Here translator() is a subroutine which takes "CHARNAME" as an
187 argument, and returns text to insert into the string instead of the
188 "\N{CHARNAME}" escape. Since the text to insert should be different in
189 "bytes" mode and out of it, the function should check the current state
190 of "bytes"-flag as in:
191 use bytes (); # for $bytes::hint_bits
193 sub translator {
194 if ($^H & $bytes::hint_bits) {
195 return bytes_translator(@_);
196 }
197 else {
198 return utf8_translator(@_);
199 }
200 }
201
203 If you ask by name for a character that does not exist, a warning is
204 given and the Unicode replacement character "\x{FFFD}" is returned.
205 If you ask by code for a character that does not exist, no warning is
207 given and "undef" is returned. (Though if you ask for a code point
208 past U+10FFFF you do get a warning.)
209
211 Unicode standard named sequences are not recognized, such as "LATIN
212 CAPITAL LETTER A WITH MACRON AND GRAVE" (which should mean "LATIN
213 CAPITAL LETTER A WITH MACRON" with an additional "COMBINING GRAVE
214 ACCENT").
215 Since evaluation of the translation function happens in a middle of
217 compilation (of a string literal), the translation function should not
218 do any "eval"s or "require"s. This restriction should be lifted in a
219 future version of Perl.
220perl v5.10.1 2009-07-03 charnames(3pm)