ext/Encode/Encode.pm

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