This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
charnames pod: slight rewording
[perl5.git] / lib / charnames.pm
CommitLineData
423cee85 1package charnames;
b177ca84
JF
2use strict;
3use warnings;
228e8c7b 4our $VERSION = '1.30';
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
7620cb10
KW
214Since Unicode 6.0, it is deprecated to use C<BELL>. Instead use C<ALERT> (but
215C<BEL> will continue to work).
301a3cda 216
e5432b89
KW
217If the input name is unknown, C<\N{NAME}> raises a warning and
218substitutes the Unicode REPLACEMENT CHARACTER (U+FFFD).
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
251spellings, and probably only when those look-ups are through vianame() and
252string_vianame(), since C<\N{...}> look-ups are done at compile time.
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
KW
272
273Note that an alias should not be something that is a legal curly
274brace-enclosed quantifier (see L<perlreref/QUANTIFIERS>). For example
e5432b89
KW
275C<\N{123}> means to match 123 non-newline characters, and is not treated as a
276charnames alias. Aliases are discouraged from beginning with anything
277other than an alphabetic character and from containing anything other
278than alphanumerics, spaces, dashes, parentheses, and underscores.
279Currently they must be ASCII.
280
38f4139d
KW
281An alias can map to either an official Unicode character name (not a loose
282matched name) or to a
e5432b89
KW
283numeric code point (ordinal). The latter is useful for assigning names
284to code points in Unicode private use areas such as U+E800 through
f12d74c0
KW
285U+F8FF.
286A numeric code point must be a non-negative integer or a string beginning
287with C<"U+"> or C<"0x"> with the remainder considered to be a
288hexadecimal integer. A literal numeric constant must be unsigned; it
289will be interpreted as hex if it has a leading zero or contains
290non-decimal hex digits; otherwise it will be interpreted as decimal.
232cbbee 291
da9dec57 292Aliases are added either by the use of anonymous hashes:
35c0985d 293
da9dec57 294 use charnames ":alias" => {
35c0985d 295 e_ACUTE => "LATIN SMALL LETTER E WITH ACUTE",
232cbbee 296 mychar1 => 0xE8000,
35c0985d
MB
297 };
298 my $str = "\N{e_ACUTE}";
299
da9dec57 300or by using a file containing aliases:
35c0985d 301
da9dec57 302 use charnames ":alias" => "pro";
35c0985d 303
8ebef31d 304This will try to read C<"unicore/pro_alias.pl"> from the C<@INC> path. This
da9dec57 305file should return a list in plain perl:
35c0985d
MB
306
307 (
308 A_GRAVE => "LATIN CAPITAL LETTER A WITH GRAVE",
309 A_CIRCUM => "LATIN CAPITAL LETTER A WITH CIRCUMFLEX",
310 A_DIAERES => "LATIN CAPITAL LETTER A WITH DIAERESIS",
311 A_TILDE => "LATIN CAPITAL LETTER A WITH TILDE",
312 A_BREVE => "LATIN CAPITAL LETTER A WITH BREVE",
313 A_RING => "LATIN CAPITAL LETTER A WITH RING ABOVE",
314 A_MACRON => "LATIN CAPITAL LETTER A WITH MACRON",
f12d74c0 315 mychar2 => "U+E8001",
35c0985d
MB
316 );
317
da9dec57
KW
318Both these methods insert C<":full"> automatically as the first argument (if no
319other argument is given), and you can give the C<":full"> explicitly as
320well, like
35c0985d 321
da9dec57 322 use charnames ":full", ":alias" => "pro";
35c0985d 323
38f4139d
KW
324C<":loose"> has no effect with these. Input names must match exactly, using
325C<":full"> rules.
326
14aeae98 327Also, both these methods currently allow only single characters to be named.
8ebef31d
KW
328To name a sequence of characters, use a
329L<custom translator|/CUSTOM TRANSLATORS> (described below).
330
228e8c7b
KW
331=head1 charnames::string_vianame(I<name>)
332
333This is a runtime equivalent to C<\N{...}>. I<name> can be any expression
334that evaluates to a name accepted by C<\N{...}> under the L<C<:full>
335option|/DESCRIPTION> to C<charnames>. In addition, any other options for the
336controlling C<"use charnames"> in the same scope apply, like C<:loose> or any
337L<script list, C<:short> option|/DESCRIPTION>, or L<custom aliases|/CUSTOM
338ALIASES> you may have defined.
339
340The only difference is that if the input name is unknown, C<string_vianame>
341returns C<undef> instead of the REPLACEMENT CHARACTER and does not raise a
342warning message.
343
344=head1 charnames::vianame(I<name>)
345
346This is similar to C<string_vianame>. The main difference is that under most
347circumstances, vianame returns an ordinal code
348point, whereas C<string_vianame> returns a string. For example,
349
350 printf "U+%04X", charnames::vianame("FOUR TEARDROP-SPOKED ASTERISK");
351
352prints "U+2722".
353
354This leads to the other two differences. Since a single code point is
355returned, the function can't handle named character sequences, as these are
356composed of multiple characters (it returns C<undef> for these. And, the code
357point can be that of any
358character, even ones that aren't legal under the C<S<use bytes>> pragma,
359
360See L</BUGS> for the circumstances in which the behavior differs
361from that described above.
362
da9dec57 363=head1 charnames::viacode(I<code>)
b177ca84
JF
364
365Returns the full name of the character indicated by the numeric code.
da9dec57 366For example,
b177ca84
JF
367
368 print charnames::viacode(0x2722);
369
370prints "FOUR TEARDROP-SPOKED ASTERISK".
371
232cbbee 372The name returned is the official name for the code point, if
ffec6758
KW
373available; otherwise your custom alias for it, if defined; otherwise C<undef>.
374This means that your alias will only be returned for code points that don't
375have an official Unicode name (nor alias) such as private use code points.
7620cb10
KW
376Until Unicode 6.1, the 4 control characters U+0080, U+0081, U+0084, and U+0099
377did not have names (actually, to be precise they still don't, but they do have
378aliases, which for most purposes are indistiunguishable from true names).
379To preserve backwards compatibility, any alias you define for these code
380points will be returned by this function, in preference to the official alias.
381
da9dec57
KW
382If you define more than one name for the code point, it is indeterminate
383which one will be returned.
384
ffec6758
KW
385As mentioned, the function returns C<undef> if no name is known for the code
386point. In Unicode the proper name of these is the empty string, which
da9dec57
KW
387C<undef> stringifies to. (If you ask for a code point past the legal
388Unicode maximum of U+10FFFF that you haven't assigned an alias to, you
f12d74c0
KW
389get C<undef> plus a warning.)
390
1f3b4888 391The input number must be a non-negative integer, or a string beginning
f12d74c0
KW
392with C<"U+"> or C<"0x"> with the remainder considered to be a
393hexadecimal integer. A literal numeric constant must be unsigned; it
394will be interpreted as hex if it has a leading zero or contains
395non-decimal hex digits; otherwise it will be interpreted as decimal.
daf0d493 396
d9f23c72 397Notice that the name returned for U+FEFF is "ZERO WIDTH NO-BREAK
274085e3
PN
398SPACE", not "BYTE ORDER MARK".
399
5ffe0e96 400=head1 CUSTOM TRANSLATORS
52ea3e69 401
5ffe0e96 402The mechanism of translation of C<\N{...}> escapes is general and not
5ef88e32 403hardwired into F<charnames.pm>. A module can install custom
5ffe0e96
MB
404translations (inside the scope which C<use>s the module) with the
405following magic incantation:
52ea3e69 406
5ffe0e96 407 sub import {
52fb7278
KW
408 shift;
409 $^H{charnames} = \&translator;
5ffe0e96 410 }
52ea3e69 411
da9dec57 412Here translator() is a subroutine which takes I<CHARNAME> as an
5ffe0e96 413argument, and returns text to insert into the string instead of the
5ef88e32
KW
414C<\N{I<CHARNAME>}> escape.
415
416This is the only way you can create a custom named sequence of code points.
417
418Since the text to insert should be different
5ffe0e96
MB
419in C<bytes> mode and out of it, the function should check the current
420state of C<bytes>-flag as in:
52ea3e69 421
52fb7278 422 use bytes (); # for $bytes::hint_bits
5ffe0e96 423 sub translator {
52fb7278
KW
424 if ($^H & $bytes::hint_bits) {
425 return bytes_translator(@_);
426 }
427 else {
428 return utf8_translator(@_);
429 }
5ffe0e96 430 }
52ea3e69 431
da9dec57 432See L</CUSTOM ALIASES> above for restrictions on I<CHARNAME>.
f0175764 433
9e808deb
KW
434Of course, C<vianame>, C<viacode>, and C<string_vianame> would need to be
435overridden as well.
1f31fcd4 436
423cee85
JH
437=head1 BUGS
438
14aeae98 439vianame() normally returns an ordinal code point, but when the input name is of
8ebef31d
KW
440the form C<U+...>, it returns a chr instead. In this case, if C<use bytes> is
441in effect and the character won't fit into a byte, it returns C<undef> and
442raises a warning.
55bc7d3c 443
16036bcd
KW
444Names must be ASCII characters only, which means that you are out of luck if
445you want to create aliases in a language where some or all the characters of
446the desired aliases are non-ASCII.
bee80e93 447
f12d74c0
KW
448Since evaluation of the translation function (see L</CUSTOM
449TRANSLATORS>) happens in the middle of compilation (of a string
450literal), the translation function should not do any C<eval>s or
451C<require>s. This restriction should be lifted (but is low priority) in
452a future version of Perl.
423cee85
JH
453
454=cut
0eacc33e 455
52fb7278 456# ex: set ts=8 sts=2 sw=2 et: