lib/charnames.pm

   1 package charnames;
   2 use strict;
   3 use warnings;
   4 use File::Spec;
   5 our $VERSION = '1.11';
   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 my %user_name_aliases = (
 403                 # User defined aliases. Even more convenient :)
 404                 # These are the ones that resolved to names
 405             );
 406
 407 my %user_numeric_aliases = (
 408                 # And these resolve directly to code points.
 409             );
 410 my %inverse_user_aliases = (
 411                 # Map from code point to name
 412             );
 413 my $txt;
 414 my $decimal_qr = qr/^[1-9]\d*$/;
 415
 416 # Returns the hex number in $1.
 417 my $hex_qr = qr/^(?:[Uu]\+|0[xX])?([[:xdigit:]]+)$/;
 418
 419 sub croak
 420 {
 421   require Carp; goto &Carp::croak;
 422 } # croak
 423
 424 sub carp
 425 {
 426   require Carp; goto &Carp::carp;
 427 } # carp
 428
 429 sub alias (@)
 430 {
 431   my $alias = ref $_[0] ? $_[0] : { @_ };
 432   foreach my $name (keys %$alias) {
 433     my $value = $alias->{$name};
 434     if ($value =~ $decimal_qr) {
 435         $user_numeric_aliases{$name} = $value;
 436
 437         # Use a canonical form.
 438         $inverse_user_aliases{sprintf("%04X", $value)} = $name;
 439     }
 440     elsif ($value =~ $hex_qr) {
 441         my $decimal = CORE::hex $1;
 442         $user_numeric_aliases{$name} = $decimal;
 443
 444         # Must convert to decimal and back to guarantee canonical form
 445         $inverse_user_aliases{sprintf("%04X", $decimal)} = $name;
 446     }
 447     else {
 448         $user_name_aliases{$name} = $value;
 449     }
 450   }
 451 } # alias
 452
 453 sub not_legal_use_bytes_msg {
 454   my ($name, $ord) = @_;
 455   return sprintf("Character 0x%04x with name '$name' is above 0xFF with 'use bytes' in effect", $ord);
 456 }
 457
 458 sub alias_file ($)
 459 {
 460   my ($arg, $file) = @_;
 461   if (-f $arg && File::Spec->file_name_is_absolute ($arg)) {
 462     $file = $arg;
 463   }
 464   elsif ($arg =~ m/^\w+$/) {
 465     $file = "unicore/${arg}_alias.pl";
 466   }
 467   else {
 468     croak "Charnames alias files can only have identifier characters";
 469   }
 470   if (my @alias = do $file) {
 471     @alias == 1 && !defined $alias[0] and
 472       croak "$file cannot be used as alias file for charnames";
 473     @alias % 2 and
 474       croak "$file did not return a (valid) list of alias pairs";
 475     alias (@alias);
 476     return (1);
 477   }
 478   0;
 479 } # alias_file
 480
 481
 482 sub lookup_name {
 483   my $name = shift;
 484   my $runtime = shift;  # compile vs run time
 485
 486   # Finds the ordinal of a character name, first in the aliases, then in
 487   # the large table.  If not found, returns undef if runtime; complains
 488   # and returns the Unicode replacement if compile.
 489   # This is not optimized in any way yet
 490
 491   my $ord;
 492
 493   # User alias should be checked first or else can't override ours, and if we
 494   # add any, could conflict with theirs.
 495   if (exists $user_numeric_aliases{$name}) {
 496     $ord = $user_numeric_aliases{$name};
 497   }
 498   elsif (exists $user_name_aliases{$name}) {
 499     $name = $user_name_aliases{$name};
 500   }
 501   elsif (exists $system_aliases{$name}) {
 502     $ord = $system_aliases{$name};
 503   }
 504   elsif (exists $deprecated_aliases{$name}) {
 505     require warnings;
 506     warnings::warnif('deprecated', "Unicode character name \"$name\" is deprecated, use \"" . viacode($deprecated_aliases{$name}) . "\" instead");
 507     $ord = $deprecated_aliases{$name};
 508   }
 509
 510   my @off;
 511
 512   if (! defined $ord) {
 513     ## Suck in the code/name list as a big string.
 514     ## Lines look like:
 515     ##     "0052\t\tLATIN CAPITAL LETTER R\n"
 516     $txt = do "unicore/Name.pl" unless $txt;
 517
 518     ## @off will hold the index into the code/name string of the start and
 519     ## end of the name as we find it.
 520
 521     ## If :full, look for the name exactly; runtime implies full
 522     if (($runtime || $^H{charnames_full}) && $txt =~ /\t\t\Q$name\E$/m) {
 523       @off = ($-[0] + 2, $+[0]);    # The 2 is for the 2 tabs
 524     }
 525
 526     ## If we didn't get above, and :short allowed, look for the short name.
 527     ## The short name is like "greek:Sigma"
 528     unless (@off) {
 529       if (($runtime || $^H{charnames_short}) && $name =~ /^(.+?):(.+)/s) {
 530        my ($script, $cname) = ($1, $2);
 531        my $case = $cname =~ /[[:upper:]]/ ? "CAPITAL" : "SMALL";
 532        if ($txt =~ m/\t\t\U$script\E (?:$case )?LETTER \U\Q$cname\E$/m) {
 533          @off = ($-[0] + 2, $+[0]);
 534        }
 535       }
 536     }
 537
 538     ## If we still don't have it, check for the name among the loaded
 539     ## scripts.
 540     if (! $runtime && not @off) {
 541       my $case = $name =~ /[[:upper:]]/ ? "CAPITAL" : "SMALL";
 542       for my $script (@{$^H{charnames_scripts}}) {
 543         if ($txt =~ m/\t\t$script (?:$case )?LETTER \U\Q$name\E$/m) {
 544           @off = ($-[0] + 2, $+[0]);
 545           last;
 546         }
 547       }
 548     }
 549
 550     ## If we don't have it by now, give up.
 551     unless (@off) {
 552       return if $runtime;
 553       carp "Unknown charname '$name'";
 554       return "\x{FFFD}";
 555     }
 556
 557     ##
 558     ## Now know where in the string the name starts.
 559     ## The code, in hex, is before that.
 560     ##
 561     ## The code can be 4-6 characters long, so we've got to sort of
 562     ## go look for it, just after the newline that comes before $off[0].
 563     ##
 564     ## This would be much easier if unicore/Name.pl had info in
 565     ## a name/code order, instead of code/name order.
 566     ##
 567     ## The +1 after the rindex() is to skip past the newline we're finding,
 568     ## or, if the rindex() fails, to put us to an offset of zero.
 569     ##
 570     my $hexstart = rindex($txt, "\n", $off[0]) + 1;
 571
 572     ## we know where it starts, so turn into number -
 573     ## the ordinal for the char.
 574     $ord = CORE::hex substr($txt, $hexstart, $off[0] - 2 - $hexstart);
 575   }
 576
 577   return $ord if $runtime || $ord <= 255 || ! ($^H & $bytes::hint_bits);
 578
 579   # Here is compile time, "use bytes" is in effect, and the character
 580   # won't fit in a byte
 581
 582
 583   # Get the official name if have one for the message
 584   $name = substr($txt, $off[0], $off[1] - $off[0]) if @off;
 585
 586   croak not_legal_use_bytes_msg($name, $ord);
 587 } # lookup_name
 588
 589 sub charnames {
 590   my $name = shift;
 591
 592   # For \N{...}.  Looks up the character name and returns its ordinal if
 593   # found, undef otherwise.  If not in 'use bytes', forces into utf8
 594
 595   my $ord = lookup_name($name, 0); # 0 means compile-time
 596   return unless defined $ord;
 597   return chr $ord if $^H & $bytes::hint_bits;
 598
 599   no warnings 'utf8'; # allow even illegal characters
 600   return pack "U", $ord;
 601 }
 602
 603 sub import
 604 {
 605   shift; ## ignore class name
 606
 607   if (not @_) {
 608     carp("`use charnames' needs explicit imports list");
 609   }
 610   $^H{charnames} = \&charnames ;
 611
 612   ##
 613   ## fill %h keys with our @_ args.
 614   ##
 615   my ($promote, %h, @args) = (0);
 616   while (my $arg = shift) {
 617     if ($arg eq ":alias") {
 618       @_ or
 619         croak ":alias needs an argument in charnames";
 620       my $alias = shift;
 621       if (ref $alias) {
 622         ref $alias eq "HASH" or
 623           croak "Only HASH reference supported as argument to :alias";
 624         alias ($alias);
 625         next;
 626       }
 627       if ($alias =~ m{:(\w+)$}) {
 628         $1 eq "full" || $1 eq "short" and
 629           croak ":alias cannot use existing pragma :$1 (reversed order?)";
 630         alias_file ($1) and $promote = 1;
 631         next;
 632       }
 633       alias_file ($alias);
 634       next;
 635     }
 636     if (substr($arg, 0, 1) eq ':' and ! ($arg eq ":full" || $arg eq ":short")) {
 637       warn "unsupported special '$arg' in charnames";
 638       next;
 639     }
 640     push @args, $arg;
 641   }
 642   @args == 0 && $promote and @args = (":full");
 643   @h{@args} = (1) x @args;
 644
 645   $^H{charnames_full} = delete $h{':full'};
 646   $^H{charnames_short} = delete $h{':short'};
 647   $^H{charnames_scripts} = [map uc, keys %h];
 648
 649   ##
 650   ## If utf8? warnings are enabled, and some scripts were given,
 651   ## see if at least we can find one letter of each script.
 652   ##
 653   if (warnings::enabled('utf8') && @{$^H{charnames_scripts}}) {
 654     $txt = do "unicore/Name.pl" unless $txt;
 655
 656     for my $script (@{$^H{charnames_scripts}}) {
 657       if (not $txt =~ m/\t\t$script (?:CAPITAL |SMALL )?LETTER /) {
 658         warnings::warn('utf8',  "No such script: '$script'");
 659       }
 660     }
 661   }
 662 } # import
 663
 664 my %viacode;    # Cache of already-found codes
 665
 666 sub viacode {
 667
 668   # Returns the name of the code point argument
 669
 670   if (@_ != 1) {
 671     carp "charnames::viacode() expects one argument";
 672     return;
 673   }
 674
 675   my $arg = shift;
 676
 677   # This is derived from Unicode::UCD, where it is nearly the same as the
 678   # function _getcode(), but here it makes sure that even a hex argument
 679   # has the proper number of leading zeros, which is critical in
 680   # matching against $txt below
 681   my $hex;
 682   if ($arg =~ $decimal_qr) {
 683     $hex = sprintf "%04X", $arg;
 684   } elsif ($arg =~ $hex_qr) {
 685     # Below is the line that differs from the _getcode() source
 686     $hex = sprintf "%04X", hex $1;
 687   } else {
 688     carp("unexpected arg \"$arg\" to charnames::viacode()");
 689     return;
 690   }
 691
 692   return $viacode{$hex} if exists $viacode{$hex};
 693
 694   # If the code point is above the max in the table, there's no point
 695   # looking through it.  Checking the length first is slightly faster
 696   if (length($hex) <= 5 || CORE::hex($hex) <= 0x10FFFF) {
 697     $txt = do "unicore/Name.pl" unless $txt;
 698
 699     # Return the official name, if exists.  It's unclear to me (khw) at
 700     # this juncture if it is better to return a user-defined override, so
 701     # leaving it as is for now.
 702     if ($txt =~ m/^$hex\t\t(.+)/m) {
 703         $viacode{$hex} = $1;
 704         return $1;
 705     }
 706   }
 707
 708   # See if there is a user name for it, before giving up completely.
 709   if (! exists $inverse_user_aliases{$hex}) {
 710     if (CORE::hex($hex) > 0x10FFFF) {
 711         carp "Unicode characters only allocated up to U+10FFFF (you asked for U+$hex)";
 712     }
 713     return;
 714   }
 715
 716   $viacode{$hex} = $inverse_user_aliases{$hex};
 717   return $inverse_user_aliases{$hex};
 718 } # viacode
 719
 720 my %vianame;    # Cache of already-found names
 721
 722 sub vianame
 723 {
 724   if (@_ != 1) {
 725     carp "charnames::vianame() expects one name argument";
 726     return ()
 727   }
 728
 729   # Looks up the character name and returns its ordinal if
 730   # found, undef otherwise.
 731
 732   my $arg = shift;
 733
 734   if ($arg =~ /^U\+([0-9a-fA-F]+)$/) {
 735
 736     # khw claims that this is bad.  The function should return either a
 737     # an ord or a chr for all inputs; not be bipolar.  Also, under 'use
 738     # bytes', can create a chr above 255.
 739     my $ord = CORE::hex $1;
 740     return chr $ord if $ord <= 255 || ! ((caller 0)[8] & $bytes::hint_bits);
 741     carp not_legal_use_bytes_msg($arg, $ord);
 742     return;
 743   }
 744
 745   if (! exists $vianame{$arg}) {
 746     $vianame{$arg} = lookup_name($arg, 1); # 1 means run-time
 747   }
 748
 749   return $vianame{$arg};
 750 } # vianame
 751
 752
 753 1;
 754 __END__
 755
 756 =head1 NAME
 757
 758 charnames - access to Unicode character names and define character names for C<\N{named}> string literal escapes
 759
 760 =head1 SYNOPSIS
 761
 762   use charnames ':full';
 763   print "\N{GREEK SMALL LETTER SIGMA} is called sigma.\n";
 764
 765   use charnames ':short';
 766   print "\N{greek:Sigma} is an upper-case sigma.\n";
 767
 768   use charnames qw(cyrillic greek);
 769   print "\N{sigma} is Greek sigma, and \N{be} is Cyrillic b.\n";
 770
 771   use charnames ":full", ":alias" => {
 772     e_ACUTE => "LATIN SMALL LETTER E WITH ACUTE",
 773     mychar => 0xE8000,  # Private use area
 774   };
 775   print "\N{e_ACUTE} is a small letter e with an acute.\n";
 776   print "\\N{mychar} allows me to name private use characters.\n";
 777
 778   use charnames ();
 779   print charnames::viacode(0x1234); # prints "ETHIOPIC SYLLABLE SEE"
 780   printf "%04X", charnames::vianame("GOTHIC LETTER AHSA"); # prints
 781                                                            # "10330"
 782
 783 =head1 DESCRIPTION
 784
 785 Pragma C<use charnames> is used to gain access to the names of the
 786 Unicode characters, and to allow you to define your own character names.
 787
 788 All forms of the pragma enable use of the
 789 L</charnames::vianame(I<name>)> function for run-time lookup of a
 790 character name to get its ordinal (code point), and the inverse
 791 function, L</charnames::viacode(I<code>)>.
 792
 793 Forms other than C<S<"use charnames ();">> enable the use of of
 794 C<\N{I<CHARNAME>}> sequences to compile a Unicode character into a
 795 string based on its name.
 796
 797 Note that C<\N{U+I<...>}>, where the I<...> is a hexadecimal number,
 798 also inserts a character into a string, but doesn't require the use of
 799 this pragma.  The character it inserts is the one whose code point
 800 (ordinal value) is equal to the number.  For example, C<"\N{U+263a}"> is
 801 the Unicode (white background, black foreground) smiley face; it doesn't
 802 require this pragma, whereas the equivalent, C<"\N{WHITE SMILING FACE}">
 803 does.
 804 Also, C<\N{I<...>}> can mean a regex quantifier instead of a character
 805 name, when the I<...> is a number (or comma separated pair of numbers;
 806 see L<perlreref/QUANTIFIERS>), and is not related to this pragma.
 807
 808 The C<charnames> pragma supports arguments C<:full>, C<:short>, script
 809 names and customized aliases.  If C<:full> is present, for expansion of
 810 C<\N{I<CHARNAME>}>, the string I<CHARNAME> is first looked up in the list of
 811 standard Unicode character names.  If C<:short> is present, and
 812 I<CHARNAME> has the form C<I<SCRIPT>:I<CNAME>>, then I<CNAME> is looked up
 813 as a letter in script I<SCRIPT>.  If C<use charnames> is used
 814 with script name arguments, then for C<\N{I<CHARNAME>}> the name
 815 I<CHARNAME> is looked up as a letter in the given scripts (in the
 816 specified order). Customized aliases can override these, and are explained in
 817 L</CUSTOM ALIASES>.
 818
 819 For lookup of I<CHARNAME> inside a given script I<SCRIPTNAME>
 820 this pragma looks for the names
 821
 822   SCRIPTNAME CAPITAL LETTER CHARNAME
 823   SCRIPTNAME SMALL LETTER CHARNAME
 824   SCRIPTNAME LETTER CHARNAME
 825
 826 in the table of standard Unicode names.  If I<CHARNAME> is lowercase,
 827 then the C<CAPITAL> variant is ignored, otherwise the C<SMALL> variant
 828 is ignored.
 829
 830 Note that C<\N{...}> is compile-time; it's a special form of string
 831 constant used inside double-quotish strings; this means that you cannot
 832 use variables inside the C<\N{...}>.  If you want similar run-time
 833 functionality, use L<charnames::vianame()|/charnames::vianame(I<name>)>.
 834
 835 For the C0 and C1 control characters (U+0000..U+001F, U+0080..U+009F)
 836 there are no official Unicode names but you can use instead the ISO 6429
 837 names (LINE FEED, ESCAPE, and so forth, and their abbreviations, LF,
 838 ESC, ...).  In Unicode 3.2 (as of Perl 5.8) some naming changes took
 839 place, and ISO 6429 was updated, see L</ALIASES>.
 840
 841 If the input name is unknown, C<\N{NAME}> raises a warning and
 842 substitutes the Unicode REPLACEMENT CHARACTER (U+FFFD).
 843
 844 It is a fatal error if C<use bytes> is in effect and the input name is
 845 that of a character that won't fit into a byte (i.e., whose ordinal is
 846 above 255).
 847
 848 Otherwise, any string that includes a C<\N{I<charname>}> or
 849 C<S<\N{U+I<code point>}>> will automatically have Unicode semantics (see
 850 L<perlunicode/Byte and Character Semantics>).
 851
 852 =head1 ALIASES
 853
 854 A few aliases have been defined for convenience: instead of having
 855 to use the official names
 856
 857     LINE FEED (LF)
 858     FORM FEED (FF)
 859     CARRIAGE RETURN (CR)
 860     NEXT LINE (NEL)
 861
 862 (yes, with parentheses), one can use
 863
 864     LINE FEED
 865     FORM FEED
 866     CARRIAGE RETURN
 867     NEXT LINE
 868     LF
 869     FF
 870     CR
 871     NEL
 872
 873 All the other standard abbreviations for the controls, such as C<ACK> for
 874 C<ACKNOWLEDGE> also can be used.
 875
 876 One can also use
 877
 878     BYTE ORDER MARK
 879     BOM
 880
 881 and these abbreviations
 882
 883     Abbreviation        Full Name
 884
 885     CGJ                 COMBINING GRAPHEME JOINER
 886     FVS1                MONGOLIAN FREE VARIATION SELECTOR ONE
 887     FVS2                MONGOLIAN FREE VARIATION SELECTOR TWO
 888     FVS3                MONGOLIAN FREE VARIATION SELECTOR THREE
 889     LRE                 LEFT-TO-RIGHT EMBEDDING
 890     LRM                 LEFT-TO-RIGHT MARK
 891     LRO                 LEFT-TO-RIGHT OVERRIDE
 892     MMSP                MEDIUM MATHEMATICAL SPACE
 893     MVS                 MONGOLIAN VOWEL SEPARATOR
 894     NBSP                NO-BREAK SPACE
 895     NNBSP               NARROW NO-BREAK SPACE
 896     PDF                 POP DIRECTIONAL FORMATTING
 897     RLE                 RIGHT-TO-LEFT EMBEDDING
 898     RLM                 RIGHT-TO-LEFT MARK
 899     RLO                 RIGHT-TO-LEFT OVERRIDE
 900     SHY                 SOFT HYPHEN
 901     VS1                 VARIATION SELECTOR-1
 902     .
 903     .
 904     .
 905     VS256               VARIATION SELECTOR-256
 906     WJ                  WORD JOINER
 907     ZWJ                 ZERO WIDTH JOINER
 908     ZWNJ                ZERO WIDTH NON-JOINER
 909     ZWSP                ZERO WIDTH SPACE
 910
 911 For backward compatibility one can use the old names for
 912 certain C0 and C1 controls
 913
 914     old                         new
 915
 916     FILE SEPARATOR              INFORMATION SEPARATOR FOUR
 917     GROUP SEPARATOR             INFORMATION SEPARATOR THREE
 918     HORIZONTAL TABULATION       CHARACTER TABULATION
 919     HORIZONTAL TABULATION SET   CHARACTER TABULATION SET
 920     HORIZONTAL TABULATION WITH JUSTIFICATION    CHARACTER TABULATION
 921                                                 WITH JUSTIFICATION
 922     PARTIAL LINE DOWN           PARTIAL LINE FORWARD
 923     PARTIAL LINE UP             PARTIAL LINE BACKWARD
 924     RECORD SEPARATOR            INFORMATION SEPARATOR TWO
 925     REVERSE INDEX               REVERSE LINE FEED
 926     UNIT SEPARATOR              INFORMATION SEPARATOR ONE
 927     VERTICAL TABULATION         LINE TABULATION
 928     VERTICAL TABULATION SET     LINE TABULATION SET
 929
 930 but the old names in addition to giving the character
 931 will also give a warning about being deprecated.
 932
 933 And finally, certain published variants are usable, including some for
 934 controls that have no Unicode names:
 935
 936     name                                   character
 937
 938     END OF PROTECTED AREA                  END OF GUARDED AREA, U+0097
 939     HIGH OCTET PRESET                      U+0081
 940     HOP                                    U+0081
 941     IND                                    U+0084
 942     INDEX                                  U+0084
 943     PAD                                    U+0080
 944     PADDING CHARACTER                      U+0080
 945     PRIVATE USE 1                          PRIVATE USE ONE, U+0091
 946     PRIVATE USE 2                          PRIVATE USE TWO, U+0092
 947     SGC                                    U+0099
 948     SINGLE GRAPHIC CHARACTER INTRODUCER    U+0099
 949     SINGLE-SHIFT 2                         SINGLE SHIFT TWO, U+008E
 950     SINGLE-SHIFT 3                         SINGLE SHIFT THREE, U+008F
 951     START OF PROTECTED AREA                START OF GUARDED AREA, U+0096
 952
 953 =head1 CUSTOM ALIASES
 954
 955 You can add customized aliases to standard (C<:full>) Unicode naming
 956 conventions.  The aliases override any standard definitions, so, if
 957 you're twisted enough, you can change C<"\N{LATIN CAPITAL LETTER A}"> to
 958 mean C<"B">, etc.
 959
 960 Note that an alias should not be something that is a legal curly
 961 brace-enclosed quantifier (see L<perlreref/QUANTIFIERS>).  For example
 962 C<\N{123}> means to match 123 non-newline characters, and is not treated as a
 963 charnames alias.  Aliases are discouraged from beginning with anything
 964 other than an alphabetic character and from containing anything other
 965 than alphanumerics, spaces, dashes, parentheses, and underscores.
 966 Currently they must be ASCII.
 967
 968 An alias can map to either an official Unicode character name or to a
 969 numeric code point (ordinal).  The latter is useful for assigning names
 970 to code points in Unicode private use areas such as U+E800 through
 971 U+F8FF.  The number must look like an unsigned decimal integer, or a
 972 hexadecimal constant beginning with C<0x>, or C<U+>.
 973
 974 Aliases are added either by the use of anonymous hashes:
 975
 976     use charnames ":alias" => {
 977         e_ACUTE => "LATIN SMALL LETTER E WITH ACUTE",
 978         mychar1 => 0xE8000,
 979         };
 980     my $str = "\N{e_ACUTE}";
 981
 982 or by using a file containing aliases:
 983
 984     use charnames ":alias" => "pro";
 985
 986 will try to read C<"unicore/pro_alias.pl"> from the C<@INC> path. This
 987 file should return a list in plain perl:
 988
 989     (
 990     A_GRAVE         => "LATIN CAPITAL LETTER A WITH GRAVE",
 991     A_CIRCUM        => "LATIN CAPITAL LETTER A WITH CIRCUMFLEX",
 992     A_DIAERES       => "LATIN CAPITAL LETTER A WITH DIAERESIS",
 993     A_TILDE         => "LATIN CAPITAL LETTER A WITH TILDE",
 994     A_BREVE         => "LATIN CAPITAL LETTER A WITH BREVE",
 995     A_RING          => "LATIN CAPITAL LETTER A WITH RING ABOVE",
 996     A_MACRON        => "LATIN CAPITAL LETTER A WITH MACRON",
 997     mychar2         => U+E8001,
 998     );
 999
1000 Both these methods insert C<":full"> automatically as the first argument (if no
1001 other argument is given), and you can give the C<":full"> explicitly as
1002 well, like
1003
1004     use charnames ":full", ":alias" => "pro";
1005
1006 =head1 charnames::viacode(I<code>)
1007
1008 Returns the full name of the character indicated by the numeric code.
1009 For example,
1010
1011     print charnames::viacode(0x2722);
1012
1013 prints "FOUR TEARDROP-SPOKED ASTERISK".
1014
1015 The name returned is the official name for the code point, if
1016 available, otherwise your custom alias for it.  This means that your
1017 alias will only be returned for code points that don't have an official
1018 Unicode name (nor Unicode version 1 name), such as private use code
1019 points, and the 4 control characters U+0080, U+0081, U+0084, and U+0099.
1020 If you define more than one name for the code point, it is indeterminate
1021 which one will be returned.
1022
1023 The function returns C<undef> if no name is known for the code point.
1024 In Unicode the proper name of these is the empty string, which
1025 C<undef> stringifies to.  (If you ask for a code point past the legal
1026 Unicode maximum of U+10FFFF that you haven't assigned an alias to, you
1027 get C<undef> and a warning.)
1028
1029 Notice that the name returned for of U+FEFF is "ZERO WIDTH NO-BREAK
1030 SPACE", not "BYTE ORDER MARK".
1031
1032 =head1 charnames::vianame(I<name>)
1033
1034 Returns the code point indicated by the name.
1035 For example,
1036
1037     printf "%04X", charnames::vianame("FOUR TEARDROP-SPOKED ASTERISK");
1038
1039 prints "2722".
1040
1041 C<vianame> takes the identical inputs that C<\N{...}> does under the
1042 L<C<:full> and C<:short>|/DESCRIPTION> options to the C<charnames>
1043 pragma, including any L<custom aliases|/CUSTOM ALIASES> you may have
1044 defined.
1045
1046 There are just a few differences.  The main one is that under
1047 most circumstances, (see L</BUGS> for the other ones), vianame returns
1048 an ord, whereas C<\\N{...}> is seamlessly placed as a chr into the
1049 string in which it appears.  This leads to a second difference.
1050 Since an ord is returned, it can be that of any character, even one
1051 that isn't legal under the C<S<use bytes>> pragma.  It is up to the
1052 caller to validate the return under C<S<use bytes>> before converting it
1053 to chr.
1054
1055 The final difference is that if the input name is unknown C<vianame>
1056 returns C<undef> instead of the REPLACEMENT CHARACTER, and it does not
1057 raise a warning message.
1058
1059 =head1 CUSTOM TRANSLATORS
1060
1061 The mechanism of translation of C<\N{...}> escapes is general and not
1062 hardwired into F<charnames.pm>.  A module can install custom
1063 translations (inside the scope which C<use>s the module) with the
1064 following magic incantation:
1065
1066     sub import {
1067         shift;
1068         $^H{charnames} = \&translator;
1069     }
1070
1071 Here translator() is a subroutine which takes I<CHARNAME> as an
1072 argument, and returns text to insert into the string instead of the
1073 C<\N{I<CHARNAME>}> escape.  Since the text to insert should be different
1074 in C<bytes> mode and out of it, the function should check the current
1075 state of C<bytes>-flag as in:
1076
1077     use bytes ();                       # for $bytes::hint_bits
1078     sub translator {
1079         if ($^H & $bytes::hint_bits) {
1080             return bytes_translator(@_);
1081         }
1082         else {
1083             return utf8_translator(@_);
1084         }
1085     }
1086
1087 See L</CUSTOM ALIASES> above for restrictions on I<CHARNAME>.
1088
1089 Of course, C<vianame> and C<viacode> would need to be overridden as
1090 well.
1091
1092 =head1 BUGS
1093
1094 vianame returns a chr if the input name is of the form C<U+...>, and an ord
1095 otherwise.  It is proposed to change this to always return an ord.  Send email
1096 to C<perl5-porters@perl.org> to comment on this proposal.  If S<C<use
1097 bytes>> is in effect when a chr is returned, and if that chr won't fit
1098 into a byte, C<undef> is returned instead.
1099
1100 All the Hangul syllable characters are treated as having no names, as
1101 are almost all the CJK Unicode characters that have their code points as
1102 part of their names.
1103
1104 Names must be ASCII characters only, which means that you are out of luck if
1105 you want to create aliases in a language where some or all the characters of
1106 the desired aliases are non-ASCII.
1107
1108 Unicode standard named sequences are not recognized, such as
1109 C<LATIN CAPITAL LETTER A WITH MACRON AND GRAVE>
1110 (which should mean C<LATIN CAPITAL LETTER A WITH MACRON> with an additional
1111 C<COMBINING GRAVE ACCENT>).
1112
1113 Since evaluation of the translation function happens in the middle of
1114 compilation (of a string literal), the translation function should not
1115 do any C<eval>s or C<require>s.  This restriction should be lifted (but
1116 is low priority) in a future version of Perl.
1117
1118 =cut