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