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