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