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