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