lib/charnames.pm

   1 package charnames;
   2 use strict;
   3 use warnings;
   4 use File::Spec;
   5 our $VERSION = '1.15';
   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 # For use when don't import anything.  This structure must be kept in
 506 # sync with the one that import() fills up.
 507 my %dummy_H = (
 508                 charnames_stringified_names => "",
 509                 charnames_stringified_ords => "",
 510                 charnames_scripts => "",
 511                 charnames_full => 1,
 512                 charnames_short => 0,
 513               );
 514
 515
 516 sub lookup_name ($;$) {
 517
 518   # Finds the ordinal of a character name, first in the aliases, then in
 519   # the large table.  If not found, returns undef if runtime; if
 520   # compile, complains and returns the Unicode replacement character.
 521
 522   my $runtime = (@_ > 1);  # compile vs run time
 523
 524   my ($name, $hints_ref) = @_;
 525
 526   my $ord;
 527   my $save_input;
 528
 529   if ($runtime) {
 530
 531     # If we didn't import anything (which happens with 'use charnames ()',
 532     # substitute a dummy structure.
 533     $hints_ref = \%dummy_H if ! defined $hints_ref
 534                               || ! defined $hints_ref->{charnames_full};
 535
 536     # At runtime, but currently not at compile time, $^H gets
 537     # stringified, so un-stringify back to the original data structures.
 538     # These get thrown away by perl before the next invocation
 539     # Also fill in the hash with the non-stringified data.
 540     # N.B.  New fields must be also added to %dummy_H
 541
 542     %{$^H{charnames_name_aliases}} = split ',',
 543                                       $hints_ref->{charnames_stringified_names};
 544     %{$^H{charnames_ord_aliases}} = split ',',
 545                                       $hints_ref->{charnames_stringified_ords};
 546     $^H{charnames_scripts} = $hints_ref->{charnames_scripts};
 547     $^H{charnames_full} = $hints_ref->{charnames_full};
 548     $^H{charnames_short} = $hints_ref->{charnames_short};
 549   }
 550
 551   # User alias should be checked first or else can't override ours, and if we
 552   # add any, could conflict with theirs.
 553   if (exists $^H{charnames_ord_aliases}{$name}) {
 554     $ord = $^H{charnames_ord_aliases}{$name};
 555   }
 556   elsif (exists $^H{charnames_name_aliases}{$name}) {
 557     $name = $^H{charnames_name_aliases}{$name};
 558     $save_input = $name;  # Cache the result for any error message
 559   }
 560   elsif (exists $system_aliases{$name}) {
 561     $ord = $system_aliases{$name};
 562   }
 563   elsif (exists $deprecated_aliases{$name}) {
 564     require warnings;
 565     warnings::warnif('deprecated', "Unicode character name \"$name\" is deprecated, use \"" . viacode($deprecated_aliases{$name}) . "\" instead");
 566     $ord = $deprecated_aliases{$name};
 567   }
 568
 569   my @off;
 570
 571   if (! defined $ord) {
 572
 573     # See if has looked this up earlier.
 574     if ($^H{charnames_full} && exists $full_names_cache{$name}) {
 575       $ord = $full_names_cache{$name};
 576     }
 577     else {
 578
 579       ## Suck in the code/name list as a big string.
 580       ## Lines look like:
 581       ##     "0052\t\tLATIN CAPITAL LETTER R\n"
 582       $txt = do "unicore/Name.pl" unless $txt;
 583
 584       ## @off will hold the index into the code/name string of the start and
 585       ## end of the name as we find it.
 586
 587       ## If :full, look for the name exactly; runtime implies full
 588       my $found_full_in_table = 0;  # Tells us if can cache the result
 589       if ($^H{charnames_full}) {
 590
 591         # See if the name is one which is algorithmically determinable.
 592         # The subroutine is included in Name.pl.  The table contained in
 593         # $txt doesn't contain these.  Experiments show that checking
 594         # for these before checking for the regular names has no
 595         # noticeable impact on performance for the regular names, but
 596         # the other way around slows down finding these immensely.
 597         # Algorithmically determinables are not placed in the cache (that
 598         # $found_full_in_table indicates) because that uses up memory,
 599         # and finding these again is fast.
 600         if (! defined ($ord = name_to_code_point_special($name))) {
 601
 602           # Not algorthmically determinable; look up in the table.
 603           if ($txt =~ /\t\t\Q$name\E$/m) {
 604             @off = ($-[0] + 2, $+[0]);    # The 2 is for the 2 tabs
 605             $found_full_in_table = 1;
 606           }
 607         }
 608       }
 609
 610       # If we didn't get it above, keep looking
 611       if (! $found_full_in_table && ! defined $ord) {
 612
 613         # If :short is allowed, see if input is like "greek:Sigma".
 614         my $scripts_trie;
 615         if (($^H{charnames_short})
 616             && $name =~ /^ \s* (.+?) \s* : \s* (.+?) \s* $ /xs)
 617         {
 618             $scripts_trie = "\U\Q$1";
 619             $name = $2;
 620         }
 621         else {
 622             $scripts_trie = $^H{charnames_scripts};
 623         }
 624
 625         my $case = $name =~ /[[:upper:]]/ ? "CAPITAL" : "SMALL";
 626         if ($txt !~
 627             /\t\t (?: $scripts_trie ) \ (?:$case\ )? LETTER \ \U\Q$name\E $/xm)
 628         {
 629           # Here we still don't have it, give up.
 630           return if $runtime;
 631
 632           # May have zapped input name, get it again.
 633           $name = (defined $save_input) ? $save_input : $_[0];
 634           carp "Unknown charname '$name'";
 635           return 0xFFFD;
 636         }
 637
 638         @off = ($-[0] + 2, $+[0]);
 639       }
 640
 641       if (! defined $ord) {
 642         ##
 643         ## Now know where in the string the name starts.
 644         ## The code, in hex, is before that.
 645         ##
 646         ## The code can be 4-6 characters long, so we've got to sort of
 647         ## go look for it, just after the newline that comes before $off[0].
 648         ##
 649         ## This would be much easier if unicore/Name.pl had info in
 650         ## a name/code order, instead of code/name order.
 651         ##
 652         ## The +1 after the rindex() is to skip past the newline we're finding,
 653         ## or, if the rindex() fails, to put us to an offset of zero.
 654         ##
 655         my $hexstart = rindex($txt, "\n", $off[0]) + 1;
 656
 657         ## we know where it starts, so turn into number -
 658         ## the ordinal for the char.
 659         $ord = CORE::hex substr($txt, $hexstart, $off[0] - 2 - $hexstart);
 660       }
 661
 662       # Cache the input so as to not have to search the large table
 663       # again, but only if it came from the one search that we cache.
 664       $full_names_cache{$name} = $ord if $found_full_in_table;
 665     }
 666   }
 667
 668   return $ord if $runtime || $ord <= 255 || ! ($^H & $bytes::hint_bits);
 669
 670   # Here is compile time, "use bytes" is in effect, and the character
 671   # won't fit in a byte
 672   # Prefer any official name over the input one.
 673   if (@off) {
 674     $name = substr($txt, $off[0], $off[1] - $off[0]) if @off;
 675   }
 676   else {
 677     $name = (defined $save_input) ? $save_input : $_[0];
 678   }
 679   croak not_legal_use_bytes_msg($name, $ord);
 680 } # lookup_name
 681
 682 sub charnames {
 683   my $name = shift;
 684
 685   # For \N{...}.  Looks up the character name and returns its ordinal if
 686   # found, undef otherwise.  If not in 'use bytes', forces into utf8
 687
 688   my $ord = lookup_name($name);
 689   return if ! defined $ord;
 690   return chr $ord if $^H & $bytes::hint_bits;
 691
 692   no warnings 'utf8'; # allow even illegal characters
 693   return pack "U", $ord;
 694 }
 695
 696 sub import
 697 {
 698   shift; ## ignore class name
 699
 700   if (not @_) {
 701     carp("`use charnames' needs explicit imports list");
 702   }
 703   $^H{charnames} = \&charnames ;
 704   $^H{charnames_ord_aliases} = {};
 705   $^H{charnames_name_aliases} = {};
 706   $^H{charnames_inverse_ords} = {};
 707   # New fields must be added to %dummy_H, and the code in lookup_name()
 708   # that copies fields from the runtime structure
 709
 710   ##
 711   ## fill %h keys with our @_ args.
 712   ##
 713   my ($promote, %h, @args) = (0);
 714   while (my $arg = shift) {
 715     if ($arg eq ":alias") {
 716       @_ or
 717         croak ":alias needs an argument in charnames";
 718       my $alias = shift;
 719       if (ref $alias) {
 720         ref $alias eq "HASH" or
 721           croak "Only HASH reference supported as argument to :alias";
 722         alias ($alias);
 723         next;
 724       }
 725       if ($alias =~ m{:(\w+)$}) {
 726         $1 eq "full" || $1 eq "short" and
 727           croak ":alias cannot use existing pragma :$1 (reversed order?)";
 728         alias_file ($1) and $promote = 1;
 729         next;
 730       }
 731       alias_file ($alias);
 732       next;
 733     }
 734     if (substr($arg, 0, 1) eq ':' and ! ($arg eq ":full" || $arg eq ":short")) {
 735       warn "unsupported special '$arg' in charnames";
 736       next;
 737     }
 738     push @args, $arg;
 739   }
 740   @args == 0 && $promote and @args = (":full");
 741   @h{@args} = (1) x @args;
 742
 743   $^H{charnames_full} = delete $h{':full'} || 0;  # Don't leave undefined,
 744                                                   # as tested for in
 745                                                   # lookup_names
 746   $^H{charnames_short} = delete $h{':short'} || 0;
 747   my @scripts = map uc, keys %h;
 748
 749   ##
 750   ## If utf8? warnings are enabled, and some scripts were given,
 751   ## see if at least we can find one letter from each script.
 752   ##
 753   if (warnings::enabled('utf8') && @scripts) {
 754     $txt = do "unicore/Name.pl" unless $txt;
 755
 756     for my $script (@scripts) {
 757       if (not $txt =~ m/\t\t$script (?:CAPITAL |SMALL )?LETTER /) {
 758         warnings::warn('utf8',  "No such script: '$script'");
 759         $script = quotemeta $script;  # Escape it, for use in the re.
 760       }
 761     }
 762   }
 763
 764   # %^H gets stringified, so serialize it ourselves so can extract the
 765   # real data back later.
 766   $^H{charnames_stringified_ords} = join ",", %{$^H{charnames_ord_aliases}};
 767   $^H{charnames_stringified_names} = join ",", %{$^H{charnames_name_aliases}};
 768   $^H{charnames_stringified_inverse_ords} = join ",", %{$^H{charnames_inverse_ords}};
 769   $^H{charnames_scripts} = join "|", @scripts;  # Stringifiy them as a trie
 770 } # import
 771
 772 # Cache of already looked-up values.  This is set to only contain
 773 # official values, and user aliases can't override them, so scoping is
 774 # not an issue.
 775 my %viacode;
 776
 777 sub viacode {
 778
 779   # Returns the name of the code point argument
 780
 781   if (@_ != 1) {
 782     carp "charnames::viacode() expects one argument";
 783     return;
 784   }
 785
 786   my $arg = shift;
 787
 788   # This is derived from Unicode::UCD, where it is nearly the same as the
 789   # function _getcode(), but here it makes sure that even a hex argument
 790   # has the proper number of leading zeros, which is critical in
 791   # matching against $txt below
 792   # Must check if decimal first; see comments at that definition
 793   my $hex;
 794   if ($arg =~ $decimal_qr) {
 795     $hex = sprintf "%04X", $arg;
 796   } elsif ($arg =~ $hex_qr) {
 797     # Below is the line that differs from the _getcode() source
 798     $hex = sprintf "%04X", hex $1;
 799   } else {
 800     carp("unexpected arg \"$arg\" to charnames::viacode()");
 801     return;
 802   }
 803
 804   return $viacode{$hex} if exists $viacode{$hex};
 805
 806   # If the code point is above the max in the table, there's no point
 807   # looking through it.  Checking the length first is slightly faster
 808   if (length($hex) <= 5 || CORE::hex($hex) <= 0x10FFFF) {
 809     $txt = do "unicore/Name.pl" unless $txt;
 810
 811     # See if the name is algorithmically determinable.
 812     my $algorithmic = code_point_to_name_special(CORE::hex $hex);
 813     if (defined $algorithmic) {
 814       $viacode{$hex} = $algorithmic;
 815       return $algorithmic;
 816     }
 817
 818     # Return the official name, if exists.  It's unclear to me (khw) at
 819     # this juncture if it is better to return a user-defined override, so
 820     # leaving it as is for now.
 821     if ($txt =~ m/^$hex\t\t/m) {
 822
 823         # The name starts with the next character and goes up to the
 824         # next new-line.  Using capturing parentheses above instead of
 825         # @+ more than doubles the execution time in Perl 5.13
 826         $viacode{$hex} = substr($txt, $+[0], index($txt, "\n", $+[0]) - $+[0]);
 827         return $viacode{$hex};
 828     }
 829   }
 830
 831   # See if there is a user name for it, before giving up completely.
 832   # First get the scoped aliases, give up if have none.
 833   my $H_ref = (caller(0))[10];
 834   return if ! defined $H_ref
 835             || ! exists $H_ref->{charnames_stringified_inverse_ords};
 836
 837   my %code_point_aliases = split ',',
 838                           $H_ref->{charnames_stringified_inverse_ords};
 839   if (! exists $code_point_aliases{$hex}) {
 840     if (CORE::hex($hex) > 0x10FFFF) {
 841         carp "Unicode characters only allocated up to U+10FFFF (you asked for U+$hex)";
 842     }
 843     return;
 844   }
 845
 846   return $code_point_aliases{$hex};
 847 } # viacode
 848
 849 sub vianame
 850 {
 851   if (@_ != 1) {
 852     carp "charnames::vianame() expects one name argument";
 853     return ()
 854   }
 855
 856   # Looks up the character name and returns its ordinal if
 857   # found, undef otherwise.
 858
 859   my $arg = shift;
 860
 861   if ($arg =~ /^U\+([0-9a-fA-F]+)$/) {
 862
 863     # khw claims that this is bad.  The function should return either a
 864     # an ord or a chr for all inputs; not be bipolar.
 865     my $ord = CORE::hex $1;
 866     return chr $ord if $ord <= 255 || ! ((caller 0)[8] & $bytes::hint_bits);
 867     carp not_legal_use_bytes_msg($arg, $ord);
 868     return;
 869   }
 870
 871   return lookup_name($arg, (caller(0))[10]);
 872 } # vianame
 873
 874
 875 1;
 876 __END__
 877
 878 =head1 NAME
 879
 880 charnames - access to Unicode character names; define character names for C<\N{named}> string literal escapes
 881
 882 =head1 SYNOPSIS
 883
 884   use charnames ':full';
 885   print "\N{GREEK SMALL LETTER SIGMA} is called sigma.\n";
 886
 887   use charnames ':short';
 888   print "\N{greek:Sigma} is an upper-case sigma.\n";
 889
 890   use charnames qw(cyrillic greek);
 891   print "\N{sigma} is Greek sigma, and \N{be} is Cyrillic b.\n";
 892
 893   use charnames ":full", ":alias" => {
 894     e_ACUTE => "LATIN SMALL LETTER E WITH ACUTE",
 895     mychar => 0xE8000,  # Private use area
 896   };
 897   print "\N{e_ACUTE} is a small letter e with an acute.\n";
 898   print "\\N{mychar} allows me to name private use characters.\n";
 899
 900   use charnames ();
 901   print charnames::viacode(0x1234); # prints "ETHIOPIC SYLLABLE SEE"
 902   printf "%04X", charnames::vianame("GOTHIC LETTER AHSA"); # prints
 903                                                            # "10330"
 904
 905 =head1 DESCRIPTION
 906
 907 Pragma C<use charnames> is used to gain access to the names of the
 908 Unicode characters, and to allow you to define your own character names.
 909
 910 All forms of the pragma enable use of the
 911 L</charnames::vianame(I<name>)> function for run-time lookup of a
 912 character name to get its ordinal (code point), and the inverse
 913 function, L</charnames::viacode(I<code>)>.
 914
 915 Forms other than C<S<"use charnames ();">> enable the use of of
 916 C<\N{I<CHARNAME>}> sequences to compile a Unicode character into a
 917 string based on its name.
 918
 919 Note that C<\N{U+I<...>}>, where the I<...> is a hexadecimal number,
 920 also inserts a character into a string, but doesn't require the use of
 921 this pragma.  The character it inserts is the one whose code point
 922 (ordinal value) is equal to the number.  For example, C<"\N{U+263a}"> is
 923 the Unicode (white background, black foreground) smiley face; it doesn't
 924 require this pragma, whereas the equivalent, C<"\N{WHITE SMILING FACE}">
 925 does.
 926 Also, C<\N{I<...>}> can mean a regex quantifier instead of a character
 927 name, when the I<...> is a number (or comma separated pair of numbers;
 928 see L<perlreref/QUANTIFIERS>), and is not related to this pragma.
 929
 930 The C<charnames> pragma supports arguments C<:full>, C<:short>, script
 931 names and customized aliases.  If C<:full> is present, for expansion of
 932 C<\N{I<CHARNAME>}>, the string I<CHARNAME> is first looked up in the list of
 933 standard Unicode character names.  If C<:short> is present, and
 934 I<CHARNAME> has the form C<I<SCRIPT>:I<CNAME>>, then I<CNAME> is looked up
 935 as a letter in script I<SCRIPT>.  If C<use charnames> is used
 936 with script name arguments, then for C<\N{I<CHARNAME>}> the name
 937 I<CHARNAME> is looked up as a letter in the given scripts (in the
 938 specified order). Customized aliases can override these, and are explained in
 939 L</CUSTOM ALIASES>.
 940
 941 For lookup of I<CHARNAME> inside a given script I<SCRIPTNAME>
 942 this pragma looks for the names
 943
 944   SCRIPTNAME CAPITAL LETTER CHARNAME
 945   SCRIPTNAME SMALL LETTER CHARNAME
 946   SCRIPTNAME LETTER CHARNAME
 947
 948 in the table of standard Unicode names.  If I<CHARNAME> is lowercase,
 949 then the C<CAPITAL> variant is ignored, otherwise the C<SMALL> variant
 950 is ignored.
 951
 952 Note that C<\N{...}> is compile-time; it's a special form of string
 953 constant used inside double-quotish strings; this means that you cannot
 954 use variables inside the C<\N{...}>.  If you want similar run-time
 955 functionality, use L<charnames::vianame()|/charnames::vianame(I<name>)>.
 956
 957 For the C0 and C1 control characters (U+0000..U+001F, U+0080..U+009F)
 958 there are no official Unicode names but you can use instead the ISO 6429
 959 names (LINE FEED, ESCAPE, and so forth, and their abbreviations, LF,
 960 ESC, ...).  In Unicode 3.2 (as of Perl 5.8) some naming changes took
 961 place, and ISO 6429 was updated, see L</ALIASES>.
 962
 963 If the input name is unknown, C<\N{NAME}> raises a warning and
 964 substitutes the Unicode REPLACEMENT CHARACTER (U+FFFD).
 965
 966 It is a fatal error if C<use bytes> is in effect and the input name is
 967 that of a character that won't fit into a byte (i.e., whose ordinal is
 968 above 255).
 969
 970 Otherwise, any string that includes a C<\N{I<charname>}> or
 971 C<S<\N{U+I<code point>}>> will automatically have Unicode semantics (see
 972 L<perlunicode/Byte and Character Semantics>).
 973
 974 =head1 ALIASES
 975
 976 A few aliases have been defined for convenience: instead of having
 977 to use the official names
 978
 979     LINE FEED (LF)
 980     FORM FEED (FF)
 981     CARRIAGE RETURN (CR)
 982     NEXT LINE (NEL)
 983
 984 (yes, with parentheses), one can use
 985
 986     LINE FEED
 987     FORM FEED
 988     CARRIAGE RETURN
 989     NEXT LINE
 990     LF
 991     FF
 992     CR
 993     NEL
 994
 995 All the other standard abbreviations for the controls, such as C<ACK> for
 996 C<ACKNOWLEDGE> also can be used.
 997
 998 One can also use
 999
1000     BYTE ORDER MARK
1001     BOM
1002
1003 and these abbreviations
1004
1005     Abbreviation        Full Name
1006
1007     CGJ                 COMBINING GRAPHEME JOINER
1008     FVS1                MONGOLIAN FREE VARIATION SELECTOR ONE
1009     FVS2                MONGOLIAN FREE VARIATION SELECTOR TWO
1010     FVS3                MONGOLIAN FREE VARIATION SELECTOR THREE
1011     LRE                 LEFT-TO-RIGHT EMBEDDING
1012     LRM                 LEFT-TO-RIGHT MARK
1013     LRO                 LEFT-TO-RIGHT OVERRIDE
1014     MMSP                MEDIUM MATHEMATICAL SPACE
1015     MVS                 MONGOLIAN VOWEL SEPARATOR
1016     NBSP                NO-BREAK SPACE
1017     NNBSP               NARROW NO-BREAK SPACE
1018     PDF                 POP DIRECTIONAL FORMATTING
1019     RLE                 RIGHT-TO-LEFT EMBEDDING
1020     RLM                 RIGHT-TO-LEFT MARK
1021     RLO                 RIGHT-TO-LEFT OVERRIDE
1022     SHY                 SOFT HYPHEN
1023     VS1                 VARIATION SELECTOR-1
1024     .
1025     .
1026     .
1027     VS256               VARIATION SELECTOR-256
1028     WJ                  WORD JOINER
1029     ZWJ                 ZERO WIDTH JOINER
1030     ZWNJ                ZERO WIDTH NON-JOINER
1031     ZWSP                ZERO WIDTH SPACE
1032
1033 For backward compatibility one can use the old names for
1034 certain C0 and C1 controls
1035
1036     old                         new
1037
1038     FILE SEPARATOR              INFORMATION SEPARATOR FOUR
1039     GROUP SEPARATOR             INFORMATION SEPARATOR THREE
1040     HORIZONTAL TABULATION       CHARACTER TABULATION
1041     HORIZONTAL TABULATION SET   CHARACTER TABULATION SET
1042     HORIZONTAL TABULATION WITH JUSTIFICATION    CHARACTER TABULATION
1043                                                 WITH JUSTIFICATION
1044     PARTIAL LINE DOWN           PARTIAL LINE FORWARD
1045     PARTIAL LINE UP             PARTIAL LINE BACKWARD
1046     RECORD SEPARATOR            INFORMATION SEPARATOR TWO
1047     REVERSE INDEX               REVERSE LINE FEED
1048     UNIT SEPARATOR              INFORMATION SEPARATOR ONE
1049     VERTICAL TABULATION         LINE TABULATION
1050     VERTICAL TABULATION SET     LINE TABULATION SET
1051
1052 but the old names in addition to giving the character
1053 will also give a warning about being deprecated.
1054
1055 And finally, certain published variants are usable, including some for
1056 controls that have no Unicode names:
1057
1058     name                                   character
1059
1060     END OF PROTECTED AREA                  END OF GUARDED AREA, U+0097
1061     HIGH OCTET PRESET                      U+0081
1062     HOP                                    U+0081
1063     IND                                    U+0084
1064     INDEX                                  U+0084
1065     PAD                                    U+0080
1066     PADDING CHARACTER                      U+0080
1067     PRIVATE USE 1                          PRIVATE USE ONE, U+0091
1068     PRIVATE USE 2                          PRIVATE USE TWO, U+0092
1069     SGC                                    U+0099
1070     SINGLE GRAPHIC CHARACTER INTRODUCER    U+0099
1071     SINGLE-SHIFT 2                         SINGLE SHIFT TWO, U+008E
1072     SINGLE-SHIFT 3                         SINGLE SHIFT THREE, U+008F
1073     START OF PROTECTED AREA                START OF GUARDED AREA, U+0096
1074
1075 =head1 CUSTOM ALIASES
1076
1077 You can add customized aliases to standard (C<:full>) Unicode naming
1078 conventions.  The aliases override any standard definitions, so, if
1079 you're twisted enough, you can change C<"\N{LATIN CAPITAL LETTER A}"> to
1080 mean C<"B">, etc.
1081
1082 Note that an alias should not be something that is a legal curly
1083 brace-enclosed quantifier (see L<perlreref/QUANTIFIERS>).  For example
1084 C<\N{123}> means to match 123 non-newline characters, and is not treated as a
1085 charnames alias.  Aliases are discouraged from beginning with anything
1086 other than an alphabetic character and from containing anything other
1087 than alphanumerics, spaces, dashes, parentheses, and underscores.
1088 Currently they must be ASCII.
1089
1090 An alias can map to either an official Unicode character name or to a
1091 numeric code point (ordinal).  The latter is useful for assigning names
1092 to code points in Unicode private use areas such as U+E800 through
1093 U+F8FF.
1094 A numeric code point must be a non-negative integer or a string beginning
1095 with C<"U+"> or C<"0x"> with the remainder considered to be a
1096 hexadecimal integer.  A literal numeric constant must be unsigned; it
1097 will be interpreted as hex if it has a leading zero or contains
1098 non-decimal hex digits; otherwise it will be interpreted as decimal.
1099
1100 Aliases are added either by the use of anonymous hashes:
1101
1102     use charnames ":alias" => {
1103         e_ACUTE => "LATIN SMALL LETTER E WITH ACUTE",
1104         mychar1 => 0xE8000,
1105         };
1106     my $str = "\N{e_ACUTE}";
1107
1108 or by using a file containing aliases:
1109
1110     use charnames ":alias" => "pro";
1111
1112 will try to read C<"unicore/pro_alias.pl"> from the C<@INC> path. This
1113 file should return a list in plain perl:
1114
1115     (
1116     A_GRAVE         => "LATIN CAPITAL LETTER A WITH GRAVE",
1117     A_CIRCUM        => "LATIN CAPITAL LETTER A WITH CIRCUMFLEX",
1118     A_DIAERES       => "LATIN CAPITAL LETTER A WITH DIAERESIS",
1119     A_TILDE         => "LATIN CAPITAL LETTER A WITH TILDE",
1120     A_BREVE         => "LATIN CAPITAL LETTER A WITH BREVE",
1121     A_RING          => "LATIN CAPITAL LETTER A WITH RING ABOVE",
1122     A_MACRON        => "LATIN CAPITAL LETTER A WITH MACRON",
1123     mychar2         => "U+E8001",
1124     );
1125
1126 Both these methods insert C<":full"> automatically as the first argument (if no
1127 other argument is given), and you can give the C<":full"> explicitly as
1128 well, like
1129
1130     use charnames ":full", ":alias" => "pro";
1131
1132 =head1 charnames::viacode(I<code>)
1133
1134 Returns the full name of the character indicated by the numeric code.
1135 For example,
1136
1137     print charnames::viacode(0x2722);
1138
1139 prints "FOUR TEARDROP-SPOKED ASTERISK".
1140
1141 The name returned is the official name for the code point, if
1142 available, otherwise your custom alias for it.  This means that your
1143 alias will only be returned for code points that don't have an official
1144 Unicode name (nor Unicode version 1 name), such as private use code
1145 points, and the 4 control characters U+0080, U+0081, U+0084, and U+0099.
1146 If you define more than one name for the code point, it is indeterminate
1147 which one will be returned.
1148
1149 The function returns C<undef> if no name is known for the code point.
1150 In Unicode the proper name of these is the empty string, which
1151 C<undef> stringifies to.  (If you ask for a code point past the legal
1152 Unicode maximum of U+10FFFF that you haven't assigned an alias to, you
1153 get C<undef> plus a warning.)
1154
1155 The input number must be a non-negative integer or a string beginning
1156 with C<"U+"> or C<"0x"> with the remainder considered to be a
1157 hexadecimal integer.  A literal numeric constant must be unsigned; it
1158 will be interpreted as hex if it has a leading zero or contains
1159 non-decimal hex digits; otherwise it will be interpreted as decimal.
1160
1161 Notice that the name returned for of U+FEFF is "ZERO WIDTH NO-BREAK
1162 SPACE", not "BYTE ORDER MARK".
1163
1164 =head1 charnames::vianame(I<name>)
1165
1166 Returns the code point indicated by the name.
1167 For example,
1168
1169     printf "%04X", charnames::vianame("FOUR TEARDROP-SPOKED ASTERISK");
1170
1171 prints "2722".
1172
1173 C<vianame> takes the identical inputs that C<\N{...}> does under the
1174 L<C<:full> option|/DESCRIPTION> to C<charnames>.  In addition, any other
1175 options for the controlling C<"use charnames"> in the same scope apply,
1176 like any L<script list, C<:short> option|/DESCRIPTION>, or L<custom
1177 aliases|/CUSTOM ALIASES> you may have defined.
1178
1179 There are just a few differences.  The main one is that under
1180 most (see L</BUGS> for the others) circumstances, vianame returns
1181 an ord, whereas C<\\N{...}> is seamlessly placed as a chr into the
1182 string in which it appears.  This leads to a second difference.
1183 Since an ord is returned, it can be that of any character, even one
1184 that isn't legal under the C<S<use bytes>> pragma.
1185
1186 The final difference is that if the input name is unknown C<vianame>
1187 returns C<undef> instead of the REPLACEMENT CHARACTER, and it does not
1188 raise a warning message.
1189
1190 =head1 CUSTOM TRANSLATORS
1191
1192 The mechanism of translation of C<\N{...}> escapes is general and not
1193 hardwired into F<charnames.pm>.  A module can install custom
1194 translations (inside the scope which C<use>s the module) with the
1195 following magic incantation:
1196
1197     sub import {
1198         shift;
1199         $^H{charnames} = \&translator;
1200     }
1201
1202 Here translator() is a subroutine which takes I<CHARNAME> as an
1203 argument, and returns text to insert into the string instead of the
1204 C<\N{I<CHARNAME>}> escape.  Since the text to insert should be different
1205 in C<bytes> mode and out of it, the function should check the current
1206 state of C<bytes>-flag as in:
1207
1208     use bytes ();                      # for $bytes::hint_bits
1209     sub translator {
1210         if ($^H & $bytes::hint_bits) {
1211             return bytes_translator(@_);
1212         }
1213         else {
1214             return utf8_translator(@_);
1215         }
1216     }
1217
1218 See L</CUSTOM ALIASES> above for restrictions on I<CHARNAME>.
1219
1220 Of course, C<vianame> and C<viacode> would need to be overridden as
1221 well.
1222
1223 =head1 BUGS
1224
1225 vianame returns a chr if the input name is of the form C<U+...>, and an ord
1226 otherwise.  It is proposed to change this to always return an ord.  Send email
1227 to C<perl5-porters@perl.org> to comment on this proposal.  If S<C<use
1228 bytes>> is in effect when a chr is returned, and if that chr won't fit
1229 into a byte, C<undef> is returned instead.
1230
1231 Names must be ASCII characters only, which means that you are out of luck if
1232 you want to create aliases in a language where some or all the characters of
1233 the desired aliases are non-ASCII.
1234
1235 Unicode standard named sequences are not recognized, such as
1236 C<LATIN CAPITAL LETTER A WITH MACRON AND GRAVE>
1237 (which should mean C<LATIN CAPITAL LETTER A WITH MACRON> with an additional
1238 C<COMBINING GRAVE ACCENT>).
1239
1240 Since evaluation of the translation function (see L</CUSTOM
1241 TRANSLATORS>) happens in the middle of compilation (of a string
1242 literal), the translation function should not do any C<eval>s or
1243 C<require>s.  This restriction should be lifted (but is low priority) in
1244 a future version of Perl.
1245
1246 =cut
1247
1248 # ex: set ts=8 sts=2 sw=2 et: