lib/_charnames.pm

   1 # !!!!!!!   INTERNAL PERL USE ONLY   !!!!!!!
   2 # This helper module is for internal use by core Perl only.  This module is
   3 # subject to change or removal at any time without notice.  Don't use it
   4 # directly.  Use the public <charnames> module instead.
   5
   6 package _charnames;
   7 use strict;
   8 use warnings;
   9 our $VERSION = '1.48';
  10 use unicore::Name;    # mktables-generated algorithmically-defined names
  11
  12 use bytes ();          # for $bytes::hint_bits
  13 use re "/aa";          # Everything in here should be ASCII
  14
  15 $Carp::Internal{ (__PACKAGE__) } = 1;
  16
  17 # Translate between Unicode character names and their code points.  This is a
  18 # submodule of package <charnames>, used to allow \N{...} to be autoloaded,
  19 # but it was decided not to autoload the various functions in charnames; the
  20 # splitting allows this behavior.
  21 #
  22 # The official names with their code points are stored in a table in
  23 # lib/unicore/Name.pl which is read in as a large string (almost 3/4 Mb in
  24 # Unicode 6.0).  Each code point sequence appears on a line by itself, with
  25 # its corresponding name occupying the next line in the string.  (Some of the
  26 # CJK and the Hangul syllable names are instead determined algorithmically via
  27 # subroutines stored instead in lib/unicore/Name.pm).  Because of the large
  28 # size of this table, it isn't converted into hashes for faster lookup.
  29 #
  30 # But, user defined aliases are stored in their own hashes, as are Perl
  31 # extensions to the official names.  These are checked first before looking at
  32 # the official table.
  33 #
  34 # Basically, the table is grepped for the input code point (viacode()) or
  35 # name (the other functions), and the corresponding value on the next or
  36 # previous line is returned.  The grepping is done by turning the input into a
  37 # regular expression.  Thus, the same table does double duty, used by both
  38 # name and code point lookup.  (If we were to have hashes, we would need two,
  39 # one for each lookup direction.)
  40 #
  41 # For loose name matching, the logical thing would be to have a table
  42 # with all the ignorable characters squeezed out, and then grep it with the
  43 # similiarly-squeezed input name.  (And this is in fact how the lookups are
  44 # done with the small Perl extension hashes.)  But since we need to be able to
  45 # go from code point to official name, the original table would still need to
  46 # exist.  Due to the large size of the table, it was decided to not read
  47 # another very large string into memory for a second table.  Instead, the
  48 # regular expression of the input name is modified to have optional spaces and
  49 # dashes between characters.  For example, in strict matching, the regular
  50 # expression would be:
  51 #   qr/^DIGIT ONE$/m
  52 # Under loose matching, the blank would be squeezed out, and the re would be:
  53 #   qr/^D[- ]?I[- ]?G[- ]?I[- ]?T[- ]?O[- ]?N[- ]?E$/m
  54 # which matches a blank or dash between any characters in the official table.
  55 #
  56 # This is also how script lookup is done.  Basically the re looks like
  57 #   qr/ (?:LATIN|GREEK|CYRILLIC) (?:SMALL )?LETTER $name/
  58 # where $name is the loose or strict regex for the remainder of the name.
  59
  60 # The hashes are stored as utf8 strings.  This makes it easier to deal with
  61 # sequences.  I (khw) also tried making Name.pl utf8, but it slowed things
  62 # down by a factor of 7.  I then tried making Name.pl store the utf8
  63 # equivalents but not calling them utf8.  That led to similar speed as leaving
  64 # it alone, but since that is harder for a human to parse, I left it as-is.
  65
  66 my %system_aliases = (
  67
  68     'SINGLE-SHIFT 2'                => chr utf8::unicode_to_native(0x8E),
  69     'SINGLE-SHIFT 3'                => chr utf8::unicode_to_native(0x8F),
  70     'PRIVATE USE 1'                 => chr utf8::unicode_to_native(0x91),
  71     'PRIVATE USE 2'                 => chr utf8::unicode_to_native(0x92),
  72 );
  73
  74 # These are the aliases above that differ under :loose and :full matching
  75 # because the :full versions have blanks or hyphens in them.
  76 #my %loose_system_aliases = (
  77 #);
  78
  79 #my %deprecated_aliases;
  80 #$deprecated_aliases{'BELL'} = chr utf8::unicode_to_native(0x07) if $^V lt v5.17.0;
  81
  82 #my %loose_deprecated_aliases = (
  83 #);
  84
  85 # These are special cased in :loose matching, differing only in a medial
  86 # hyphen
  87 my $HANGUL_JUNGSEONG_O_E_utf8 = chr 0x1180;
  88 my $HANGUL_JUNGSEONG_OE_utf8 = chr 0x116C;
  89
  90
  91 my $txt;  # The table of official character names
  92
  93 my %full_names_cache; # Holds already-looked-up names, so don't have to
  94 # re-look them up again.  The previous versions of charnames had scoping
  95 # bugs.  For example if we use script A in one scope and find and cache
  96 # what Z resolves to, we can't use that cache in a different scope that
  97 # uses script B instead of A, as Z might be an entirely different letter
  98 # there; or there might be different aliases in effect in different
  99 # scopes, or :short may be in effect or not effect in different scopes,
 100 # or various combinations thereof.  This was solved in this version
 101 # mostly by moving things to %^H.  But some things couldn't be moved
 102 # there.  One of them was the cache of runtime looked-up names, in part
 103 # because %^H is read-only at runtime.  I (khw) don't know why the cache
 104 # was run-time only in the previous versions: perhaps oversight; perhaps
 105 # that compile time looking doesn't happen in a loop so didn't think it
 106 # was worthwhile; perhaps not wanting to make the cache too large.  But
 107 # I decided to make it compile time as well; this could easily be
 108 # changed.
 109 # Anyway, this hash is not scoped, and is added to at runtime.  It
 110 # doesn't have scoping problems because the data in it is restricted to
 111 # official names, which are always invariant, and we only set it and
 112 # look at it at during :full lookups, so is unaffected by any other
 113 # scoped options.  I put this in to maintain parity with the older
 114 # version.  If desired, a %short_names cache could also be made, as well
 115 # as one for each script, say in %script_names_cache, with each key
 116 # being a hash for a script named in a 'use charnames' statement.  I
 117 # decided not to do that for now, just because it's added complication,
 118 # and because I'm just trying to maintain parity, not extend it.
 119
 120 # Like %full_names_cache, but for use when :loose is in effect.  There needs
 121 # to be two caches because :loose may not be in effect for a scope, and a
 122 # loose name could inappropriately be returned when only exact matching is
 123 # called for.
 124 my %loose_names_cache;
 125
 126 # Designed so that test decimal first, and then hex.  Leading zeros
 127 # imply non-decimal, as do non-[0-9]
 128 my $decimal_qr = qr/^[1-9]\d*$/;
 129
 130 # Returns the hex number in $1.
 131 my $hex_qr = qr/^(?:[Uu]\+|0[xX])?([[:xdigit:]]+)$/;
 132
 133 sub croak
 134 {
 135   require Carp; goto &Carp::croak;
 136 } # croak
 137
 138 sub carp
 139 {
 140   require Carp; goto &Carp::carp;
 141 } # carp
 142
 143 sub populate_txt()
 144 {
 145   return if $txt;
 146
 147   $txt = do "unicore/Name.pl";
 148   Internals::SvREADONLY($txt, 1);
 149 }
 150
 151 sub alias (@) # Set up a single alias
 152 {
 153   my @errors;
 154   my $nbsp = chr utf8::unicode_to_native(0xA0);
 155
 156   my $alias = ref $_[0] ? $_[0] : { @_ };
 157   foreach my $name (sort keys %$alias) {  # Sort only because it helps having
 158                                           # deterministic output for
 159                                           # t/lib/charnames/alias
 160     my $value = $alias->{$name};
 161     next unless defined $value;          # Omit if screwed up.
 162
 163     # Is slightly slower to just after this statement see if it is
 164     # decimal, since we already know it is after having converted from
 165     # hex, but makes the code easier to maintain, and is called
 166     # infrequently, only at compile-time
 167     if ($value !~ $decimal_qr && $value =~ $hex_qr) {
 168       my $temp = CORE::hex $1;
 169       $temp = utf8::unicode_to_native($temp) if $value =~ /^[Uu]\+/;
 170       $value = $temp;
 171     }
 172     if ($value =~ $decimal_qr) {
 173         no warnings qw(non_unicode surrogate nonchar); # Allow any of these
 174         $^H{charnames_ord_aliases}{$name} = chr $value;
 175
 176         # Use a canonical form.
 177         $^H{charnames_inverse_ords}{sprintf("%05X", $value)} = $name;
 178     }
 179     else {
 180         my $ok_portion = "";
 181         $ok_portion = $1 if $name =~ / ^ (
 182                                             \p{_Perl_Charname_Begin}
 183                                             \p{_Perl_Charname_Continue}*
 184                                          ) /x;
 185
 186         # If the name was fully correct, the above should have matched all of
 187         # it.
 188         if (length $ok_portion < length $name) {
 189           my $first_bad = substr($name, length($ok_portion), 1);
 190           push @errors, "Invalid character in charnames alias definition; "
 191                         . "marked by <-- HERE in '$ok_portion$first_bad<-- HERE "
 192                         . substr($name, length($ok_portion) + 1)
 193                         . "'";
 194         }
 195         else {
 196             if ($name =~ / ( .* \s ) ( \s* ) $ /x) {
 197               push @errors, "charnames alias definitions may not contain "
 198                             . "trailing white-space; marked by <-- HERE in "
 199                             . "'$1 <-- HERE " . $2 . "'";
 200               next;
 201             }
 202
 203             # Use '+' instead of '*' in this regex, because any trailing
 204             # blanks have already been found
 205             if ($name =~ / ( .*? \s{2} ) ( .+ ) /x) {
 206               push @errors, "charnames alias definitions may not contain a "
 207                             . "sequence of multiple spaces; marked by <-- HERE "
 208                             . "in '$1 <-- HERE " . $2 . "'";
 209               next;
 210             }
 211
 212             $^H{charnames_name_aliases}{$name} = $value;
 213         }
 214     }
 215   }
 216
 217   # We find and output all errors from this :alias definition, rather than
 218   # failing on the first one, so fewer runs are needed to get it to compile
 219   if (@errors) {
 220     croak join "\n", @errors;
 221   }
 222
 223   return;
 224 } # alias
 225
 226 sub not_legal_use_bytes_msg {
 227   my ($name, $utf8) = @_;
 228   my $return;
 229
 230   if (length($utf8) == 1) {
 231     $return = sprintf("Character 0x%04x with name '%s' is", ord $utf8, $name);
 232   } else {
 233     $return = sprintf("String with name '%s' (and ordinals %s) contains character(s)", $name, join(" ", map { sprintf "0x%04X", ord $_ } split(//, $utf8)));
 234   }
 235   return $return . " above 0xFF with 'use bytes' in effect";
 236 }
 237
 238 sub alias_file ($)  # Reads a file containing alias definitions
 239 {
 240   require File::Spec;
 241   my ($arg, $file) = @_;
 242   if (-f $arg && File::Spec->file_name_is_absolute ($arg)) {
 243     $file = $arg;
 244   }
 245   elsif ($arg =~ m/ ^ \p{_Perl_IDStart} \p{_Perl_IDCont}* $/x) {
 246     $file = "unicore/${arg}_alias.pl";
 247   }
 248   else {
 249     croak "Charnames alias file names can only have identifier characters";
 250   }
 251   if (my @alias = do $file) {
 252     @alias == 1 && !defined $alias[0] and
 253       croak "$file cannot be used as alias file for charnames";
 254     @alias % 2 and
 255       croak "$file did not return a (valid) list of alias pairs";
 256     alias (@alias);
 257     return (1);
 258   }
 259   0;
 260 } # alias_file
 261
 262 # For use when don't import anything.  This structure must be kept in
 263 # sync with the one that import() fills up.
 264 my %dummy_H = (
 265                 charnames_stringified_names => "",
 266                 charnames_stringified_ords => "",
 267                 charnames_scripts => "",
 268                 charnames_full => 1,
 269                 charnames_loose => 0,
 270                 charnames_short => 0,
 271               );
 272
 273
 274 sub lookup_name ($$$;$) {
 275   my ($name, $wants_ord, $runtime, $regex_loose) = @_;
 276   $regex_loose //= 0;
 277
 278   # Lookup the name or sequence $name in the tables.  If $wants_ord is false,
 279   # returns the string equivalent of $name; if true, returns the ordinal value
 280   # instead, but in this case $name must not be a sequence; otherwise undef is
 281   # returned and a warning raised.  $runtime is 0 if compiletime, otherwise
 282   # gives the number of stack frames to go back to get the application caller
 283   # info.
 284   # If $name is not found, returns undef in runtime with no warning; and in
 285   # compiletime, the Unicode replacement character, with a warning.
 286
 287   # It looks first in the aliases, then in the large table of official Unicode
 288   # names.
 289
 290   my $result;       # The string result
 291   my $save_input;
 292
 293   if ($runtime && ! $regex_loose) {
 294
 295     my $hints_ref = (caller($runtime))[10];
 296
 297     # If we didn't import anything (which happens with 'use charnames ()',
 298     # substitute a dummy structure.
 299     $hints_ref = \%dummy_H if ! defined $hints_ref
 300                               || (! defined $hints_ref->{charnames_full}
 301                                   && ! defined $hints_ref->{charnames_loose});
 302
 303     # At runtime, but currently not at compile time, %^H gets
 304     # stringified, so un-stringify back to the original data structures.
 305     # These get thrown away by perl before the next invocation
 306     # Also fill in the hash with the non-stringified data.
 307     # N.B.  New fields must be also added to %dummy_H
 308
 309     %{$^H{charnames_name_aliases}} = split ',',
 310                                       $hints_ref->{charnames_stringified_names};
 311     %{$^H{charnames_ord_aliases}} = split ',',
 312                                       $hints_ref->{charnames_stringified_ords};
 313     $^H{charnames_scripts} = $hints_ref->{charnames_scripts};
 314     $^H{charnames_full} = $hints_ref->{charnames_full};
 315     $^H{charnames_loose} = $hints_ref->{charnames_loose};
 316     $^H{charnames_short} = $hints_ref->{charnames_short};
 317   }
 318
 319   my $loose = $regex_loose || $^H{charnames_loose};
 320   my $lookup_name;  # Input name suitably modified for grepping for in the
 321                     # table
 322
 323   # User alias should be checked first or else can't override ours, and if we
 324   # were to add any, could conflict with theirs.
 325   if (! $regex_loose && exists $^H{charnames_ord_aliases}{$name}) {
 326     $result = $^H{charnames_ord_aliases}{$name};
 327   }
 328   elsif (! $regex_loose && exists $^H{charnames_name_aliases}{$name}) {
 329     $name = $^H{charnames_name_aliases}{$name};
 330     $save_input = $lookup_name = $name;  # Cache the result for any error
 331                                          # message
 332     # The aliases are documented to not match loosely, so change loose match
 333     # into full.
 334     if ($loose) {
 335       $loose = 0;
 336       $^H{charnames_full} = 1;
 337     }
 338   }
 339   else {
 340
 341     # Here, not a user alias.  That means that loose matching may be in
 342     # effect; will have to modify the input name.
 343     $lookup_name = $name;
 344     if ($loose) {
 345       $lookup_name = uc $lookup_name;
 346
 347       # Squeeze out all underscores
 348       $lookup_name =~ s/_//g;
 349
 350       # Remove all medial hyphens
 351       $lookup_name =~ s/ (?<= \S  ) - (?= \S  )//gx;
 352
 353       # Squeeze out all spaces
 354       $lookup_name =~ s/\s//g;
 355     }
 356
 357     # Here, $lookup_name has been modified as necessary for looking in the
 358     # hashes.  Check the system alias files next.  Most of these aliases are
 359     # the same for both strict and loose matching.  To save space, the ones
 360     # which differ are in their own separate hash, which is checked if loose
 361     # matching is selected and the regular match fails.  To save time, the
 362     # loose hashes could be expanded to include all aliases, and there would
 363     # only have to be one check.  But if someone specifies :loose, they are
 364     # interested in convenience over speed, and the time for this second check
 365     # is miniscule compared to the rest of the routine.
 366     if (exists $system_aliases{$lookup_name}) {
 367       $result = $system_aliases{$lookup_name};
 368     }
 369     # There are currently no entries in this hash, so don't waste time looking
 370     # for them.  But the code is retained for the unlikely possibility that
 371     # some will be added in the future.
 372 #    elsif ($loose && exists $loose_system_aliases{$lookup_name}) {
 373 #      $result = $loose_system_aliases{$lookup_name};
 374 #    }
 375 #    if (exists $deprecated_aliases{$lookup_name}) {
 376 #      require warnings;
 377 #      warnings::warnif('deprecated',
 378 #                       "Unicode character name \"$name\" is deprecated, use \""
 379 #                       . viacode(ord $deprecated_aliases{$lookup_name})
 380 #                       . "\" instead");
 381 #      $result = $deprecated_aliases{$lookup_name};
 382 #    }
 383     # There are currently no entries in this hash, so don't waste time looking
 384     # for them.  But the code is retained for the unlikely possibility that
 385     # some will be added in the future.
 386 #    elsif ($loose && exists $loose_deprecated_aliases{$lookup_name}) {
 387 #      require warnings;
 388 #      warnings::warnif('deprecated',
 389 #                       "Unicode character name \"$name\" is deprecated, use \""
 390 #                       . viacode(ord $loose_deprecated_aliases{$lookup_name})
 391 #                       . "\" instead");
 392 #      $result = $loose_deprecated_aliases{$lookup_name};
 393 #    }
 394   }
 395
 396   my @off;  # Offsets into table of pattern match begin and end
 397
 398   # If haven't found it yet...
 399   if (! defined $result) {
 400
 401     # See if has looked this input up earlier.
 402     if (! $loose && $^H{charnames_full} && exists $full_names_cache{$name}) {
 403       $result = $full_names_cache{$name};
 404     }
 405     elsif ($loose && exists $loose_names_cache{$name}) {
 406       $result = $loose_names_cache{$name};
 407     }
 408     else { # Here, must do a look-up
 409
 410       # If full or loose matching succeeded, points to where to cache the
 411       # result
 412       my $cache_ref;
 413
 414       ## Suck in the code/name list as a big string.
 415       ## Entries look like:
 416       ##     "00052\nLATIN CAPITAL LETTER R\n\n"
 417       # or
 418       #      "0052 0303\nLATIN CAPITAL LETTER R WITH TILDE\n\n"
 419       populate_txt() unless $txt;
 420
 421       ## @off will hold the index into the code/name string of the start and
 422       ## end of the name as we find it.
 423
 424       ## If :loose, look for a loose match; if :full, look for the name
 425       ## exactly
 426       # First, see if the name is one which is algorithmically determinable.
 427       # The subroutine is included in Name.pl.  The table contained in
 428       # $txt doesn't contain these.  Experiments show that checking
 429       # for these before checking for the regular names has no
 430       # noticeable impact on performance for the regular names, but
 431       # the other way around slows down finding these immensely.
 432       # Algorithmically determinables are not placed in the cache because
 433       # that uses up memory, and finding these again is fast.
 434       if (   ($loose || $^H{charnames_full})
 435           && (defined (my $ord = charnames::name_to_code_point_special($lookup_name, $loose))))
 436       {
 437         $result = chr $ord;
 438       }
 439       else {
 440
 441         # Not algorithmically determinable; look up in the table.  The name
 442         # will be turned into a regex, so quote any meta characters.
 443         $lookup_name = quotemeta $lookup_name;
 444
 445         if ($loose) {
 446
 447           # For loose matches, $lookup_name has already squeezed out the
 448           # non-essential characters.  We have to add in code to make the
 449           # squeezed version match the non-squeezed equivalent in the table.
 450           # The only remaining hyphens are ones that start or end a word in
 451           # the original.  They have been quoted in $lookup_name so they look
 452           # like "\-".  Change all other characters except the backslash
 453           # quotes for any metacharacters, and the final character, so that
 454           # e.g., COLON gets transformed into: /C[- ]?O[- ]?L[- ]?O[- ]?N/
 455           $lookup_name =~ s/ (?! \\ -)    # Don't do this to the \- sequence
 456                              ( [^-\\] )   # Nor the "-" within that sequence,
 457                                           # nor the "\" that quotes metachars,
 458                                           # but otherwise put the char into $1
 459                              (?=.)        # And don't do it for the final char
 460                            /$1\[- \]?/gx; # And add an optional blank or
 461                                           # '-' after each $1 char
 462
 463           # Those remaining hyphens were originally at the beginning or end of
 464           # a word, so they can match either a blank before or after, but not
 465           # both.  (Keep in mind that they have been quoted, so are a '\-'
 466           # sequence)
 467           $lookup_name =~ s/\\ -/(?:- | -)/xg;
 468         }
 469
 470         # Do the lookup in the full table if asked for, and if succeeds
 471         # save the offsets and set where to cache the result.
 472         if (($loose || $^H{charnames_full}) && $txt =~ /^$lookup_name$/m) {
 473           @off = ($-[0], $+[0]);
 474           $cache_ref = ($loose) ? \%loose_names_cache : \%full_names_cache;
 475         }
 476         elsif ($regex_loose) {
 477           # Currently don't allow :short when this is set
 478           return;
 479         }
 480         else {
 481
 482           # Here, didn't look for, or didn't find the name.
 483           # If :short is allowed, see if input is like "greek:Sigma".
 484           # Keep in mind that $lookup_name has had the metas quoted.
 485           my $scripts_trie = "";
 486           my $name_has_uppercase;
 487           if (($^H{charnames_short})
 488               && $lookup_name =~ /^ (?: \\ \s)*   # Quoted space
 489                                     (.+?)         # $1 = the script
 490                                     (?: \\ \s)*
 491                                     \\ :          # Quoted colon
 492                                     (?: \\ \s)*
 493                                     (.+?)         # $2 = the name
 494                                     (?: \\ \s)* $
 495                                   /xs)
 496           {
 497               # Even in non-loose matching, the script traditionally has been
 498               # case insensitive
 499               $scripts_trie = "\U$1";
 500               $lookup_name = $2;
 501
 502               # Use original name to find its input casing, but ignore the
 503               # script part of that to make the determination.
 504               $save_input = $name if ! defined $save_input;
 505               $name =~ s/.*?://;
 506               $name_has_uppercase = $name =~ /[[:upper:]]/;
 507           }
 508           else { # Otherwise look in allowed scripts
 509               $scripts_trie = $^H{charnames_scripts};
 510
 511               # Use original name to find its input casing
 512               $name_has_uppercase = $name =~ /[[:upper:]]/;
 513           }
 514
 515           my $case = $name_has_uppercase ? "CAPITAL" : "SMALL";
 516           return if (! $scripts_trie || $txt !~
 517              /^ (?: $scripts_trie ) \ (?:$case\ )? LETTER \ \U$lookup_name $/xm);
 518
 519           # Here have found the input name in the table.
 520           @off = ($-[0], $+[0]);
 521         }
 522
 523         # Here, the input name has been found; we haven't set up the output,
 524         # but we know where in the string
 525         # the name starts.  The string is set up so that for single characters
 526         # (and not named sequences), the name is on a line by itself, and the
 527         # previous line contains precisely 5 hex digits for its code point.
 528         # Named sequences won't have the 7th preceding character be a \n.
 529         # (Actually, for the very first entry in the table this isn't strictly
 530         # true: subtracting 7 will yield -1, and the substr below will
 531         # therefore yield the very last character in the table, which should
 532         # also be a \n, so the statement works anyway.)
 533         if (substr($txt, $off[0] - 7, 1) eq "\n") {
 534           $result = chr CORE::hex substr($txt, $off[0] - 6, 5);
 535
 536           # Handle the single loose matching special case, in which two names
 537           # differ only by a single medial hyphen.  If the original had a
 538           # hyphen (or more) in the right place, then it is that one.
 539           $result = $HANGUL_JUNGSEONG_O_E_utf8
 540                   if $loose
 541                      && $result eq $HANGUL_JUNGSEONG_OE_utf8
 542                      && $name =~ m/O \s* - [-\s]* E/ix;
 543                      # Note that this wouldn't work if there were a 2nd
 544                      # OE in the name
 545         }
 546         else {
 547
 548           # Here, is a named sequence.  Need to go looking for the beginning,
 549           # which is just after the \n from the previous entry in the table.
 550           # The +1 skips past that newline, or, if the rindex() fails, to put
 551           # us to an offset of zero.
 552           my $charstart = rindex($txt, "\n", $off[0] - 7) + 1;
 553           $result = pack("W*", map { CORE::hex }
 554               split " ", substr($txt, $charstart, $off[0] - $charstart - 1));
 555         }
 556       }
 557
 558       # Cache the input so as to not have to search the large table
 559       # again, but only if it came from the one search that we cache.
 560       # (Haven't bothered with the pain of sorting out scoping issues for the
 561       # scripts searches.)
 562       $cache_ref->{$name} = $result if defined $cache_ref;
 563     }
 564   }
 565
 566   # Here, have the result character.  If the return is to be an ord, must be
 567   # any single character.
 568   if ($wants_ord) {
 569     return ord($result) if length $result == 1;
 570   }
 571   elsif (! utf8::is_utf8($result)) {
 572
 573     # Here isn't UTF-8.  That's OK if it is all ASCII, or we are being called
 574     # at compile time where we know we can guarantee that Unicode rules are
 575     # correctly imposed on the result, or under 'bytes' where we don't want
 576     # those rules.  But otherwise we have to make it UTF8 to guarantee Unicode
 577     # rules on the returned string.
 578     return $result if ! $runtime
 579                       || (caller $runtime)[8] & $bytes::hint_bits
 580                       || $result !~ /[[:^ascii:]]/;
 581     utf8::upgrade($result);
 582     return $result;
 583   }
 584   else {
 585
 586     # Here, wants string output.  If utf8 is acceptable, just return what
 587     # we've got; otherwise attempt to convert it to non-utf8 and return that.
 588     my $in_bytes =     ! $regex_loose   # \p{name=} doesn't currently care if
 589                                         # in bytes or not
 590                    && (($runtime)
 591                        ? (caller $runtime)[8] & $bytes::hint_bits
 592                        : $^H & $bytes::hint_bits);
 593     return $result if (! $in_bytes || utf8::downgrade($result, 1)) # The 1 arg
 594                                                   # means don't die on failure
 595   }
 596
 597   # Here, there is an error:  either there are too many characters, or the
 598   # result string needs to be non-utf8, and at least one character requires
 599   # utf8.  Prefer any official name over the input one for the error message.
 600   if (@off) {
 601     $name = substr($txt, $off[0], $off[1] - $off[0]) if @off;
 602   }
 603   else {
 604     $name = (defined $save_input) ? $save_input : $_[0];
 605   }
 606
 607   if ($wants_ord) {
 608     # Only way to get here in this case is if result too long.  Message
 609     # assumes that our only caller that requires single char result is
 610     # vianame.
 611     carp "charnames::vianame() doesn't handle named sequences ($name).  Use charnames::string_vianame() instead";
 612     return;
 613   }
 614
 615   # Only other possible failure here is from use bytes.
 616   if ($runtime) {
 617     carp not_legal_use_bytes_msg($name, $result);
 618     return;
 619   } else {
 620     croak not_legal_use_bytes_msg($name, $result);
 621   }
 622
 623 } # lookup_name
 624
 625 sub charnames {
 626
 627   # For \N{...}.  Looks up the character name and returns the string
 628   # representation of it.
 629
 630   # The first 0 arg means wants a string returned; the second that we are in
 631   # compile time
 632   return lookup_name($_[0], 0, 0);
 633 }
 634
 635 sub _loose_regcomp_lookup {
 636   # For use only by regcomp.c to compile \p{name=...}
 637   # khw thinks it best to not do :short matching, and only official names.
 638   # But that is only a guess, and if demand warrants, could be changed
 639   return lookup_name($_[0], 0, 1,
 640                      1  # Always use :loose matching
 641                     );
 642 }
 643
 644 sub _get_names_info {
 645   # For use only by regcomp.c to compile \p{name=/.../}
 646   populate_txt() unless $txt;
 647
 648
 649   return ( \$txt, \@charnames::code_points_ending_in_code_point );
 650 }
 651
 652 sub import
 653 {
 654   shift; ## ignore class name
 655
 656   if (not @_) {
 657     carp("'use charnames' needs explicit imports list");
 658   }
 659   $^H{charnames} = \&charnames ;
 660   $^H{charnames_ord_aliases} = {};
 661   $^H{charnames_name_aliases} = {};
 662   $^H{charnames_inverse_ords} = {};
 663   # New fields must be added to %dummy_H, and the code in lookup_name()
 664   # that copies fields from the runtime structure
 665
 666   ##
 667   ## fill %h keys with our @_ args.
 668   ##
 669   my ($promote, %h, @args) = (0);
 670   while (my $arg = shift) {
 671     if ($arg eq ":alias") {
 672       @_ or
 673         croak ":alias needs an argument in charnames";
 674       my $alias = shift;
 675       if (ref $alias) {
 676         ref $alias eq "HASH" or
 677           croak "Only HASH reference supported as argument to :alias";
 678         alias ($alias);
 679         $promote = 1;
 680         next;
 681       }
 682       if ($alias =~ m{:(\w+)$}) {
 683         $1 eq "full" || $1 eq "loose" || $1 eq "short" and
 684           croak ":alias cannot use existing pragma :$1 (reversed order?)";
 685         alias_file ($1) and $promote = 1;
 686         next;
 687       }
 688       alias_file ($alias) and $promote = 1;
 689       next;
 690     }
 691     if (substr($arg, 0, 1) eq ':'
 692       and ! ($arg eq ":full" || $arg eq ":short" || $arg eq ":loose"))
 693     {
 694       warn "unsupported special '$arg' in charnames";
 695       next;
 696     }
 697     push @args, $arg;
 698   }
 699
 700   @args == 0 && $promote and @args = (":full");
 701   @h{@args} = (1) x @args;
 702
 703   # Don't leave these undefined as are tested for in lookup_names
 704   $^H{charnames_full} = delete $h{':full'} || 0;
 705   $^H{charnames_loose} = delete $h{':loose'} || 0;
 706   $^H{charnames_short} = delete $h{':short'} || 0;
 707   my @scripts = map { uc quotemeta } keys %h;
 708
 709   ##
 710   ## If utf8? warnings are enabled, and some scripts were given,
 711   ## see if at least we can find one letter from each script.
 712   ##
 713   if (warnings::enabled('utf8') && @scripts) {
 714     populate_txt() unless $txt;
 715
 716     for my $script (@scripts) {
 717       if (not $txt =~ m/^$script (?:CAPITAL |SMALL )?LETTER /m) {
 718         warnings::warn('utf8',  "No such script: '$script'");
 719         $script = quotemeta $script;  # Escape it, for use in the re.
 720       }
 721     }
 722   }
 723
 724   # %^H gets stringified, so serialize it ourselves so can extract the
 725   # real data back later.
 726   $^H{charnames_stringified_ords} = join ",", %{$^H{charnames_ord_aliases}};
 727   $^H{charnames_stringified_names} = join ",", %{$^H{charnames_name_aliases}};
 728   $^H{charnames_stringified_inverse_ords} = join ",", %{$^H{charnames_inverse_ords}};
 729
 730   # Modify the input script names for loose name matching if that is also
 731   # specified, similar to the way the base character name is prepared.  They
 732   # don't (currently, and hopefully never will) have dashes.  These go into a
 733   # regex, and have already been uppercased and quotemeta'd.  Squeeze out all
 734   # input underscores, blanks, and dashes.  Then convert so will match a blank
 735   # between any characters.
 736   if ($^H{charnames_loose}) {
 737     for (my $i = 0; $i < @scripts; $i++) {
 738       $scripts[$i] =~ s/[_ -]//g;
 739       $scripts[$i] =~ s/ ( [^\\] ) (?= . ) /$1\\ ?/gx;
 740     }
 741   }
 742
 743   $^H{charnames_scripts} = join "|", @scripts;  # Stringifiy them as a trie
 744 } # import
 745
 746 # Cache of already looked-up values.  This is set to only contain
 747 # official values, and user aliases can't override them, so scoping is
 748 # not an issue.
 749 my %viacode;
 750
 751 my $no_name_code_points_re = join "|", map { sprintf("%05X",
 752                                              utf8::unicode_to_native($_)) }
 753                                             0x80, 0x81, 0x84, 0x99;
 754 $no_name_code_points_re = qr/$no_name_code_points_re/;
 755
 756 sub viacode {
 757
 758   # Returns the name of the code point argument
 759
 760   if (@_ != 1) {
 761     carp "charnames::viacode() expects one argument";
 762     return;
 763   }
 764
 765   my $arg = shift;
 766
 767   # This is derived from Unicode::UCD, where it is nearly the same as the
 768   # function _getcode(), but here it makes sure that even a hex argument
 769   # has the proper number of leading zeros, which is critical in
 770   # matching against $txt below
 771   # Must check if decimal first; see comments at that definition
 772   my $hex;
 773   if ($arg =~ $decimal_qr) {
 774     $hex = sprintf "%05X", $arg;
 775   } elsif ($arg =~ $hex_qr) {
 776     $hex = CORE::hex $1;
 777     $hex = utf8::unicode_to_native($hex) if $arg =~ /^[Uu]\+/;
 778     # Below is the line that differs from the _getcode() source
 779     $hex = sprintf "%05X", $hex;
 780   } else {
 781     carp("unexpected arg \"$arg\" to charnames::viacode()");
 782     return;
 783   }
 784
 785   return $viacode{$hex} if exists $viacode{$hex};
 786
 787   my $return;
 788
 789   # If the code point is above the max in the table, there's no point
 790   # looking through it.  Checking the length first is slightly faster
 791   if (length($hex) <= 5 || CORE::hex($hex) <= 0x10FFFF) {
 792     populate_txt() unless $txt;
 793
 794     # See if the name is algorithmically determinable.
 795     my $algorithmic = charnames::code_point_to_name_special(CORE::hex $hex);
 796     if (defined $algorithmic) {
 797       $viacode{$hex} = $algorithmic;
 798       return $algorithmic;
 799     }
 800
 801     # Return the official name, if exists.  It's unclear to me (khw) at
 802     # this juncture if it is better to return a user-defined override, so
 803     # leaving it as is for now.
 804     if ($txt =~ m/^$hex\n/m) {
 805
 806         # The name starts with the next character and goes up to the
 807         # next new-line.  Using capturing parentheses above instead of
 808         # @+ more than doubles the execution time in Perl 5.13
 809         $return = substr($txt, $+[0], index($txt, "\n", $+[0]) - $+[0]);
 810
 811         # If not one of these 4 code points, return what we've found.
 812         if ($hex !~ / ^ $no_name_code_points_re $ /x) {
 813           $viacode{$hex} = $return;
 814           return $return;
 815         }
 816
 817         # For backwards compatibility, we don't return the official name of
 818         # the 4 code points if there are user-defined aliases for them -- so
 819         # continue looking.
 820     }
 821   }
 822
 823   # See if there is a user name for it, before giving up completely.
 824   # First get the scoped aliases, give up if have none.
 825   my $H_ref = (caller(1))[10];
 826   return if ! defined $return
 827               && (! defined $H_ref
 828                   || ! exists $H_ref->{charnames_stringified_inverse_ords});
 829
 830   my %code_point_aliases;
 831   if (defined $H_ref->{charnames_stringified_inverse_ords}) {
 832     %code_point_aliases = split ',',
 833                           $H_ref->{charnames_stringified_inverse_ords};
 834     return $code_point_aliases{$hex} if exists $code_point_aliases{$hex};
 835   }
 836
 837   # Here there is no user-defined alias, return any official one.
 838   return $return if defined $return;
 839
 840   if (CORE::hex($hex) > 0x10FFFF
 841       && warnings::enabled('non_unicode'))
 842   {
 843       carp "Unicode characters only allocated up to U+10FFFF (you asked for U+$hex)";
 844   }
 845   return;
 846
 847 } # viacode
 848
 849 1;
 850
 851 # ex: set ts=8 sts=2 sw=2 et: