ext/Encode/Encode.pm

   1 package Encode;
   2 use strict;
   3 our $VERSION = '0.40';
   4
   5 require DynaLoader;
   6 require Exporter;
   7
   8 our @ISA = qw(Exporter DynaLoader);
   9
  10 # Public, encouraged API is exported by default
  11 our @EXPORT = qw (
  12   encode
  13   decode
  14   encode_utf8
  15   decode_utf8
  16   find_encoding
  17   encodings
  18 );
  19
  20 our @EXPORT_OK =
  21     qw(
  22        define_encoding
  23        define_alias
  24        from_to
  25        is_utf8
  26        is_8bit
  27        is_16bit
  28        utf8_upgrade
  29        utf8_downgrade
  30        _utf8_on
  31        _utf8_off
  32       );
  33
  34 bootstrap Encode ();
  35
  36 # Documentation moved after __END__ for speed - NI-S
  37
  38 use Carp;
  39
  40 # Make a %encoding package variable to allow a certain amount of cheating
  41 our %encoding;
  42 my @alias;  # ordered matching list
  43 my %alias;  # cached known aliases
  44
  45                      # 0  1  2  3  4  5   6   7   8   9  10
  46 our @latin2iso_num = ( 0, 1, 2, 3, 4, 9, 10, 13, 14, 15, 16 );
  47
  48 our %winlatin2cp   = (
  49                       'Latin1'     => 1252,
  50                       'Latin2'     => 1250,
  51                       'Cyrillic'   => 1251,
  52                       'Greek'      => 1253,
  53                       'Turkish'    => 1254,
  54                       'Hebrew'     => 1255,
  55                       'Arabic'     => 1256,
  56                       'Baltic'     => 1257,
  57                       'Vietnamese' => 1258,
  58                      );
  59
  60 sub encodings
  61 {
  62  my ($class) = @_;
  63  return
  64      map { $_->[0] }
  65          sort { $a->[1] cmp $b->[1] }
  66                map { [$_, lc $_] }
  67                    grep { $_ ne 'Internal' }
  68                         keys %encoding;
  69 }
  70
  71 sub findAlias
  72 {
  73     my $class = shift;
  74     local $_ = shift;
  75     # print "# findAlias $_\n";
  76     unless (exists $alias{$_})
  77     {
  78         for (my $i=0; $i < @alias; $i += 2)
  79         {
  80             my $alias = $alias[$i];
  81             my $val   = $alias[$i+1];
  82             my $new;
  83             if (ref($alias) eq 'Regexp' && $_ =~ $alias)
  84             {
  85                 $new = eval $val;
  86             }
  87             elsif (ref($alias) eq 'CODE')
  88             {
  89                 $new = &{$alias}($val)
  90                 }
  91             elsif (lc($_) eq lc($alias))
  92             {
  93                 $new = $val;
  94             }
  95             if (defined($new))
  96             {
  97                 next if $new eq $_; # avoid (direct) recursion on bugs
  98                 my $enc = (ref($new)) ? $new : find_encoding($new);
  99                 if ($enc)
 100                 {
 101                     $alias{$_} = $enc;
 102                     last;
 103                 }
 104             }
 105         }
 106     }
 107     return $alias{$_};
 108 }
 109
 110 sub define_alias
 111 {
 112     while (@_)
 113     {
 114         my ($alias,$name) = splice(@_,0,2);
 115         push(@alias, $alias => $name);
 116     }
 117 }
 118
 119 # Allow variants of iso-8859-1 etc.
 120 define_alias( qr/^iso[-_]?(\d+)[-_](\d+)$/i => '"iso-$1-$2"' );
 121
 122 # At least HP-UX has these.
 123 define_alias( qr/^iso8859(\d+)$/i => '"iso-8859-$1"' );
 124
 125 # More HP stuff.
 126 define_alias( qr/^(?:hp-)?(arabic|greek|hebrew|kana|roman|thai|turkish)8$/i => '"${1}8"' );
 127
 128 # The Official name of ASCII.
 129 define_alias( qr/^ANSI[-_]?X3\.4[-_]?1968$/i => '"ascii"' );
 130
 131 # This is a font issue, not an encoding issue.
 132 # (The currency symbol of the Latin 1 upper half
 133 #  has been redefined as the euro symbol.)
 134 define_alias( qr/^(.+)\@euro$/i => '"$1"' );
 135
 136 # Allow latin-1 style names as well
 137 define_alias( qr/^(?:iso[-_]?)?latin[-_]?(\d+)$/i => '"iso-8859-$latin2iso_num[$1]"' );
 138
 139 # Allow winlatin1 style names as well
 140 define_alias( qr/^win(latin[12]|cyrillic|baltic|greek|turkish|hebrew|arabic|baltic|vietnamese)$/i => '"cp$winlatin2cp{\u$1}"' );
 141
 142 # Common names for non-latin prefered MIME names
 143 define_alias( 'ascii'    => 'US-ascii',
 144               'cyrillic' => 'iso-8859-5',
 145               'arabic'   => 'iso-8859-6',
 146               'greek'    => 'iso-8859-7',
 147               'hebrew'   => 'iso-8859-8',
 148               'thai'     => 'iso-8859-11',
 149               'tis620'   => 'iso-8859-11',
 150             );
 151
 152 # At least AIX has IBM-NNN (surprisingly...) instead of cpNNN.
 153 # And Microsoft has their own naming (again, surprisingly).
 154 define_alias( qr/^(?:ibm|ms)[-_]?(\d\d\d\d?)$/i => '"cp$1"');
 155
 156 # Sometimes seen with a leading zero.
 157 define_alias( qr/^cp037$/i => '"cp37"');
 158
 159 # Ououououou.
 160 define_alias( qr/^macRomanian$/i => '"macRumanian"');
 161
 162 # Standardize on the dashed versions.
 163 define_alias( qr/^utf8$/i  => 'utf-8' );
 164 define_alias( qr/^koi8r$/i => 'koi8-r' );
 165 define_alias( qr/^koi8u$/i => 'koi8-u' );
 166
 167 # Seen in some Linuxes.
 168 define_alias( qr/^ujis$/i => 'euc-jp' );
 169
 170 # CP936 doesn't have vendor-addon for GBK, so they're identical.
 171 define_alias( qr/^gbk$/i => '"cp936"');
 172
 173 # TODO: HP-UX '8' encodings arabic8 greek8 hebrew8 kana8 thai8 turkish8
 174 # TODO: HP-UX '15' encodings japanese15 korean15 roi15
 175 # TODO: Cyrillic encoding ISO-IR-111 (useful?)
 176 # TODO: Armenian encoding ARMSCII-8
 177 # TODO: Hebrew encoding ISO-8859-8-1
 178 # TODO: Thai encoding TCVN
 179 # TODO: Korean encoding Johab
 180 # TODO: Vietnamese encodings VPS
 181 # TODO: Japanese encoding JIS (not the same as SJIS)
 182 # TODO: Mac Asian+African encodings: Arabic Armenian Bengali Burmese
 183 #       ChineseSimp ChineseTrad Devanagari Ethiopic ExtArabic
 184 #       Farsi Georgian Gujarati Gurmukhi Hebrew Japanese
 185 #       Kannada Khmer Korean Laotian Malayalam Mongolian
 186 #       Oriya Sinhalese Symbol Tamil Telugu Tibetan Vietnamese
 187
 188 # Map white space and _ to '-'
 189 define_alias( qr/^(\S+)[\s_]+(.*)$/i => '"$1-$2"' );
 190
 191 sub define_encoding
 192 {
 193     my $obj  = shift;
 194     my $name = shift;
 195     $encoding{$name} = $obj;
 196     my $lc = lc($name);
 197     define_alias($lc => $obj) unless $lc eq $name;
 198     while (@_)
 199     {
 200         my $alias = shift;
 201         define_alias($alias,$obj);
 202     }
 203     return $obj;
 204 }
 205
 206 sub getEncoding
 207 {
 208     my ($class,$name) = @_;
 209     my $enc;
 210     if (ref($name) && $name->can('new_sequence'))
 211     {
 212         return $name;
 213     }
 214     my $lc = lc $name;
 215     if (exists $encoding{$name})
 216     {
 217         return $encoding{$name};
 218     }
 219     if (exists $encoding{$lc})
 220     {
 221         return $encoding{$lc};
 222     }
 223
 224     my $oc = $class->findAlias($name);
 225     return $oc if defined $oc;
 226     return $class->findAlias($lc) if $lc ne $name;
 227
 228     return;
 229 }
 230
 231 sub find_encoding
 232 {
 233     my ($name) = @_;
 234     return __PACKAGE__->getEncoding($name);
 235 }
 236
 237 sub encode
 238 {
 239     my ($name,$string,$check) = @_;
 240     my $enc = find_encoding($name);
 241     croak("Unknown encoding '$name'") unless defined $enc;
 242     my $octets = $enc->encode($string,$check);
 243     return undef if ($check && length($string));
 244     return $octets;
 245 }
 246
 247 sub decode
 248 {
 249     my ($name,$octets,$check) = @_;
 250     my $enc = find_encoding($name);
 251     croak("Unknown encoding '$name'") unless defined $enc;
 252     my $string = $enc->decode($octets,$check);
 253     $_[1] = $octets if $check;
 254     return $string;
 255 }
 256
 257 sub from_to
 258 {
 259     my ($string,$from,$to,$check) = @_;
 260     my $f = find_encoding($from);
 261     croak("Unknown encoding '$from'") unless defined $f;
 262     my $t = find_encoding($to);
 263     croak("Unknown encoding '$to'") unless defined $t;
 264     my $uni = $f->decode($string,$check);
 265     return undef if ($check && length($string));
 266     $string = $t->encode($uni,$check);
 267     return undef if ($check && length($uni));
 268     return length($_[0] = $string);
 269 }
 270
 271 sub encode_utf8
 272 {
 273     my ($str) = @_;
 274   utf8::encode($str);
 275     return $str;
 276 }
 277
 278 sub decode_utf8
 279 {
 280     my ($str) = @_;
 281     return undef unless utf8::decode($str);
 282     return $str;
 283 }
 284
 285 require Encode::Encoding;
 286 require Encode::XS;
 287 require Encode::Internal;
 288 require Encode::Unicode;
 289 require Encode::utf8;
 290 require Encode::iso10646_1;
 291 require Encode::ucs2_le;
 292
 293 1;
 294
 295 __END__
 296
 297 =head1 NAME
 298
 299 Encode - character encodings
 300
 301 =head1 SYNOPSIS
 302
 303     use Encode;
 304
 305     use Encode::TW; # for Taiwan-based Chinese encodings
 306     use Encode::CN; # for China-based Chinese encodings
 307     use Encode::JP; # for Japanese encodings
 308     use Encode::KR; # for Korean encodings
 309
 310 =head1 DESCRIPTION
 311
 312 The C<Encode> module provides the interfaces between Perl's strings
 313 and the rest of the system.  Perl strings are sequences of B<characters>.
 314
 315 The repertoire of characters that Perl can represent is at least that
 316 defined by the Unicode Consortium. On most platforms the ordinal
 317 values of the characters (as returned by C<ord(ch)>) is the "Unicode
 318 codepoint" for the character (the exceptions are those platforms where
 319 the legacy encoding is some variant of EBCDIC rather than a super-set
 320 of ASCII - see L<perlebcdic>).
 321
 322 Traditionaly computer data has been moved around in 8-bit chunks
 323 often called "bytes". These chunks are also known as "octets" in
 324 networking standards. Perl is widely used to manipulate data of
 325 many types - not only strings of characters representing human or
 326 computer languages but also "binary" data being the machines representation
 327 of numbers, pixels in an image - or just about anything.
 328
 329 When Perl is processing "binary data" the programmer wants Perl to process
 330 "sequences of bytes". This is not a problem for Perl - as a byte has 256
 331 possible values it easily fits in Perl's much larger "logical character".
 332
 333 Due to size concerns, before using B<CJK> (Chinese, Japanese & Korean)
 334 encodings, you have to C<use> the corresponding
 335 B<Encode::>(B<TW>|B<CN>|B<JP>|B<KR>) modules first.
 336
 337 =head2 TERMINOLOGY
 338
 339 =over 4
 340
 341 =item *
 342
 343 I<character>: a character in the range 0..(2**32-1) (or more).
 344 (What Perl's strings are made of.)
 345
 346 =item *
 347
 348 I<byte>: a character in the range 0..255
 349 (A special case of a Perl character.)
 350
 351 =item *
 352
 353 I<octet>: 8 bits of data, with ordinal values 0..255
 354 (Term for bytes passed to or from a non-Perl context, e.g. disk file.)
 355
 356 =back
 357
 358 The marker [INTERNAL] marks Internal Implementation Details, in
 359 general meant only for those who think they know what they are doing,
 360 and such details may change in future releases.
 361
 362 =head1 ENCODINGS
 363
 364 =head2 Characteristics of an Encoding
 365
 366 An encoding has a "repertoire" of characters that it can represent,
 367 and for each representable character there is at least one sequence of
 368 octets that represents it.
 369
 370 =head2 Types of Encodings
 371
 372 Encodings can be divided into the following types:
 373
 374 =over 4
 375
 376 =item * Fixed length 8-bit (or less) encodings.
 377
 378 Each character is a single octet so may have a repertoire of up to
 379 256 characters. ASCII and iso-8859-* are typical examples.
 380
 381 =item * Fixed length 16-bit encodings
 382
 383 Each character is two octets so may have a repertoire of up to
 384 65 536 characters.  Unicode's UCS-2 is an example.  Also used for
 385 encodings for East Asian languages.
 386
 387 =item * Fixed length 32-bit encodings.
 388
 389 Not really very "encoded" encodings. The Unicode code points
 390 are just represented as 4-octet integers. None the less because
 391 different architectures use different representations of integers
 392 (so called "endian") there at least two disctinct encodings.
 393
 394 =item * Multi-byte encodings
 395
 396 The number of octets needed to represent a character varies.
 397 UTF-8 is a particularly complex but regular case of a multi-byte
 398 encoding. Several East Asian countries use a multi-byte encoding
 399 where 1-octet is used to cover western roman characters and Asian
 400 characters get 2-octets.
 401 (UTF-16 is strictly a multi-byte encoding taking either 2 or 4 octets
 402 to represent a Unicode code point.)
 403
 404 =item * "Escape" encodings.
 405
 406 These encodings embed "escape sequences" into the octet sequence
 407 which describe how the following octets are to be interpreted.
 408 The iso-2022-* family is typical. Following the escape sequence
 409 octets are encoded by an "embedded" encoding (which will be one
 410 of the above types) until another escape sequence switches to
 411 a different "embedded" encoding.
 412
 413 These schemes are very flexible and can handle mixed languages but are
 414 very complex to process (and have state).  No escape encodings are
 415 implemented for Perl yet.
 416
 417 =back
 418
 419 =head2 Specifying Encodings
 420
 421 Encodings can be specified to the API described below in two ways:
 422
 423 =over 4
 424
 425 =item 1. By name
 426
 427 Encoding names are strings with characters taken from a restricted
 428 repertoire.  See L</"Encoding Names">.
 429
 430 =item 2. As an object
 431
 432 Encoding objects are returned by C<find_encoding($name)>.
 433
 434 =back
 435
 436 =head2 Encoding Names
 437
 438 Encoding names are case insensitive. White space in names is ignored.
 439 In addition an encoding may have aliases. Each encoding has one
 440 "canonical" name.  The "canonical" name is chosen from the names of
 441 the encoding by picking the first in the following sequence:
 442
 443 =over 4
 444
 445 =item * The MIME name as defined in IETF RFCs.
 446
 447 =item * The name in the IANA registry.
 448
 449 =item * The name used by the organization that defined it.
 450
 451 =back
 452
 453 Because of all the alias issues, and because in the general case
 454 encodings have state C<Encode> uses the encoding object internally
 455 once an operation is in progress.
 456
 457 As of Perl 5.8.0, at least the following encodings are recognized
 458 (the => marks aliases):
 459
 460   ASCII
 461
 462   US-ASCII => ASCII
 463
 464 The Unicode:
 465
 466   UTF-8
 467   UTF-16
 468   UCS-2
 469
 470   ISO 10646-1 => UCS-2
 471
 472 The ISO 8859 and KOI:
 473
 474   ISO 8859-1  ISO 8859-6   ISO 8859-11         KOI8-F
 475   ISO 8859-2  ISO 8859-7   (12 doesn't exist)  KOI8-R
 476   ISO 8859-3  ISO 8859-8   ISO 8859-13         KOI8-U
 477   ISO 8859-4  ISO 8859-9   ISO 8859-14
 478   ISO 8859-5  ISO 8859-10  ISO 8859-15
 479                            ISO 8859-16
 480
 481   Latin1  => 8859-1  Latin6  => 8859-10
 482   Latin2  => 8859-2  Latin7  => 8859-13
 483   Latin3  => 8859-3  Latin8  => 8859-14
 484   Latin4  => 8859-4  Latin9  => 8859-15
 485   Latin5  => 8859-9  Latin10 => 8859-16
 486
 487   Cyrillic => 8859-5
 488   Arabic   => 8859-6
 489   Greek    => 8859-7
 490   Hebrew   => 8859-8
 491   Thai     => 8859-11
 492   TIS620   => 8859-11
 493
 494 The CJKV: Chinese, Japanese, Korean, Vietnamese:
 495
 496   ISO 2022     ISO 2022 JP-1  JIS 0201  GB 1988   Big5       EUC-CN
 497   ISO 2022 CN  ISO 2022 JP-2  JIS 0208  GB 2312   HZ         EUC-JP
 498   ISO 2022 JP  ISO 2022 KR    JIS 0210  GB 12345  CNS 11643  EUC-JP-0212
 499   Shift-JIS                             GBK       Big5-HKSCS EUC-KR
 500   VISCII                                ISO-IR-165
 501
 502 (Due to size concerns, additional Chinese encodings including C<GB 18030>,
 503 C<EUC-TW> and C<BIG5PLUS> are distributed separately on CPAN, under the name
 504 L<Encode::HanExtra>.)
 505
 506 The PC codepages:
 507
 508   CP37   CP852  CP861  CP866  CP949   CP1251  CP1256
 509   CP424  CP855  CP862  CP869  CP950   CP1252  CP1257
 510   CP737  CP856  CP863  CP874  CP1006  CP1253  CP1258
 511   CP775  CP857  CP864  CP932  CP1047  CP1254
 512   CP850  CP860  CP865  CP936  CP1250  CP1255
 513
 514   WinLatin1     => CP1252
 515   WinLatin2     => CP1250
 516   WinCyrillic   => CP1251
 517   WinGreek      => CP1253
 518   WinTurkiskh   => CP1254
 519   WinHebrew     => CP1255
 520   WinArabic     => CP1256
 521   WinBaltic     => CP1257
 522   WinVietnamese => CP1258
 523
 524 (All the CPI<NNN...> are available also as IBMI<NNN...>.)
 525
 526 The Mac codepages:
 527
 528   MacCentralEuropean   MacJapanese
 529   MacCroatian          MacRoman
 530   MacCyrillic          MacRomanian
 531   MacDingbats          MacSami
 532   MacGreek             MacThai
 533   MacIcelandic         MacTurkish
 534                        MacUkraine
 535
 536 Miscellaneous:
 537
 538   7bit-greek  IR-197
 539   7bit-kana   NeXTstep
 540   7bit-latin1 POSIX-BC
 541   DingBats    Roman8
 542   GSM 0338    Symbol
 543
 544 =head1 PERL ENCODING API
 545
 546 =head2 Generic Encoding Interface
 547
 548 =over 4
 549
 550 =item *
 551
 552         $bytes  = encode(ENCODING, $string[, CHECK])
 553
 554 Encodes string from Perl's internal form into I<ENCODING> and returns
 555 a sequence of octets.  For CHECK see L</"Handling Malformed Data">.
 556
 557 For example to convert (internally UTF-8 encoded) Unicode data
 558 to octets:
 559
 560         $octets = encode("utf8", $unicode);
 561
 562 =item *
 563
 564         $string = decode(ENCODING, $bytes[, CHECK])
 565
 566 Decode sequence of octets assumed to be in I<ENCODING> into Perl's
 567 internal form and returns the resulting string.  For CHECK see
 568 L</"Handling Malformed Data">.
 569
 570 For example to convert ISO 8859-1 data to UTF-8:
 571
 572         $utf8 = decode("latin1", $latin1);
 573
 574 =item *
 575
 576         from_to($string, FROM_ENCODING, TO_ENCODING[, CHECK])
 577
 578 Convert B<in-place> the data between two encodings.  How did the data
 579 in $string originally get to be in FROM_ENCODING?  Either using
 580 encode() or through PerlIO: See L</"Encoding and IO">.  For CHECK
 581 see L</"Handling Malformed Data">.
 582
 583 For example to convert ISO 8859-1 data to UTF-8:
 584
 585         from_to($data, "iso-8859-1", "utf-8");
 586
 587 and to convert it back:
 588
 589         from_to($data, "utf-8", "iso-8859-1");
 590
 591 Note that because the conversion happens in place, the data to be
 592 converted cannot be a string constant, it must be a scalar variable.
 593
 594 =back
 595
 596 =head2 Handling Malformed Data
 597
 598 If CHECK is not set, C<undef> is returned.  If the data is supposed to
 599 be UTF-8, an optional lexical warning (category utf8) is given.  If
 600 CHECK is true but not a code reference, dies.
 601
 602 It would desirable to have a way to indicate that transform should use
 603 the encodings "replacement character" - no such mechanism is defined yet.
 604
 605 It is also planned to allow I<CHECK> to be a code reference.
 606
 607 This is not yet implemented as there are design issues with what its
 608 arguments should be and how it returns its results.
 609
 610 =over 4
 611
 612 =item Scheme 1
 613
 614 Passed remaining fragment of string being processed.
 615 Modifies it in place to remove bytes/characters it can understand
 616 and returns a string used to represent them.
 617 e.g.
 618
 619  sub fixup {
 620    my $ch = substr($_[0],0,1,'');
 621    return sprintf("\x{%02X}",ord($ch);
 622  }
 623
 624 This scheme is close to how underlying C code for Encode works, but gives
 625 the fixup routine very little context.
 626
 627 =item Scheme 2
 628
 629 Passed original string, and an index into it of the problem area, and
 630 output string so far.  Appends what it will to output string and
 631 returns new index into original string.  For example:
 632
 633  sub fixup {
 634    # my ($s,$i,$d) = @_;
 635    my $ch = substr($_[0],$_[1],1);
 636    $_[2] .= sprintf("\x{%02X}",ord($ch);
 637    return $_[1]+1;
 638  }
 639
 640 This scheme gives maximal control to the fixup routine but is more
 641 complicated to code, and may need internals of Encode to be tweaked to
 642 keep original string intact.
 643
 644 =item Other Schemes
 645
 646 Hybrids of above.
 647
 648 Multiple return values rather than in-place modifications.
 649
 650 Index into the string could be pos($str) allowing s/\G...//.
 651
 652 =back
 653
 654 =head2 UTF-8 / utf8
 655
 656 The Unicode consortium defines the UTF-8 standard as a way of encoding
 657 the entire Unicode repertiore as sequences of octets.  This encoding is
 658 expected to become very widespread. Perl can use this form internaly
 659 to represent strings, so conversions to and from this form are
 660 particularly efficient (as octets in memory do not have to change,
 661 just the meta-data that tells Perl how to treat them).
 662
 663 =over 4
 664
 665 =item *
 666
 667         $bytes = encode_utf8($string);
 668
 669 The characters that comprise string are encoded in Perl's superset of UTF-8
 670 and the resulting octets returned as a sequence of bytes. All possible
 671 characters have a UTF-8 representation so this function cannot fail.
 672
 673 =item *
 674
 675         $string = decode_utf8($bytes [,CHECK]);
 676
 677 The sequence of octets represented by $bytes is decoded from UTF-8
 678 into a sequence of logical characters. Not all sequences of octets
 679 form valid UTF-8 encodings, so it is possible for this call to fail.
 680 For CHECK see L</"Handling Malformed Data">.
 681
 682 =back
 683
 684 =head2 Other Encodings of Unicode
 685
 686 UTF-16 is similar to UCS-2, 16 bit or 2-byte chunks.  UCS-2 can only
 687 represent 0..0xFFFF, while UTF-16 has a I<surrogate pair> scheme which
 688 allows it to cover the whole Unicode range.
 689
 690 Surrogates are code points set aside to encode the 0x01000..0x10FFFF
 691 range of Unicode code points in pairs of 16-bit units.  The I<high
 692 surrogates> are the range 0xD800..0xDBFF, and the I<low surrogates>
 693 are the range 0xDC00..0xDFFFF.  The surrogate encoding is
 694
 695         $hi = ($uni - 0x10000) / 0x400 + 0xD800;
 696         $lo = ($uni - 0x10000) % 0x400 + 0xDC00;
 697
 698 and the decoding is
 699
 700         $uni = 0x10000 + ($hi - 0xD8000) * 0x400 + ($lo - 0xDC00);
 701
 702 Encode implements big-endian UCS-2 aliased to "iso-10646-1" as that
 703 happens to be the name used by that representation when used with X11
 704 fonts.
 705
 706 UTF-32 or UCS-4 is 32-bit or 4-byte chunks.  Perl's logical characters
 707 can be considered as being in this form without encoding. An encoding
 708 to transfer strings in this form (e.g. to write them to a file) would
 709 need to
 710
 711      pack('L*', unpack('U*', $string));  # native
 712   or
 713      pack('V*', unpack('U*', $string));  # little-endian
 714   or
 715      pack('N*', unpack('U*', $string));  # big-endian
 716
 717 depending on the endianness required.
 718
 719 No UTF-32 encodings are implemented yet.
 720
 721 Both UCS-2 and UCS-4 style encodings can have "byte order marks" by
 722 representing the code point 0xFFFE as the very first thing in a file.
 723
 724 =head2 Listing available encodings
 725
 726   use Encode qw(encodings);
 727   @list = encodings();
 728
 729 Returns a list of the canonical names of the available encodings.
 730
 731 =head2 Defining Aliases
 732
 733   use Encode qw(define_alias);
 734   define_alias( newName => ENCODING);
 735
 736 Allows newName to be used as am alias for ENCODING. ENCODING may be
 737 either the name of an encoding or and encoding object (as above).
 738
 739 Currently I<newName> can be specified in the following ways:
 740
 741 =over 4
 742
 743 =item As a simple string.
 744
 745 =item As a qr// compiled regular expression, e.g.:
 746
 747   define_alias( qr/^iso8859-(\d+)$/i => '"iso-8859-$1"' );
 748
 749 In this case if I<ENCODING> is not a reference it is C<eval>-ed to
 750 allow C<$1> etc. to be subsituted.  The example is one way to names as
 751 used in X11 font names to alias the MIME names for the iso-8859-*
 752 family.
 753
 754 =item As a code reference, e.g.:
 755
 756   define_alias( sub { return /^iso8859-(\d+)$/i ? "iso-8859-$1" : undef } , '');
 757
 758 In this case C<$_> will be set to the name that is being looked up and
 759 I<ENCODING> is passed to the sub as its first argument.  The example
 760 is another way to names as used in X11 font names to alias the MIME
 761 names for the iso-8859-* family.
 762
 763 =back
 764
 765 =head2 Defining Encodings
 766
 767     use Encode qw(define_alias);
 768     define_encoding( $object, 'canonicalName' [,alias...]);
 769
 770 Causes I<canonicalName> to be associated with I<$object>.  The object
 771 should provide the interface described in L</"IMPLEMENTATION CLASSES">
 772 below.  If more than two arguments are provided then additional
 773 arguments are taken as aliases for I<$object> as for C<define_alias>.
 774
 775 =head1 Encoding and IO
 776
 777 It is very common to want to do encoding transformations when
 778 reading or writing files, network connections, pipes etc.
 779 If Perl is configured to use the new 'perlio' IO system then
 780 C<Encode> provides a "layer" (See L<perliol>) which can transform
 781 data as it is read or written.
 782
 783 Here is how the blind poet would modernise the encoding:
 784
 785     use Encode;
 786     open(my $iliad,'<:encoding(iso-8859-7)','iliad.greek');
 787     open(my $utf8,'>:utf8','iliad.utf8');
 788     my @epic = <$iliad>;
 789     print $utf8 @epic;
 790     close($utf8);
 791     close($illiad);
 792
 793 In addition the new IO system can also be configured to read/write
 794 UTF-8 encoded characters (as noted above this is efficient):
 795
 796     open(my $fh,'>:utf8','anything');
 797     print $fh "Any \x{0021} string \N{SMILEY FACE}\n";
 798
 799 Either of the above forms of "layer" specifications can be made the default
 800 for a lexical scope with the C<use open ...> pragma. See L<open>.
 801
 802 Once a handle is open is layers can be altered using C<binmode>.
 803
 804 Without any such configuration, or if Perl itself is built using
 805 system's own IO, then write operations assume that file handle accepts
 806 only I<bytes> and will C<die> if a character larger than 255 is
 807 written to the handle. When reading, each octet from the handle
 808 becomes a byte-in-a-character. Note that this default is the same
 809 behaviour as bytes-only languages (including Perl before v5.6) would
 810 have, and is sufficient to handle native 8-bit encodings
 811 e.g. iso-8859-1, EBCDIC etc. and any legacy mechanisms for handling
 812 other encodings and binary data.
 813
 814 In other cases it is the programs responsibility to transform
 815 characters into bytes using the API above before doing writes, and to
 816 transform the bytes read from a handle into characters before doing
 817 "character operations" (e.g. C<lc>, C</\W+/>, ...).
 818
 819 You can also use PerlIO to convert larger amounts of data you don't
 820 want to bring into memory.  For example to convert between ISO 8859-1
 821 (Latin 1) and UTF-8 (or UTF-EBCDIC in EBCDIC machines):
 822
 823     open(F, "<:encoding(iso-8859-1)", "data.txt") or die $!;
 824     open(G, ">:utf8",                 "data.utf") or die $!;
 825     while (<F>) { print G }
 826
 827     # Could also do "print G <F>" but that would pull
 828     # the whole file into memory just to write it out again.
 829
 830 More examples:
 831
 832     open(my $f, "<:encoding(cp1252)")
 833     open(my $g, ">:encoding(iso-8859-2)")
 834     open(my $h, ">:encoding(latin9)")       # iso-8859-15
 835
 836 See L<PerlIO> for more information.
 837
 838 See also L<encoding> for how to change the default encoding of the
 839 data in your script.
 840
 841 =head1 Encoding How to ...
 842
 843 To do:
 844
 845 =over 4
 846
 847 =item * IO with mixed content (faking iso-2020-*)
 848
 849 =item * MIME's Content-Length:
 850
 851 =item * UTF-8 strings in binary data.
 852
 853 =item * Perl/Encode wrappers on non-Unicode XS modules.
 854
 855 =back
 856
 857 =head1 Messing with Perl's Internals
 858
 859 The following API uses parts of Perl's internals in the current
 860 implementation.  As such they are efficient, but may change.
 861
 862 =over 4
 863
 864 =item * is_utf8(STRING [, CHECK])
 865
 866 [INTERNAL] Test whether the UTF-8 flag is turned on in the STRING.
 867 If CHECK is true, also checks the data in STRING for being well-formed
 868 UTF-8.  Returns true if successful, false otherwise.
 869
 870 =item * valid_utf8(STRING)
 871
 872 [INTERNAL] Test whether STRING is in a consistent state.  Will return
 873 true if string is held as bytes, or is well-formed UTF-8 and has the
 874 UTF-8 flag on.  Main reason for this routine is to allow Perl's
 875 testsuite to check that operations have left strings in a consistent
 876 state.
 877
 878 =item *
 879
 880         _utf8_on(STRING)
 881
 882 [INTERNAL] Turn on the UTF-8 flag in STRING.  The data in STRING is
 883 B<not> checked for being well-formed UTF-8.  Do not use unless you
 884 B<know> that the STRING is well-formed UTF-8.  Returns the previous
 885 state of the UTF-8 flag (so please don't test the return value as
 886 I<not> success or failure), or C<undef> if STRING is not a string.
 887
 888 =item *
 889
 890         _utf8_off(STRING)
 891
 892 [INTERNAL] Turn off the UTF-8 flag in STRING.  Do not use frivolously.
 893 Returns the previous state of the UTF-8 flag (so please don't test the
 894 return value as I<not> success or failure), or C<undef> if STRING is
 895 not a string.
 896
 897 =back
 898
 899 =head1 IMPLEMENTATION CLASSES
 900
 901 As mentioned above encodings are (in the current implementation at least)
 902 defined by objects. The mapping of encoding name to object is via the
 903 C<%encodings> hash.
 904
 905 The values of the hash can currently be either strings or objects.
 906 The string form may go away in the future. The string form occurs
 907 when C<encodings()> has scanned C<@INC> for loadable encodings but has
 908 not actually loaded the encoding in question. This is because the
 909 current "loading" process is all Perl and a bit slow.
 910
 911 Once an encoding is loaded then value of the hash is object which
 912 implements the encoding. The object should provide the following
 913 interface:
 914
 915 =over 4
 916
 917 =item -E<gt>name
 918
 919 Should return the string representing the canonical name of the encoding.
 920
 921 =item -E<gt>new_sequence
 922
 923 This is a placeholder for encodings with state. It should return an
 924 object which implements this interface, all current implementations
 925 return the original object.
 926
 927 =item -E<gt>encode($string,$check)
 928
 929 Should return the octet sequence representing I<$string>. If I<$check>
 930 is true it should modify I<$string> in place to remove the converted
 931 part (i.e.  the whole string unless there is an error).  If an error
 932 occurs it should return the octet sequence for the fragment of string
 933 that has been converted, and modify $string in-place to remove the
 934 converted part leaving it starting with the problem fragment.
 935
 936 If check is is false then C<encode> should make a "best effort" to
 937 convert the string - for example by using a replacement character.
 938
 939 =item -E<gt>decode($octets,$check)
 940
 941 Should return the string that I<$octets> represents. If I<$check> is
 942 true it should modify I<$octets> in place to remove the converted part
 943 (i.e.  the whole sequence unless there is an error).  If an error
 944 occurs it should return the fragment of string that has been
 945 converted, and modify $octets in-place to remove the converted part
 946 leaving it starting with the problem fragment.
 947
 948 If check is is false then C<decode> should make a "best effort" to
 949 convert the string - for example by using Unicode's "\x{FFFD}" as a
 950 replacement character.
 951
 952 =back
 953
 954 It should be noted that the check behaviour is different from the
 955 outer public API. The logic is that the "unchecked" case is useful
 956 when encoding is part of a stream which may be reporting errors
 957 (e.g. STDERR).  In such cases it is desirable to get everything
 958 through somehow without causing additional errors which obscure the
 959 original one. Also the encoding is best placed to know what the
 960 correct replacement character is, so if that is the desired behaviour
 961 then letting low level code do it is the most efficient.
 962
 963 In contrast if check is true, the scheme above allows the encoding to
 964 do as much as it can and tell layer above how much that was. What is
 965 lacking at present is a mechanism to report what went wrong. The most
 966 likely interface will be an additional method call to the object, or
 967 perhaps (to avoid forcing per-stream objects on otherwise stateless
 968 encodings) and additional parameter.
 969
 970 It is also highly desirable that encoding classes inherit from
 971 C<Encode::Encoding> as a base class. This allows that class to define
 972 additional behaviour for all encoding objects. For example built in
 973 Unicode, UCS-2 and UTF-8 classes use :
 974
 975   package Encode::MyEncoding;
 976   use base qw(Encode::Encoding);
 977
 978   __PACKAGE__->Define(qw(myCanonical myAlias));
 979
 980 To create an object with bless {Name => ...},$class, and call
 981 define_encoding.  They inherit their C<name> method from
 982 C<Encode::Encoding>.
 983
 984 =head2 Compiled Encodings
 985
 986 F<Encode.xs> provides a class C<Encode::XS> which provides the
 987 interface described above. It calls a generic octet-sequence to
 988 octet-sequence "engine" that is driven by tables (defined in
 989 F<encengine.c>). The same engine is used for both encode and
 990 decode. C<Encode:XS>'s C<encode> forces Perl's characters to their
 991 UTF-8 form and then treats them as just another multibyte
 992 encoding. C<Encode:XS>'s C<decode> transforms the sequence and then
 993 turns the UTF-8-ness flag as that is the form that the tables are
 994 defined to produce. For details of the engine see the comments in
 995 F<encengine.c>.
 996
 997 The tables are produced by the Perl script F<compile> (the name needs
 998 to change so we can eventually install it somewhere). F<compile> can
 999 currently read two formats:
1000
1001 =over 4
1002
1003 =item *.enc
1004
1005 This is a coined format used by Tcl. It is documented in
1006 Encode/EncodeFormat.pod.
1007
1008 =item *.ucm
1009
1010 This is the semi-standard format used by IBM's ICU package.
1011
1012 =back
1013
1014 F<compile> can write the following forms:
1015
1016 =over 4
1017
1018 =item *.ucm
1019
1020 See above - the F<Encode/*.ucm> files provided with the distribution have
1021 been created from the original Tcl .enc files using this approach.
1022
1023 =item *.c
1024
1025 Produces tables as C data structures - this is used to build in encodings
1026 into F<Encode.so>/F<Encode.dll>.
1027
1028 =item *.xs
1029
1030 In theory this allows encodings to be stand-alone loadable Perl
1031 extensions.  The process has not yet been tested. The plan is to use
1032 this approach for large East Asian encodings.
1033
1034 =back
1035
1036 The set of encodings built-in to F<Encode.so>/F<Encode.dll> is
1037 determined by F<Makefile.PL>.  The current set is as follows:
1038
1039 =over 4
1040
1041 =item ascii and iso-8859-*
1042
1043 That is all the common 8-bit "western" encodings.
1044
1045 =item IBM-1047 and two other variants of EBCDIC.
1046
1047 These are the same variants that are supported by EBCDIC Perl as
1048 "native" encodings.  They are included to prove "reversibility" of
1049 some constructs in EBCDIC Perl.
1050
1051 =item symbol and dingbats as used by Tk on X11.
1052
1053 (The reason Encode got started was to support Perl/Tk.)
1054
1055 =back
1056
1057 That set is rather ad hoc and has been driven by the needs of the
1058 tests rather than the needs of typical applications. It is likely
1059 to be rationalized.
1060
1061 =head1 SEE ALSO
1062
1063 L<perlunicode>, L<perlebcdic>, L<perlfunc/open>, L<PerlIO>, L<encoding>
1064
1065 =cut
1066