lib/charnames.pm

   1 package charnames;
   2 use strict;
   3 use warnings;
   4 use File::Spec;
   5 our $VERSION = '1.14';
   6
   7 use bytes ();          # for $bytes::hint_bits
   8
   9 my %system_aliases = (
  10                 # Icky 3.2 names with parentheses.
  11                 'LINE FEED'             => 0x0A, # LINE FEED (LF)
  12                 'FORM FEED'             => 0x0C, # FORM FEED (FF)
  13                 'CARRIAGE RETURN'       => 0x0D, # CARRIAGE RETURN (CR)
  14                 'NEXT LINE'             => 0x85, # NEXT LINE (NEL)
  15
  16                 # Some variant names from Wikipedia
  17                 'SINGLE-SHIFT 2'                => 0x8E,
  18                 'SINGLE-SHIFT 3'                => 0x8F,
  19                 'PRIVATE USE 1'                 => 0x91,
  20                 'PRIVATE USE 2'                 => 0x92,
  21                 'START OF PROTECTED AREA'       => 0x96,
  22                 'END OF PROTECTED AREA'         => 0x97,
  23
  24                 # Convenience.  Standard abbreviations for the controls
  25                 'NUL'           => 0x00, # NULL
  26                 'SOH'           => 0x01, # START OF HEADING
  27                 'STX'           => 0x02, # START OF TEXT
  28                 'ETX'           => 0x03, # END OF TEXT
  29                 'EOT'           => 0x04, # END OF TRANSMISSION
  30                 'ENQ'           => 0x05, # ENQUIRY
  31                 'ACK'           => 0x06, # ACKNOWLEDGE
  32                 'BEL'           => 0x07, # BELL
  33                 'BS'            => 0x08, # BACKSPACE
  34                 'HT'            => 0x09, # HORIZONTAL TABULATION
  35                 'LF'            => 0x0A, # LINE FEED (LF)
  36                 'VT'            => 0x0B, # VERTICAL TABULATION
  37                 'FF'            => 0x0C, # FORM FEED (FF)
  38                 'CR'            => 0x0D, # CARRIAGE RETURN (CR)
  39                 'SO'            => 0x0E, # SHIFT OUT
  40                 'SI'            => 0x0F, # SHIFT IN
  41                 'DLE'           => 0x10, # DATA LINK ESCAPE
  42                 'DC1'           => 0x11, # DEVICE CONTROL ONE
  43                 'DC2'           => 0x12, # DEVICE CONTROL TWO
  44                 'DC3'           => 0x13, # DEVICE CONTROL THREE
  45                 'DC4'           => 0x14, # DEVICE CONTROL FOUR
  46                 'NAK'           => 0x15, # NEGATIVE ACKNOWLEDGE
  47                 'SYN'           => 0x16, # SYNCHRONOUS IDLE
  48                 'ETB'           => 0x17, # END OF TRANSMISSION BLOCK
  49                 'CAN'           => 0x18, # CANCEL
  50                 'EOM'           => 0x19, # END OF MEDIUM
  51                 'SUB'           => 0x1A, # SUBSTITUTE
  52                 'ESC'           => 0x1B, # ESCAPE
  53                 'FS'            => 0x1C, # FILE SEPARATOR
  54                 'GS'            => 0x1D, # GROUP SEPARATOR
  55                 'RS'            => 0x1E, # RECORD SEPARATOR
  56                 'US'            => 0x1F, # UNIT SEPARATOR
  57                 'DEL'           => 0x7F, # DELETE
  58                 'BPH'           => 0x82, # BREAK PERMITTED HERE
  59                 'NBH'           => 0x83, # NO BREAK HERE
  60                 'NEL'           => 0x85, # NEXT LINE (NEL)
  61                 'SSA'           => 0x86, # START OF SELECTED AREA
  62                 'ESA'           => 0x87, # END OF SELECTED AREA
  63                 'HTS'           => 0x88, # CHARACTER TABULATION SET
  64                 'HTJ'           => 0x89, # CHARACTER TABULATION WITH JUSTIFICATION
  65                 'VTS'           => 0x8A, # LINE TABULATION SET
  66                 'PLD'           => 0x8B, # PARTIAL LINE FORWARD
  67                 'PLU'           => 0x8C, # PARTIAL LINE BACKWARD
  68                 'RI '           => 0x8D, # REVERSE LINE FEED
  69                 'SS2'           => 0x8E, # SINGLE SHIFT TWO
  70                 'SS3'           => 0x8F, # SINGLE SHIFT THREE
  71                 'DCS'           => 0x90, # DEVICE CONTROL STRING
  72                 'PU1'           => 0x91, # PRIVATE USE ONE
  73                 'PU2'           => 0x92, # PRIVATE USE TWO
  74                 'STS'           => 0x93, # SET TRANSMIT STATE
  75                 'CCH'           => 0x94, # CANCEL CHARACTER
  76                 'MW '           => 0x95, # MESSAGE WAITING
  77                 'SPA'           => 0x96, # START OF GUARDED AREA
  78                 'EPA'           => 0x97, # END OF GUARDED AREA
  79                 'SOS'           => 0x98, # START OF STRING
  80                 'SCI'           => 0x9A, # SINGLE CHARACTER INTRODUCER
  81                 'CSI'           => 0x9B, # CONTROL SEQUENCE INTRODUCER
  82                 'ST '           => 0x9C, # STRING TERMINATOR
  83                 'OSC'           => 0x9D, # OPERATING SYSTEM COMMAND
  84                 'PM '           => 0x9E, # PRIVACY MESSAGE
  85                 'APC'           => 0x9F, # APPLICATION PROGRAM COMMAND
  86
  87                 # There are no names for these in the Unicode standard;
  88                 # perhaps should be deprecated, but then again there are
  89                 # no alternative names, so am not deprecating.  And if
  90                 # did, the code would have to change to not recommend an
  91                 # alternative for these.
  92                 'PADDING CHARACTER'                     => 0x80,
  93                 'PAD'                                   => 0x80,
  94                 'HIGH OCTET PRESET'                     => 0x81,
  95                 'HOP'                                   => 0x81,
  96                 'INDEX'                                 => 0x84,
  97                 'IND'                                   => 0x84,
  98                 'SINGLE GRAPHIC CHARACTER INTRODUCER'   => 0x99,
  99                 'SGC'                                   => 0x99,
 100
 101                 # More convenience.  For further convenience,
 102                 # it is suggested some way of using the NamesList
 103                 # aliases be implemented, but there are ambiguities in
 104                 # NamesList.txt
 105                 'BOM'   => 0xFEFF, # BYTE ORDER MARK
 106                 'BYTE ORDER MARK'=> 0xFEFF,
 107                 'CGJ'   => 0x034F, # COMBINING GRAPHEME JOINER
 108                 'FVS1'  => 0x180B, # MONGOLIAN FREE VARIATION SELECTOR ONE
 109                 'FVS2'  => 0x180C, # MONGOLIAN FREE VARIATION SELECTOR TWO
 110                 'FVS3'  => 0x180D, # MONGOLIAN FREE VARIATION SELECTOR THREE
 111                 'LRE'   => 0x202A, # LEFT-TO-RIGHT EMBEDDING
 112                 'LRM'   => 0x200E, # LEFT-TO-RIGHT MARK
 113                 'LRO'   => 0x202D, # LEFT-TO-RIGHT OVERRIDE
 114                 'MMSP'  => 0x205F, # MEDIUM MATHEMATICAL SPACE
 115                 'MVS'   => 0x180E, # MONGOLIAN VOWEL SEPARATOR
 116                 'NBSP'  => 0x00A0, # NO-BREAK SPACE
 117                 'NNBSP' => 0x202F, # NARROW NO-BREAK SPACE
 118                 'PDF'   => 0x202C, # POP DIRECTIONAL FORMATTING
 119                 'RLE'   => 0x202B, # RIGHT-TO-LEFT EMBEDDING
 120                 'RLM'   => 0x200F, # RIGHT-TO-LEFT MARK
 121                 'RLO'   => 0x202E, # RIGHT-TO-LEFT OVERRIDE
 122                 'SHY'   => 0x00AD, # SOFT HYPHEN
 123                 'VS1'   => 0xFE00, # VARIATION SELECTOR-1
 124                 'VS2'   => 0xFE01, # VARIATION SELECTOR-2
 125                 'VS3'   => 0xFE02, # VARIATION SELECTOR-3
 126                 'VS4'   => 0xFE03, # VARIATION SELECTOR-4
 127                 'VS5'   => 0xFE04, # VARIATION SELECTOR-5
 128                 'VS6'   => 0xFE05, # VARIATION SELECTOR-6
 129                 'VS7'   => 0xFE06, # VARIATION SELECTOR-7
 130                 'VS8'   => 0xFE07, # VARIATION SELECTOR-8
 131                 'VS9'   => 0xFE08, # VARIATION SELECTOR-9
 132                 'VS10'  => 0xFE09, # VARIATION SELECTOR-10
 133                 'VS11'  => 0xFE0A, # VARIATION SELECTOR-11
 134                 'VS12'  => 0xFE0B, # VARIATION SELECTOR-12
 135                 'VS13'  => 0xFE0C, # VARIATION SELECTOR-13
 136                 'VS14'  => 0xFE0D, # VARIATION SELECTOR-14
 137                 'VS15'  => 0xFE0E, # VARIATION SELECTOR-15
 138                 'VS16'  => 0xFE0F, # VARIATION SELECTOR-16
 139                 'VS17'  => 0xE0100, # VARIATION SELECTOR-17
 140                 'VS18'  => 0xE0101, # VARIATION SELECTOR-18
 141                 'VS19'  => 0xE0102, # VARIATION SELECTOR-19
 142                 'VS20'  => 0xE0103, # VARIATION SELECTOR-20
 143                 'VS21'  => 0xE0104, # VARIATION SELECTOR-21
 144                 'VS22'  => 0xE0105, # VARIATION SELECTOR-22
 145                 'VS23'  => 0xE0106, # VARIATION SELECTOR-23
 146                 'VS24'  => 0xE0107, # VARIATION SELECTOR-24
 147                 'VS25'  => 0xE0108, # VARIATION SELECTOR-25
 148                 'VS26'  => 0xE0109, # VARIATION SELECTOR-26
 149                 'VS27'  => 0xE010A, # VARIATION SELECTOR-27
 150                 'VS28'  => 0xE010B, # VARIATION SELECTOR-28
 151                 'VS29'  => 0xE010C, # VARIATION SELECTOR-29
 152                 'VS30'  => 0xE010D, # VARIATION SELECTOR-30
 153                 'VS31'  => 0xE010E, # VARIATION SELECTOR-31
 154                 'VS32'  => 0xE010F, # VARIATION SELECTOR-32
 155                 'VS33'  => 0xE0110, # VARIATION SELECTOR-33
 156                 'VS34'  => 0xE0111, # VARIATION SELECTOR-34
 157                 'VS35'  => 0xE0112, # VARIATION SELECTOR-35
 158                 'VS36'  => 0xE0113, # VARIATION SELECTOR-36
 159                 'VS37'  => 0xE0114, # VARIATION SELECTOR-37
 160                 'VS38'  => 0xE0115, # VARIATION SELECTOR-38
 161                 'VS39'  => 0xE0116, # VARIATION SELECTOR-39
 162                 'VS40'  => 0xE0117, # VARIATION SELECTOR-40
 163                 'VS41'  => 0xE0118, # VARIATION SELECTOR-41
 164                 'VS42'  => 0xE0119, # VARIATION SELECTOR-42
 165                 'VS43'  => 0xE011A, # VARIATION SELECTOR-43
 166                 'VS44'  => 0xE011B, # VARIATION SELECTOR-44
 167                 'VS45'  => 0xE011C, # VARIATION SELECTOR-45
 168                 'VS46'  => 0xE011D, # VARIATION SELECTOR-46
 169                 'VS47'  => 0xE011E, # VARIATION SELECTOR-47
 170                 'VS48'  => 0xE011F, # VARIATION SELECTOR-48
 171                 'VS49'  => 0xE0120, # VARIATION SELECTOR-49
 172                 'VS50'  => 0xE0121, # VARIATION SELECTOR-50
 173                 'VS51'  => 0xE0122, # VARIATION SELECTOR-51
 174                 'VS52'  => 0xE0123, # VARIATION SELECTOR-52
 175                 'VS53'  => 0xE0124, # VARIATION SELECTOR-53
 176                 'VS54'  => 0xE0125, # VARIATION SELECTOR-54
 177                 'VS55'  => 0xE0126, # VARIATION SELECTOR-55
 178                 'VS56'  => 0xE0127, # VARIATION SELECTOR-56
 179                 'VS57'  => 0xE0128, # VARIATION SELECTOR-57
 180                 'VS58'  => 0xE0129, # VARIATION SELECTOR-58
 181                 'VS59'  => 0xE012A, # VARIATION SELECTOR-59
 182                 'VS60'  => 0xE012B, # VARIATION SELECTOR-60
 183                 'VS61'  => 0xE012C, # VARIATION SELECTOR-61
 184                 'VS62'  => 0xE012D, # VARIATION SELECTOR-62
 185                 'VS63'  => 0xE012E, # VARIATION SELECTOR-63
 186                 'VS64'  => 0xE012F, # VARIATION SELECTOR-64
 187                 'VS65'  => 0xE0130, # VARIATION SELECTOR-65
 188                 'VS66'  => 0xE0131, # VARIATION SELECTOR-66
 189                 'VS67'  => 0xE0132, # VARIATION SELECTOR-67
 190                 'VS68'  => 0xE0133, # VARIATION SELECTOR-68
 191                 'VS69'  => 0xE0134, # VARIATION SELECTOR-69
 192                 'VS70'  => 0xE0135, # VARIATION SELECTOR-70
 193                 'VS71'  => 0xE0136, # VARIATION SELECTOR-71
 194                 'VS72'  => 0xE0137, # VARIATION SELECTOR-72
 195                 'VS73'  => 0xE0138, # VARIATION SELECTOR-73
 196                 'VS74'  => 0xE0139, # VARIATION SELECTOR-74
 197                 'VS75'  => 0xE013A, # VARIATION SELECTOR-75
 198                 'VS76'  => 0xE013B, # VARIATION SELECTOR-76
 199                 'VS77'  => 0xE013C, # VARIATION SELECTOR-77
 200                 'VS78'  => 0xE013D, # VARIATION SELECTOR-78
 201                 'VS79'  => 0xE013E, # VARIATION SELECTOR-79
 202                 'VS80'  => 0xE013F, # VARIATION SELECTOR-80
 203                 'VS81'  => 0xE0140, # VARIATION SELECTOR-81
 204                 'VS82'  => 0xE0141, # VARIATION SELECTOR-82
 205                 'VS83'  => 0xE0142, # VARIATION SELECTOR-83
 206                 'VS84'  => 0xE0143, # VARIATION SELECTOR-84
 207                 'VS85'  => 0xE0144, # VARIATION SELECTOR-85
 208                 'VS86'  => 0xE0145, # VARIATION SELECTOR-86
 209                 'VS87'  => 0xE0146, # VARIATION SELECTOR-87
 210                 'VS88'  => 0xE0147, # VARIATION SELECTOR-88
 211                 'VS89'  => 0xE0148, # VARIATION SELECTOR-89
 212                 'VS90'  => 0xE0149, # VARIATION SELECTOR-90
 213                 'VS91'  => 0xE014A, # VARIATION SELECTOR-91
 214                 'VS92'  => 0xE014B, # VARIATION SELECTOR-92
 215                 'VS93'  => 0xE014C, # VARIATION SELECTOR-93
 216                 'VS94'  => 0xE014D, # VARIATION SELECTOR-94
 217                 'VS95'  => 0xE014E, # VARIATION SELECTOR-95
 218                 'VS96'  => 0xE014F, # VARIATION SELECTOR-96
 219                 'VS97'  => 0xE0150, # VARIATION SELECTOR-97
 220                 'VS98'  => 0xE0151, # VARIATION SELECTOR-98
 221                 'VS99'  => 0xE0152, # VARIATION SELECTOR-99
 222                 'VS100' => 0xE0153, # VARIATION SELECTOR-100
 223                 'VS101' => 0xE0154, # VARIATION SELECTOR-101
 224                 'VS102' => 0xE0155, # VARIATION SELECTOR-102
 225                 'VS103' => 0xE0156, # VARIATION SELECTOR-103
 226                 'VS104' => 0xE0157, # VARIATION SELECTOR-104
 227                 'VS105' => 0xE0158, # VARIATION SELECTOR-105
 228                 'VS106' => 0xE0159, # VARIATION SELECTOR-106
 229                 'VS107' => 0xE015A, # VARIATION SELECTOR-107
 230                 'VS108' => 0xE015B, # VARIATION SELECTOR-108
 231                 'VS109' => 0xE015C, # VARIATION SELECTOR-109
 232                 'VS110' => 0xE015D, # VARIATION SELECTOR-110
 233                 'VS111' => 0xE015E, # VARIATION SELECTOR-111
 234                 'VS112' => 0xE015F, # VARIATION SELECTOR-112
 235                 'VS113' => 0xE0160, # VARIATION SELECTOR-113
 236                 'VS114' => 0xE0161, # VARIATION SELECTOR-114
 237                 'VS115' => 0xE0162, # VARIATION SELECTOR-115
 238                 'VS116' => 0xE0163, # VARIATION SELECTOR-116
 239                 'VS117' => 0xE0164, # VARIATION SELECTOR-117
 240                 'VS118' => 0xE0165, # VARIATION SELECTOR-118
 241                 'VS119' => 0xE0166, # VARIATION SELECTOR-119
 242                 'VS120' => 0xE0167, # VARIATION SELECTOR-120
 243                 'VS121' => 0xE0168, # VARIATION SELECTOR-121
 244                 'VS122' => 0xE0169, # VARIATION SELECTOR-122
 245                 'VS123' => 0xE016A, # VARIATION SELECTOR-123
 246                 'VS124' => 0xE016B, # VARIATION SELECTOR-124
 247                 'VS125' => 0xE016C, # VARIATION SELECTOR-125
 248                 'VS126' => 0xE016D, # VARIATION SELECTOR-126
 249                 'VS127' => 0xE016E, # VARIATION SELECTOR-127
 250                 'VS128' => 0xE016F, # VARIATION SELECTOR-128
 251                 'VS129' => 0xE0170, # VARIATION SELECTOR-129
 252                 'VS130' => 0xE0171, # VARIATION SELECTOR-130
 253                 'VS131' => 0xE0172, # VARIATION SELECTOR-131
 254                 'VS132' => 0xE0173, # VARIATION SELECTOR-132
 255                 'VS133' => 0xE0174, # VARIATION SELECTOR-133
 256                 'VS134' => 0xE0175, # VARIATION SELECTOR-134
 257                 'VS135' => 0xE0176, # VARIATION SELECTOR-135
 258                 'VS136' => 0xE0177, # VARIATION SELECTOR-136
 259                 'VS137' => 0xE0178, # VARIATION SELECTOR-137
 260                 'VS138' => 0xE0179, # VARIATION SELECTOR-138
 261                 'VS139' => 0xE017A, # VARIATION SELECTOR-139
 262                 'VS140' => 0xE017B, # VARIATION SELECTOR-140
 263                 'VS141' => 0xE017C, # VARIATION SELECTOR-141
 264                 'VS142' => 0xE017D, # VARIATION SELECTOR-142
 265                 'VS143' => 0xE017E, # VARIATION SELECTOR-143
 266                 'VS144' => 0xE017F, # VARIATION SELECTOR-144
 267                 'VS145' => 0xE0180, # VARIATION SELECTOR-145
 268                 'VS146' => 0xE0181, # VARIATION SELECTOR-146
 269                 'VS147' => 0xE0182, # VARIATION SELECTOR-147
 270                 'VS148' => 0xE0183, # VARIATION SELECTOR-148
 271                 'VS149' => 0xE0184, # VARIATION SELECTOR-149
 272                 'VS150' => 0xE0185, # VARIATION SELECTOR-150
 273                 'VS151' => 0xE0186, # VARIATION SELECTOR-151
 274                 'VS152' => 0xE0187, # VARIATION SELECTOR-152
 275                 'VS153' => 0xE0188, # VARIATION SELECTOR-153
 276                 'VS154' => 0xE0189, # VARIATION SELECTOR-154
 277                 'VS155' => 0xE018A, # VARIATION SELECTOR-155
 278                 'VS156' => 0xE018B, # VARIATION SELECTOR-156
 279                 'VS157' => 0xE018C, # VARIATION SELECTOR-157
 280                 'VS158' => 0xE018D, # VARIATION SELECTOR-158
 281                 'VS159' => 0xE018E, # VARIATION SELECTOR-159
 282                 'VS160' => 0xE018F, # VARIATION SELECTOR-160
 283                 'VS161' => 0xE0190, # VARIATION SELECTOR-161
 284                 'VS162' => 0xE0191, # VARIATION SELECTOR-162
 285                 'VS163' => 0xE0192, # VARIATION SELECTOR-163
 286                 'VS164' => 0xE0193, # VARIATION SELECTOR-164
 287                 'VS165' => 0xE0194, # VARIATION SELECTOR-165
 288                 'VS166' => 0xE0195, # VARIATION SELECTOR-166
 289                 'VS167' => 0xE0196, # VARIATION SELECTOR-167
 290                 'VS168' => 0xE0197, # VARIATION SELECTOR-168
 291                 'VS169' => 0xE0198, # VARIATION SELECTOR-169
 292                 'VS170' => 0xE0199, # VARIATION SELECTOR-170
 293                 'VS171' => 0xE019A, # VARIATION SELECTOR-171
 294                 'VS172' => 0xE019B, # VARIATION SELECTOR-172
 295                 'VS173' => 0xE019C, # VARIATION SELECTOR-173
 296                 'VS174' => 0xE019D, # VARIATION SELECTOR-174
 297                 'VS175' => 0xE019E, # VARIATION SELECTOR-175
 298                 'VS176' => 0xE019F, # VARIATION SELECTOR-176
 299                 'VS177' => 0xE01A0, # VARIATION SELECTOR-177
 300                 'VS178' => 0xE01A1, # VARIATION SELECTOR-178
 301                 'VS179' => 0xE01A2, # VARIATION SELECTOR-179
 302                 'VS180' => 0xE01A3, # VARIATION SELECTOR-180
 303                 'VS181' => 0xE01A4, # VARIATION SELECTOR-181
 304                 'VS182' => 0xE01A5, # VARIATION SELECTOR-182
 305                 'VS183' => 0xE01A6, # VARIATION SELECTOR-183
 306                 'VS184' => 0xE01A7, # VARIATION SELECTOR-184
 307                 'VS185' => 0xE01A8, # VARIATION SELECTOR-185
 308                 'VS186' => 0xE01A9, # VARIATION SELECTOR-186
 309                 'VS187' => 0xE01AA, # VARIATION SELECTOR-187
 310                 'VS188' => 0xE01AB, # VARIATION SELECTOR-188
 311                 'VS189' => 0xE01AC, # VARIATION SELECTOR-189
 312                 'VS190' => 0xE01AD, # VARIATION SELECTOR-190
 313                 'VS191' => 0xE01AE, # VARIATION SELECTOR-191
 314                 'VS192' => 0xE01AF, # VARIATION SELECTOR-192
 315                 'VS193' => 0xE01B0, # VARIATION SELECTOR-193
 316                 'VS194' => 0xE01B1, # VARIATION SELECTOR-194
 317                 'VS195' => 0xE01B2, # VARIATION SELECTOR-195
 318                 'VS196' => 0xE01B3, # VARIATION SELECTOR-196
 319                 'VS197' => 0xE01B4, # VARIATION SELECTOR-197
 320                 'VS198' => 0xE01B5, # VARIATION SELECTOR-198
 321                 'VS199' => 0xE01B6, # VARIATION SELECTOR-199
 322                 'VS200' => 0xE01B7, # VARIATION SELECTOR-200
 323                 'VS201' => 0xE01B8, # VARIATION SELECTOR-201
 324                 'VS202' => 0xE01B9, # VARIATION SELECTOR-202
 325                 'VS203' => 0xE01BA, # VARIATION SELECTOR-203
 326                 'VS204' => 0xE01BB, # VARIATION SELECTOR-204
 327                 'VS205' => 0xE01BC, # VARIATION SELECTOR-205
 328                 'VS206' => 0xE01BD, # VARIATION SELECTOR-206
 329                 'VS207' => 0xE01BE, # VARIATION SELECTOR-207
 330                 'VS208' => 0xE01BF, # VARIATION SELECTOR-208
 331                 'VS209' => 0xE01C0, # VARIATION SELECTOR-209
 332                 'VS210' => 0xE01C1, # VARIATION SELECTOR-210
 333                 'VS211' => 0xE01C2, # VARIATION SELECTOR-211
 334                 'VS212' => 0xE01C3, # VARIATION SELECTOR-212
 335                 'VS213' => 0xE01C4, # VARIATION SELECTOR-213
 336                 'VS214' => 0xE01C5, # VARIATION SELECTOR-214
 337                 'VS215' => 0xE01C6, # VARIATION SELECTOR-215
 338                 'VS216' => 0xE01C7, # VARIATION SELECTOR-216
 339                 'VS217' => 0xE01C8, # VARIATION SELECTOR-217
 340                 'VS218' => 0xE01C9, # VARIATION SELECTOR-218
 341                 'VS219' => 0xE01CA, # VARIATION SELECTOR-219
 342                 'VS220' => 0xE01CB, # VARIATION SELECTOR-220
 343                 'VS221' => 0xE01CC, # VARIATION SELECTOR-221
 344                 'VS222' => 0xE01CD, # VARIATION SELECTOR-222
 345                 'VS223' => 0xE01CE, # VARIATION SELECTOR-223
 346                 'VS224' => 0xE01CF, # VARIATION SELECTOR-224
 347                 'VS225' => 0xE01D0, # VARIATION SELECTOR-225
 348                 'VS226' => 0xE01D1, # VARIATION SELECTOR-226
 349                 'VS227' => 0xE01D2, # VARIATION SELECTOR-227
 350                 'VS228' => 0xE01D3, # VARIATION SELECTOR-228
 351                 'VS229' => 0xE01D4, # VARIATION SELECTOR-229
 352                 'VS230' => 0xE01D5, # VARIATION SELECTOR-230
 353                 'VS231' => 0xE01D6, # VARIATION SELECTOR-231
 354                 'VS232' => 0xE01D7, # VARIATION SELECTOR-232
 355                 'VS233' => 0xE01D8, # VARIATION SELECTOR-233
 356                 'VS234' => 0xE01D9, # VARIATION SELECTOR-234
 357                 'VS235' => 0xE01DA, # VARIATION SELECTOR-235
 358                 'VS236' => 0xE01DB, # VARIATION SELECTOR-236
 359                 'VS237' => 0xE01DC, # VARIATION SELECTOR-237
 360                 'VS238' => 0xE01DD, # VARIATION SELECTOR-238
 361                 'VS239' => 0xE01DE, # VARIATION SELECTOR-239
 362                 'VS240' => 0xE01DF, # VARIATION SELECTOR-240
 363                 'VS241' => 0xE01E0, # VARIATION SELECTOR-241
 364                 'VS242' => 0xE01E1, # VARIATION SELECTOR-242
 365                 'VS243' => 0xE01E2, # VARIATION SELECTOR-243
 366                 'VS244' => 0xE01E3, # VARIATION SELECTOR-244
 367                 'VS245' => 0xE01E4, # VARIATION SELECTOR-245
 368                 'VS246' => 0xE01E5, # VARIATION SELECTOR-246
 369                 'VS247' => 0xE01E6, # VARIATION SELECTOR-247
 370                 'VS248' => 0xE01E7, # VARIATION SELECTOR-248
 371                 'VS249' => 0xE01E8, # VARIATION SELECTOR-249
 372                 'VS250' => 0xE01E9, # VARIATION SELECTOR-250
 373                 'VS251' => 0xE01EA, # VARIATION SELECTOR-251
 374                 'VS252' => 0xE01EB, # VARIATION SELECTOR-252
 375                 'VS253' => 0xE01EC, # VARIATION SELECTOR-253
 376                 'VS254' => 0xE01ED, # VARIATION SELECTOR-254
 377                 'VS255' => 0xE01EE, # VARIATION SELECTOR-255
 378                 'VS256' => 0xE01EF, # VARIATION SELECTOR-256
 379                 'WJ'    => 0x2060, # WORD JOINER
 380                 'ZWJ'   => 0x200D, # ZERO WIDTH JOINER
 381                 'ZWNJ'  => 0x200C, # ZERO WIDTH NON-JOINER
 382                 'ZWSP'  => 0x200B, # ZERO WIDTH SPACE
 383             );
 384
 385 my %deprecated_aliases = (
 386                 # Pre-3.2 compatibility (only for the first 256 characters).
 387                 # Use of these gives deprecated message.
 388                 'HORIZONTAL TABULATION' => 0x09, # CHARACTER TABULATION
 389                 'VERTICAL TABULATION'   => 0x0B, # LINE TABULATION
 390                 'FILE SEPARATOR'        => 0x1C, # INFORMATION SEPARATOR FOUR
 391                 'GROUP SEPARATOR'       => 0x1D, # INFORMATION SEPARATOR THREE
 392                 'RECORD SEPARATOR'      => 0x1E, # INFORMATION SEPARATOR TWO
 393                 'UNIT SEPARATOR'        => 0x1F, # INFORMATION SEPARATOR ONE
 394                 'HORIZONTAL TABULATION SET' => 0x88, # CHARACTER TABULATION SET
 395                 'HORIZONTAL TABULATION WITH JUSTIFICATION' => 0x89, # CHARACTER TABULATION WITH JUSTIFICATION
 396                 'PARTIAL LINE DOWN'       => 0x8B, # PARTIAL LINE FORWARD
 397                 'PARTIAL LINE UP'         => 0x8C, # PARTIAL LINE BACKWARD
 398                 'VERTICAL TABULATION SET' => 0x8A, # LINE TABULATION SET
 399                 'REVERSE INDEX'           => 0x8D, # REVERSE LINE FEED
 400             );
 401
 402
 403 my $txt;  # The table of official character names
 404
 405 my %full_names_cache; # Holds already-looked-up names, so don't have to
 406 # re-look them up again.  The previous versions of charnames had scoping
 407 # bugs.  For example if we use script A in one scope and find and cache
 408 # what Z resolves to, we can't use that cache in a different scope that
 409 # uses script B instead of A, as Z might be an entirely different letter
 410 # there; or there might be different aliases in effect in different
 411 # scopes, or :short may be in effect or not effect in different scopes,
 412 # or various combinations thereof.  This was solved in this version
 413 # mostly by moving things to %^H.  But some things couldn't be moved
 414 # there.  One of them was the cache of runtime looked-up names, in part
 415 # because %^H is read-only at runtime.  I (khw) don't know why the cache
 416 # was run-time only in the previous versions: perhaps oversight; perhaps
 417 # that compile time looking doesn't happen in a loop so didn't think it
 418 # was worthwhile; perhaps not wanting to make the cache too large.  But
 419 # I decided to make it compile time as well; this could easily be
 420 # changed.
 421 # Anyway, this hash is not scoped, and is added to at runtime.  It
 422 # doesn't have scoping problems because the data in it is restricted to
 423 # official names, which are always invariant, and we only set it and
 424 # look at it at during :full lookups, so is unaffected by any other
 425 # scoped options.  I put this in to maintain parity with the older
 426 # version.  If desired, a %short_names cache could also be made, as well
 427 # as one for each script, say in %script_names_cache, with each key
 428 # being a hash for a script named in a 'use charnames' statement.  I
 429 # decided not to do that for now, just because it's added complication,
 430 # and because I'm just trying to maintain parity, not extend it.
 431
 432 # Designed so that test decimal first, and then hex.  Leading zeros
 433 # imply non-decimal, as do non-[0-9]
 434 my $decimal_qr = qr/^[1-9]\d*$/;
 435
 436 # Returns the hex number in $1.
 437 my $hex_qr = qr/^(?:[Uu]\+|0[xX])?([[:xdigit:]]+)$/;
 438
 439 sub croak
 440 {
 441   require Carp; goto &Carp::croak;
 442 } # croak
 443
 444 sub carp
 445 {
 446   require Carp; goto &Carp::carp;
 447 } # carp
 448
 449 sub alias (@) # Set up a single alias
 450 {
 451   my $alias = ref $_[0] ? $_[0] : { @_ };
 452   foreach my $name (keys %$alias) {
 453     my $value = $alias->{$name};
 454     next unless defined $value;          # Omit if screwed up.
 455
 456     # Is slightly slower to just after this statement see if it is
 457     # decimal, since we already know it is after having converted from
 458     # hex, but makes the code easier to maintain, and is called
 459     # infrequently, only at compile-time
 460     if ($value !~ $decimal_qr && $value =~ $hex_qr) {
 461       $value = CORE::hex $1;
 462     }
 463     if ($value =~ $decimal_qr) {
 464         $^H{charnames_ord_aliases}{$name} = $value;
 465
 466         # Use a canonical form.
 467         $^H{charnames_inverse_ords}{sprintf("%04X", $value)} = $name;
 468     }
 469     else {
 470         # XXX validate syntax when deprecation cycle complete. ie. start
 471         # with an alpha only, etc.
 472         $^H{charnames_name_aliases}{$name} = $value;
 473     }
 474   }
 475 } # alias
 476
 477 sub not_legal_use_bytes_msg {
 478   my ($name, $ord) = @_;
 479   return sprintf("Character 0x%04x with name '$name' is above 0xFF with 'use bytes' in effect", $ord);
 480 }
 481
 482 sub alias_file ($)  # Reads a file containing alias definitions
 483 {
 484   my ($arg, $file) = @_;
 485   if (-f $arg && File::Spec->file_name_is_absolute ($arg)) {
 486     $file = $arg;
 487   }
 488   elsif ($arg =~ m/^\w+$/) {
 489     $file = "unicore/${arg}_alias.pl";
 490   }
 491   else {
 492     croak "Charnames alias files can only have identifier characters";
 493   }
 494   if (my @alias = do $file) {
 495     @alias == 1 && !defined $alias[0] and
 496       croak "$file cannot be used as alias file for charnames";
 497     @alias % 2 and
 498       croak "$file did not return a (valid) list of alias pairs";
 499     alias (@alias);
 500     return (1);
 501   }
 502   0;
 503 } # alias_file
 504
 505
 506 sub lookup_name ($;$) {
 507
 508   # Finds the ordinal of a character name, first in the aliases, then in
 509   # the large table.  If not found, returns undef if runtime; if
 510   # compile, complains and returns the Unicode replacement character.
 511
 512   my $runtime = (@_ > 1);  # compile vs run time
 513
 514   my ($name, $hints_ref) = @_;
 515
 516   my $ord;
 517   my $save_input;
 518
 519   if ($runtime) {
 520     # At runtime, but currently not at compile time, $^H gets
 521     # stringified, so un-stringify back to the original data structures.
 522     # These get thrown away by perl before the next invocation
 523     # Also fill in the hash with the non-stringified data.
 524
 525     %{$^H{charnames_name_aliases}} = split ',', $hints_ref->{charnames_stringified_names};
 526     %{$^H{charnames_ord_aliases}} = split ',', $hints_ref->{charnames_stringified_ords};
 527     $^H{charnames_scripts} = $hints_ref->{charnames_scripts};
 528     $^H{charnames_full} = $hints_ref->{charnames_full};
 529     $^H{charnames_short} = $hints_ref->{charnames_short};
 530   }
 531
 532   # User alias should be checked first or else can't override ours, and if we
 533   # add any, could conflict with theirs.
 534   if (exists $^H{charnames_ord_aliases}{$name}) {
 535     $ord = $^H{charnames_ord_aliases}{$name};
 536   }
 537   elsif (exists $^H{charnames_name_aliases}{$name}) {
 538     $name = $^H{charnames_name_aliases}{$name};
 539     $save_input = $name;  # Cache the result for any error message
 540   }
 541   elsif (exists $system_aliases{$name}) {
 542     $ord = $system_aliases{$name};
 543   }
 544   elsif (exists $deprecated_aliases{$name}) {
 545     require warnings;
 546     warnings::warnif('deprecated', "Unicode character name \"$name\" is deprecated, use \"" . viacode($deprecated_aliases{$name}) . "\" instead");
 547     $ord = $deprecated_aliases{$name};
 548   }
 549
 550   my @off;
 551
 552   if (! defined $ord) {
 553
 554     # See if has looked this up earlier.
 555     if ($^H{charnames_full} && exists $full_names_cache{$name}) {
 556       $ord = $full_names_cache{$name};
 557     }
 558     else {
 559
 560       ## Suck in the code/name list as a big string.
 561       ## Lines look like:
 562       ##     "0052\t\tLATIN CAPITAL LETTER R\n"
 563       $txt = do "unicore/Name.pl" unless $txt;
 564
 565       ## @off will hold the index into the code/name string of the start and
 566       ## end of the name as we find it.
 567
 568       ## If :full, look for the name exactly; runtime implies full
 569       my $found_full_in_table = 0;  # Tells us if can cache the result
 570       if ($^H{charnames_full}) {
 571
 572         # See if the name is one which is algorithmically determinable.
 573         # The subroutine is included in Name.pl.  The table contained in
 574         # $txt doesn't contain these.  Experiments show that checking
 575         # for these before checking for the regular names has no
 576         # noticeable impact on performance for the regular names, but
 577         # the other way around slows down finding these immensely.
 578         # Algorithmically determinables are not placed in the cache (that
 579         # $found_full_in_table indicates) because that uses up memory,
 580         # and finding these again is fast.
 581         if (! defined ($ord = name_to_code_point_special($name))) {
 582
 583           # Not algorthmically determinable; look up in the table.
 584           if ($txt =~ /\t\t\Q$name\E$/m) {
 585             @off = ($-[0] + 2, $+[0]);    # The 2 is for the 2 tabs
 586             $found_full_in_table = 1;
 587           }
 588         }
 589       }
 590
 591       # If we didn't get it above, keep looking
 592       if (! $found_full_in_table && ! defined $ord) {
 593
 594         # If :short is allowed, see if input is like "greek:Sigma".
 595         my $scripts_trie;
 596         if (($^H{charnames_short})
 597             && $name =~ /^ \s* (.+?) \s* : \s* (.+?) \s* $ /xs)
 598         {
 599             $scripts_trie = "\U\Q$1";
 600             $name = $2;
 601         }
 602         else {
 603             $scripts_trie = $^H{charnames_scripts};
 604         }
 605
 606         my $case = $name =~ /[[:upper:]]/ ? "CAPITAL" : "SMALL";
 607         if ($txt !~
 608             /\t\t (?: $scripts_trie ) \ (?:$case\ )? LETTER \ \U\Q$name\E $/xm)
 609         {
 610           # Here we still don't have it, give up.
 611           return if $runtime;
 612
 613           # May have zapped input name, get it again.
 614           $name = (defined $save_input) ? $save_input : $_[0];
 615           carp "Unknown charname '$name'";
 616           return 0xFFFD;
 617         }
 618
 619         @off = ($-[0] + 2, $+[0]);
 620       }
 621
 622       if (! defined $ord) {
 623         ##
 624         ## Now know where in the string the name starts.
 625         ## The code, in hex, is before that.
 626         ##
 627         ## The code can be 4-6 characters long, so we've got to sort of
 628         ## go look for it, just after the newline that comes before $off[0].
 629         ##
 630         ## This would be much easier if unicore/Name.pl had info in
 631         ## a name/code order, instead of code/name order.
 632         ##
 633         ## The +1 after the rindex() is to skip past the newline we're finding,
 634         ## or, if the rindex() fails, to put us to an offset of zero.
 635         ##
 636         my $hexstart = rindex($txt, "\n", $off[0]) + 1;
 637
 638         ## we know where it starts, so turn into number -
 639         ## the ordinal for the char.
 640         $ord = CORE::hex substr($txt, $hexstart, $off[0] - 2 - $hexstart);
 641       }
 642
 643       # Cache the input so as to not have to search the large table
 644       # again, but only if it came from the one search that we cache.
 645       $full_names_cache{$name} = $ord if $found_full_in_table;
 646     }
 647   }
 648
 649   return $ord if $runtime || $ord <= 255 || ! ($^H & $bytes::hint_bits);
 650
 651   # Here is compile time, "use bytes" is in effect, and the character
 652   # won't fit in a byte
 653   # Prefer any official name over the input one.
 654   if (@off) {
 655     $name = substr($txt, $off[0], $off[1] - $off[0]) if @off;
 656   }
 657   else {
 658     $name = (defined $save_input) ? $save_input : $_[0];
 659   }
 660   croak not_legal_use_bytes_msg($name, $ord);
 661 } # lookup_name
 662
 663 sub charnames {
 664   my $name = shift;
 665
 666   # For \N{...}.  Looks up the character name and returns its ordinal if
 667   # found, undef otherwise.  If not in 'use bytes', forces into utf8
 668
 669   my $ord = lookup_name($name);
 670   return if ! defined $ord;
 671   return chr $ord if $^H & $bytes::hint_bits;
 672
 673   no warnings 'utf8'; # allow even illegal characters
 674   return pack "U", $ord;
 675 }
 676
 677 sub import
 678 {
 679   shift; ## ignore class name
 680
 681   if (not @_) {
 682     carp("`use charnames' needs explicit imports list");
 683   }
 684   $^H{charnames} = \&charnames ;
 685   $^H{charnames_ord_aliases} = {};
 686   $^H{charnames_name_aliases} = {};
 687   $^H{charnames_inverse_ords} = {};
 688
 689   ##
 690   ## fill %h keys with our @_ args.
 691   ##
 692   my ($promote, %h, @args) = (0);
 693   while (my $arg = shift) {
 694     if ($arg eq ":alias") {
 695       @_ or
 696         croak ":alias needs an argument in charnames";
 697       my $alias = shift;
 698       if (ref $alias) {
 699         ref $alias eq "HASH" or
 700           croak "Only HASH reference supported as argument to :alias";
 701         alias ($alias);
 702         next;
 703       }
 704       if ($alias =~ m{:(\w+)$}) {
 705         $1 eq "full" || $1 eq "short" and
 706           croak ":alias cannot use existing pragma :$1 (reversed order?)";
 707         alias_file ($1) and $promote = 1;
 708         next;
 709       }
 710       alias_file ($alias);
 711       next;
 712     }
 713     if (substr($arg, 0, 1) eq ':' and ! ($arg eq ":full" || $arg eq ":short")) {
 714       warn "unsupported special '$arg' in charnames";
 715       next;
 716     }
 717     push @args, $arg;
 718   }
 719   @args == 0 && $promote and @args = (":full");
 720   @h{@args} = (1) x @args;
 721
 722   $^H{charnames_full} = delete $h{':full'};
 723   $^H{charnames_short} = delete $h{':short'};
 724   my @scripts = map uc, keys %h;
 725
 726   ##
 727   ## If utf8? warnings are enabled, and some scripts were given,
 728   ## see if at least we can find one letter from each script.
 729   ##
 730   if (warnings::enabled('utf8') && @scripts) {
 731     $txt = do "unicore/Name.pl" unless $txt;
 732
 733     for my $script (@scripts) {
 734       if (not $txt =~ m/\t\t$script (?:CAPITAL |SMALL )?LETTER /) {
 735         warnings::warn('utf8',  "No such script: '$script'");
 736         $script = quotemeta $script;  # Escape it, for use in the re.
 737       }
 738     }
 739   }
 740
 741   # %^H gets stringified, so serialize it ourselves so can extract the
 742   # real data back later.
 743   $^H{charnames_stringified_ords} = join ",", %{$^H{charnames_ord_aliases}};
 744   $^H{charnames_stringified_names} = join ",", %{$^H{charnames_name_aliases}};
 745   $^H{charnames_stringified_inverse_ords} = join ",", %{$^H{charnames_inverse_ords}};
 746   $^H{charnames_scripts} = join "|", @scripts;  # Stringifiy them as a trie
 747 } # import
 748
 749 # Cache of already looked-up values.  This is set to only contain
 750 # official values, and user aliases can't override them, so scoping is
 751 # not an issue.
 752 my %viacode;
 753
 754 sub viacode {
 755
 756   # Returns the name of the code point argument
 757
 758   if (@_ != 1) {
 759     carp "charnames::viacode() expects one argument";
 760     return;
 761   }
 762
 763   my $arg = shift;
 764
 765   # This is derived from Unicode::UCD, where it is nearly the same as the
 766   # function _getcode(), but here it makes sure that even a hex argument
 767   # has the proper number of leading zeros, which is critical in
 768   # matching against $txt below
 769   # Must check if decimal first; see comments at that definition
 770   my $hex;
 771   if ($arg =~ $decimal_qr) {
 772     $hex = sprintf "%04X", $arg;
 773   } elsif ($arg =~ $hex_qr) {
 774     # Below is the line that differs from the _getcode() source
 775     $hex = sprintf "%04X", hex $1;
 776   } else {
 777     carp("unexpected arg \"$arg\" to charnames::viacode()");
 778     return;
 779   }
 780
 781   return $viacode{$hex} if exists $viacode{$hex};
 782
 783   # If the code point is above the max in the table, there's no point
 784   # looking through it.  Checking the length first is slightly faster
 785   if (length($hex) <= 5 || CORE::hex($hex) <= 0x10FFFF) {
 786     $txt = do "unicore/Name.pl" unless $txt;
 787
 788     # See if the name is algorithmically determinable.
 789     my $algorithmic = code_point_to_name_special(CORE::hex $hex);
 790     if (defined $algorithmic) {
 791       $viacode{$hex} = $algorithmic;
 792       return $algorithmic;
 793     }
 794
 795     # Return the official name, if exists.  It's unclear to me (khw) at
 796     # this juncture if it is better to return a user-defined override, so
 797     # leaving it as is for now.
 798     if ($txt =~ m/^$hex\t\t/m) {
 799
 800         # The name starts with the next character and goes up to the
 801         # next new-line.  Using capturing parentheses above instead of
 802         # @+ more than doubles the execution time in Perl 5.13
 803         $viacode{$hex} = substr($txt, $+[0], index($txt, "\n", $+[0]) - $+[0]);
 804         return $viacode{$hex};
 805     }
 806   }
 807
 808   # See if there is a user name for it, before giving up completely.
 809   # First get the scoped aliases.
 810   my %code_point_aliases = split ',',
 811                           (caller(0))[10]->{charnames_stringified_inverse_ords};
 812   if (! exists $code_point_aliases{$hex}) {
 813     if (CORE::hex($hex) > 0x10FFFF) {
 814         carp "Unicode characters only allocated up to U+10FFFF (you asked for U+$hex)";
 815     }
 816     return;
 817   }
 818
 819   return $code_point_aliases{$hex};
 820 } # viacode
 821
 822 sub vianame
 823 {
 824   if (@_ != 1) {
 825     carp "charnames::vianame() expects one name argument";
 826     return ()
 827   }
 828
 829   # Looks up the character name and returns its ordinal if
 830   # found, undef otherwise.
 831
 832   my $arg = shift;
 833
 834   if ($arg =~ /^U\+([0-9a-fA-F]+)$/) {
 835
 836     # khw claims that this is bad.  The function should return either a
 837     # an ord or a chr for all inputs; not be bipolar.
 838     my $ord = CORE::hex $1;
 839     return chr $ord if $ord <= 255 || ! ((caller 0)[8] & $bytes::hint_bits);
 840     carp not_legal_use_bytes_msg($arg, $ord);
 841     return;
 842   }
 843
 844   return lookup_name($arg, (caller(0))[10]);
 845 } # vianame
 846
 847
 848 1;
 849 __END__
 850
 851 =head1 NAME
 852
 853 charnames - access to Unicode character names; define character names for C<\N{named}> string literal escapes
 854
 855 =head1 SYNOPSIS
 856
 857   use charnames ':full';
 858   print "\N{GREEK SMALL LETTER SIGMA} is called sigma.\n";
 859
 860   use charnames ':short';
 861   print "\N{greek:Sigma} is an upper-case sigma.\n";
 862
 863   use charnames qw(cyrillic greek);
 864   print "\N{sigma} is Greek sigma, and \N{be} is Cyrillic b.\n";
 865
 866   use charnames ":full", ":alias" => {
 867     e_ACUTE => "LATIN SMALL LETTER E WITH ACUTE",
 868     mychar => 0xE8000,  # Private use area
 869   };
 870   print "\N{e_ACUTE} is a small letter e with an acute.\n";
 871   print "\\N{mychar} allows me to name private use characters.\n";
 872
 873   use charnames ();
 874   print charnames::viacode(0x1234); # prints "ETHIOPIC SYLLABLE SEE"
 875   printf "%04X", charnames::vianame("GOTHIC LETTER AHSA"); # prints
 876                                                            # "10330"
 877
 878 =head1 DESCRIPTION
 879
 880 Pragma C<use charnames> is used to gain access to the names of the
 881 Unicode characters, and to allow you to define your own character names.
 882
 883 All forms of the pragma enable use of the
 884 L</charnames::vianame(I<name>)> function for run-time lookup of a
 885 character name to get its ordinal (code point), and the inverse
 886 function, L</charnames::viacode(I<code>)>.
 887
 888 Forms other than C<S<"use charnames ();">> enable the use of of
 889 C<\N{I<CHARNAME>}> sequences to compile a Unicode character into a
 890 string based on its name.
 891
 892 Note that C<\N{U+I<...>}>, where the I<...> is a hexadecimal number,
 893 also inserts a character into a string, but doesn't require the use of
 894 this pragma.  The character it inserts is the one whose code point
 895 (ordinal value) is equal to the number.  For example, C<"\N{U+263a}"> is
 896 the Unicode (white background, black foreground) smiley face; it doesn't
 897 require this pragma, whereas the equivalent, C<"\N{WHITE SMILING FACE}">
 898 does.
 899 Also, C<\N{I<...>}> can mean a regex quantifier instead of a character
 900 name, when the I<...> is a number (or comma separated pair of numbers;
 901 see L<perlreref/QUANTIFIERS>), and is not related to this pragma.
 902
 903 The C<charnames> pragma supports arguments C<:full>, C<:short>, script
 904 names and customized aliases.  If C<:full> is present, for expansion of
 905 C<\N{I<CHARNAME>}>, the string I<CHARNAME> is first looked up in the list of
 906 standard Unicode character names.  If C<:short> is present, and
 907 I<CHARNAME> has the form C<I<SCRIPT>:I<CNAME>>, then I<CNAME> is looked up
 908 as a letter in script I<SCRIPT>.  If C<use charnames> is used
 909 with script name arguments, then for C<\N{I<CHARNAME>}> the name
 910 I<CHARNAME> is looked up as a letter in the given scripts (in the
 911 specified order). Customized aliases can override these, and are explained in
 912 L</CUSTOM ALIASES>.
 913
 914 For lookup of I<CHARNAME> inside a given script I<SCRIPTNAME>
 915 this pragma looks for the names
 916
 917   SCRIPTNAME CAPITAL LETTER CHARNAME
 918   SCRIPTNAME SMALL LETTER CHARNAME
 919   SCRIPTNAME LETTER CHARNAME
 920
 921 in the table of standard Unicode names.  If I<CHARNAME> is lowercase,
 922 then the C<CAPITAL> variant is ignored, otherwise the C<SMALL> variant
 923 is ignored.
 924
 925 Note that C<\N{...}> is compile-time; it's a special form of string
 926 constant used inside double-quotish strings; this means that you cannot
 927 use variables inside the C<\N{...}>.  If you want similar run-time
 928 functionality, use L<charnames::vianame()|/charnames::vianame(I<name>)>.
 929
 930 For the C0 and C1 control characters (U+0000..U+001F, U+0080..U+009F)
 931 there are no official Unicode names but you can use instead the ISO 6429
 932 names (LINE FEED, ESCAPE, and so forth, and their abbreviations, LF,
 933 ESC, ...).  In Unicode 3.2 (as of Perl 5.8) some naming changes took
 934 place, and ISO 6429 was updated, see L</ALIASES>.
 935
 936 If the input name is unknown, C<\N{NAME}> raises a warning and
 937 substitutes the Unicode REPLACEMENT CHARACTER (U+FFFD).
 938
 939 It is a fatal error if C<use bytes> is in effect and the input name is
 940 that of a character that won't fit into a byte (i.e., whose ordinal is
 941 above 255).
 942
 943 Otherwise, any string that includes a C<\N{I<charname>}> or
 944 C<S<\N{U+I<code point>}>> will automatically have Unicode semantics (see
 945 L<perlunicode/Byte and Character Semantics>).
 946
 947 =head1 ALIASES
 948
 949 A few aliases have been defined for convenience: instead of having
 950 to use the official names
 951
 952     LINE FEED (LF)
 953     FORM FEED (FF)
 954     CARRIAGE RETURN (CR)
 955     NEXT LINE (NEL)
 956
 957 (yes, with parentheses), one can use
 958
 959     LINE FEED
 960     FORM FEED
 961     CARRIAGE RETURN
 962     NEXT LINE
 963     LF
 964     FF
 965     CR
 966     NEL
 967
 968 All the other standard abbreviations for the controls, such as C<ACK> for
 969 C<ACKNOWLEDGE> also can be used.
 970
 971 One can also use
 972
 973     BYTE ORDER MARK
 974     BOM
 975
 976 and these abbreviations
 977
 978     Abbreviation        Full Name
 979
 980     CGJ                 COMBINING GRAPHEME JOINER
 981     FVS1                MONGOLIAN FREE VARIATION SELECTOR ONE
 982     FVS2                MONGOLIAN FREE VARIATION SELECTOR TWO
 983     FVS3                MONGOLIAN FREE VARIATION SELECTOR THREE
 984     LRE                 LEFT-TO-RIGHT EMBEDDING
 985     LRM                 LEFT-TO-RIGHT MARK
 986     LRO                 LEFT-TO-RIGHT OVERRIDE
 987     MMSP                MEDIUM MATHEMATICAL SPACE
 988     MVS                 MONGOLIAN VOWEL SEPARATOR
 989     NBSP                NO-BREAK SPACE
 990     NNBSP               NARROW NO-BREAK SPACE
 991     PDF                 POP DIRECTIONAL FORMATTING
 992     RLE                 RIGHT-TO-LEFT EMBEDDING
 993     RLM                 RIGHT-TO-LEFT MARK
 994     RLO                 RIGHT-TO-LEFT OVERRIDE
 995     SHY                 SOFT HYPHEN
 996     VS1                 VARIATION SELECTOR-1
 997     .
 998     .
 999     .
1000     VS256               VARIATION SELECTOR-256
1001     WJ                  WORD JOINER
1002     ZWJ                 ZERO WIDTH JOINER
1003     ZWNJ                ZERO WIDTH NON-JOINER
1004     ZWSP                ZERO WIDTH SPACE
1005
1006 For backward compatibility one can use the old names for
1007 certain C0 and C1 controls
1008
1009     old                         new
1010
1011     FILE SEPARATOR              INFORMATION SEPARATOR FOUR
1012     GROUP SEPARATOR             INFORMATION SEPARATOR THREE
1013     HORIZONTAL TABULATION       CHARACTER TABULATION
1014     HORIZONTAL TABULATION SET   CHARACTER TABULATION SET
1015     HORIZONTAL TABULATION WITH JUSTIFICATION    CHARACTER TABULATION
1016                                                 WITH JUSTIFICATION
1017     PARTIAL LINE DOWN           PARTIAL LINE FORWARD
1018     PARTIAL LINE UP             PARTIAL LINE BACKWARD
1019     RECORD SEPARATOR            INFORMATION SEPARATOR TWO
1020     REVERSE INDEX               REVERSE LINE FEED
1021     UNIT SEPARATOR              INFORMATION SEPARATOR ONE
1022     VERTICAL TABULATION         LINE TABULATION
1023     VERTICAL TABULATION SET     LINE TABULATION SET
1024
1025 but the old names in addition to giving the character
1026 will also give a warning about being deprecated.
1027
1028 And finally, certain published variants are usable, including some for
1029 controls that have no Unicode names:
1030
1031     name                                   character
1032
1033     END OF PROTECTED AREA                  END OF GUARDED AREA, U+0097
1034     HIGH OCTET PRESET                      U+0081
1035     HOP                                    U+0081
1036     IND                                    U+0084
1037     INDEX                                  U+0084
1038     PAD                                    U+0080
1039     PADDING CHARACTER                      U+0080
1040     PRIVATE USE 1                          PRIVATE USE ONE, U+0091
1041     PRIVATE USE 2                          PRIVATE USE TWO, U+0092
1042     SGC                                    U+0099
1043     SINGLE GRAPHIC CHARACTER INTRODUCER    U+0099
1044     SINGLE-SHIFT 2                         SINGLE SHIFT TWO, U+008E
1045     SINGLE-SHIFT 3                         SINGLE SHIFT THREE, U+008F
1046     START OF PROTECTED AREA                START OF GUARDED AREA, U+0096
1047
1048 =head1 CUSTOM ALIASES
1049
1050 You can add customized aliases to standard (C<:full>) Unicode naming
1051 conventions.  The aliases override any standard definitions, so, if
1052 you're twisted enough, you can change C<"\N{LATIN CAPITAL LETTER A}"> to
1053 mean C<"B">, etc.
1054
1055 Note that an alias should not be something that is a legal curly
1056 brace-enclosed quantifier (see L<perlreref/QUANTIFIERS>).  For example
1057 C<\N{123}> means to match 123 non-newline characters, and is not treated as a
1058 charnames alias.  Aliases are discouraged from beginning with anything
1059 other than an alphabetic character and from containing anything other
1060 than alphanumerics, spaces, dashes, parentheses, and underscores.
1061 Currently they must be ASCII.
1062
1063 An alias can map to either an official Unicode character name or to a
1064 numeric code point (ordinal).  The latter is useful for assigning names
1065 to code points in Unicode private use areas such as U+E800 through
1066 U+F8FF.
1067 A numeric code point must be a non-negative integer or a string beginning
1068 with C<"U+"> or C<"0x"> with the remainder considered to be a
1069 hexadecimal integer.  A literal numeric constant must be unsigned; it
1070 will be interpreted as hex if it has a leading zero or contains
1071 non-decimal hex digits; otherwise it will be interpreted as decimal.
1072
1073 Aliases are added either by the use of anonymous hashes:
1074
1075     use charnames ":alias" => {
1076         e_ACUTE => "LATIN SMALL LETTER E WITH ACUTE",
1077         mychar1 => 0xE8000,
1078         };
1079     my $str = "\N{e_ACUTE}";
1080
1081 or by using a file containing aliases:
1082
1083     use charnames ":alias" => "pro";
1084
1085 will try to read C<"unicore/pro_alias.pl"> from the C<@INC> path. This
1086 file should return a list in plain perl:
1087
1088     (
1089     A_GRAVE         => "LATIN CAPITAL LETTER A WITH GRAVE",
1090     A_CIRCUM        => "LATIN CAPITAL LETTER A WITH CIRCUMFLEX",
1091     A_DIAERES       => "LATIN CAPITAL LETTER A WITH DIAERESIS",
1092     A_TILDE         => "LATIN CAPITAL LETTER A WITH TILDE",
1093     A_BREVE         => "LATIN CAPITAL LETTER A WITH BREVE",
1094     A_RING          => "LATIN CAPITAL LETTER A WITH RING ABOVE",
1095     A_MACRON        => "LATIN CAPITAL LETTER A WITH MACRON",
1096     mychar2         => "U+E8001",
1097     );
1098
1099 Both these methods insert C<":full"> automatically as the first argument (if no
1100 other argument is given), and you can give the C<":full"> explicitly as
1101 well, like
1102
1103     use charnames ":full", ":alias" => "pro";
1104
1105 =head1 charnames::viacode(I<code>)
1106
1107 Returns the full name of the character indicated by the numeric code.
1108 For example,
1109
1110     print charnames::viacode(0x2722);
1111
1112 prints "FOUR TEARDROP-SPOKED ASTERISK".
1113
1114 The name returned is the official name for the code point, if
1115 available, otherwise your custom alias for it.  This means that your
1116 alias will only be returned for code points that don't have an official
1117 Unicode name (nor Unicode version 1 name), such as private use code
1118 points, and the 4 control characters U+0080, U+0081, U+0084, and U+0099.
1119 If you define more than one name for the code point, it is indeterminate
1120 which one will be returned.
1121
1122 The function returns C<undef> if no name is known for the code point.
1123 In Unicode the proper name of these is the empty string, which
1124 C<undef> stringifies to.  (If you ask for a code point past the legal
1125 Unicode maximum of U+10FFFF that you haven't assigned an alias to, you
1126 get C<undef> plus a warning.)
1127
1128 The input number must be a non-negative integer or a string beginning
1129 with C<"U+"> or C<"0x"> with the remainder considered to be a
1130 hexadecimal integer.  A literal numeric constant must be unsigned; it
1131 will be interpreted as hex if it has a leading zero or contains
1132 non-decimal hex digits; otherwise it will be interpreted as decimal.
1133
1134 Notice that the name returned for of U+FEFF is "ZERO WIDTH NO-BREAK
1135 SPACE", not "BYTE ORDER MARK".
1136
1137 =head1 charnames::vianame(I<name>)
1138
1139 Returns the code point indicated by the name.
1140 For example,
1141
1142     printf "%04X", charnames::vianame("FOUR TEARDROP-SPOKED ASTERISK");
1143
1144 prints "2722".
1145
1146 C<vianame> takes the identical inputs that C<\N{...}> does under the
1147 L<C<:full> option|/DESCRIPTION> to C<charnames>.  In addition, any other
1148 options for the controlling C<"use charnames"> in the same scope apply,
1149 like any L<script list, C<:short> option|/DESCRIPTION>, or L<custom
1150 aliases|/CUSTOM ALIASES> you may have defined.
1151
1152 There are just a few differences.  The main one is that under
1153 most (see L</BUGS> for the others) circumstances, vianame returns
1154 an ord, whereas C<\\N{...}> is seamlessly placed as a chr into the
1155 string in which it appears.  This leads to a second difference.
1156 Since an ord is returned, it can be that of any character, even one
1157 that isn't legal under the C<S<use bytes>> pragma.
1158
1159 The final difference is that if the input name is unknown C<vianame>
1160 returns C<undef> instead of the REPLACEMENT CHARACTER, and it does not
1161 raise a warning message.
1162
1163 =head1 CUSTOM TRANSLATORS
1164
1165 The mechanism of translation of C<\N{...}> escapes is general and not
1166 hardwired into F<charnames.pm>.  A module can install custom
1167 translations (inside the scope which C<use>s the module) with the
1168 following magic incantation:
1169
1170     sub import {
1171         shift;
1172         $^H{charnames} = \&translator;
1173     }
1174
1175 Here translator() is a subroutine which takes I<CHARNAME> as an
1176 argument, and returns text to insert into the string instead of the
1177 C<\N{I<CHARNAME>}> escape.  Since the text to insert should be different
1178 in C<bytes> mode and out of it, the function should check the current
1179 state of C<bytes>-flag as in:
1180
1181     use bytes ();                      # for $bytes::hint_bits
1182     sub translator {
1183         if ($^H & $bytes::hint_bits) {
1184             return bytes_translator(@_);
1185         }
1186         else {
1187             return utf8_translator(@_);
1188         }
1189     }
1190
1191 See L</CUSTOM ALIASES> above for restrictions on I<CHARNAME>.
1192
1193 Of course, C<vianame> and C<viacode> would need to be overridden as
1194 well.
1195
1196 =head1 BUGS
1197
1198 vianame returns a chr if the input name is of the form C<U+...>, and an ord
1199 otherwise.  It is proposed to change this to always return an ord.  Send email
1200 to C<perl5-porters@perl.org> to comment on this proposal.  If S<C<use
1201 bytes>> is in effect when a chr is returned, and if that chr won't fit
1202 into a byte, C<undef> is returned instead.
1203
1204 Names must be ASCII characters only, which means that you are out of luck if
1205 you want to create aliases in a language where some or all the characters of
1206 the desired aliases are non-ASCII.
1207
1208 Unicode standard named sequences are not recognized, such as
1209 C<LATIN CAPITAL LETTER A WITH MACRON AND GRAVE>
1210 (which should mean C<LATIN CAPITAL LETTER A WITH MACRON> with an additional
1211 C<COMBINING GRAVE ACCENT>).
1212
1213 Since evaluation of the translation function (see L</CUSTOM
1214 TRANSLATORS>) happens in the middle of compilation (of a string
1215 literal), the translation function should not do any C<eval>s or
1216 C<require>s.  This restriction should be lifted (but is low priority) in
1217 a future version of Perl.
1218
1219 =cut
1220
1221 # ex: set ts=8 sts=2 sw=2 et: