ext/Encode/Encode.pm

   1 package Encode;
   2 use strict;
   3 our $VERSION = do { my @r = (q$Revision: 0.98 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };
   4 our $DEBUG = 0;
   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        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 our $ON_EBCDIC = (ord("A") == 193);
  41 use Encode::Alias;
  42
  43 # Make a %Encoding package variable to allow a certain amount of cheating
  44 our %Encoding;
  45
  46 our %ExtModule =
  47     (
  48      viscii             => 'Encode/Byte.pm',
  49      'koi8-r'           => 'Encode/Byte.pm',
  50      cp1047             => 'Encode/EBCDIC.pm',
  51      cp37               => 'Encode/EBCDIC.pm',
  52      'posix-bc'         => 'Encode/EBCDIC.pm',
  53      symbol             => 'Encode/Symbol.pm',
  54      dingbats           => 'Encode/Symbol.pm',
  55     );
  56
  57 for my $k (2..11,13..16){
  58     $ExtModule{"iso-8859-$k"} = 'Encode/Byte.pm';
  59 }
  60
  61 for my $k (1250..1258){
  62     $ExtModule{"cp$k"} = 'Encode/Byte.pm';
  63 }
  64
  65 unless ($ON_EBCDIC) { # CJK added to autoload unless EBCDIC env
  66 %ExtModule =(
  67              %ExtModule,
  68              'euc-cn'           => 'Encode/CN.pm',
  69              gb2312             => 'Encode/CN.pm',
  70              gb12345            => 'Encode/CN.pm',
  71              gbk                => 'Encode/CN.pm',
  72              cp936              => 'Encode/CN.pm',
  73              'iso-ir-165'       => 'Encode/CN.pm',
  74              'euc-jp'           => 'Encode/JP.pm',
  75              'iso-2022-jp'      => 'Encode/JP.pm',
  76              'iso-2022-jp-1'    => 'Encode/JP.pm',
  77              '7bit-jis'         => 'Encode/JP.pm',
  78              shiftjis           => 'Encode/JP.pm',
  79              macjapan           => 'Encode/JP.pm',
  80              cp932              => 'Encode/JP.pm',
  81              'euc-kr'           => 'Encode/KR.pm',
  82              ksc5601            => 'Encode/KR.pm',
  83              cp949              => 'Encode/KR.pm',
  84              big5               => 'Encode/TW.pm',
  85              'big5-hkscs'       => 'Encode/TW.pm',
  86              cp950              => 'Encode/TW.pm',
  87              gb18030            => 'Encode/HanExtra.pm',
  88              big5plus           => 'Encode/HanExtra.pm',
  89              'euc-tw'           => 'Encode/HanExtra.pm',
  90              );
  91 }
  92
  93 for my $k (qw(centeuro croatian cyrillic dingbats greek
  94               iceland roman rumanian sami
  95               thai turkish  ukraine))
  96 {
  97     $ExtModule{"mac$k"} = 'Encode/Byte.pm';
  98 }
  99
 100
 101 sub encodings
 102 {
 103     my $class = shift;
 104     my @modules = (@_ and $_[0] eq ":all") ? values %ExtModule : @_;
 105     for my $m (@modules)
 106     {
 107         $DEBUG and warn "about to require $m;";
 108         eval { require $m; };
 109     }
 110     return
 111         map({$_->[0]}
 112             sort({$a->[1] cmp $b->[1]}
 113                  map({[$_, lc $_]}
 114                      grep({ $_ ne 'Internal' }  keys %Encoding))));
 115 }
 116
 117 sub define_encoding
 118 {
 119     my $obj  = shift;
 120     my $name = shift;
 121     $Encoding{$name} = $obj;
 122     my $lc = lc($name);
 123     define_alias($lc => $obj) unless $lc eq $name;
 124     while (@_)
 125     {
 126         my $alias = shift;
 127         define_alias($alias,$obj);
 128     }
 129     return $obj;
 130 }
 131
 132 sub getEncoding
 133 {
 134     my ($class,$name,$skip_external) = @_;
 135     my $enc;
 136     if (ref($name) && $name->can('new_sequence'))
 137     {
 138         return $name;
 139     }
 140     my $lc = lc $name;
 141     if (exists $Encoding{$name})
 142     {
 143         return $Encoding{$name};
 144     }
 145     if (exists $Encoding{$lc})
 146     {
 147         return $Encoding{$lc};
 148     }
 149
 150     my $oc = $class->find_alias($name);
 151     return $oc if defined $oc;
 152
 153     $oc = $class->find_alias($lc) if $lc ne $name;
 154     return $oc if defined $oc;
 155
 156     if (!$skip_external and exists $ExtModule{$lc})
 157     {
 158         eval{ require $ExtModule{$lc}; };
 159         return $Encoding{$name} if exists $Encoding{$name};
 160     }
 161
 162     return;
 163 }
 164
 165 sub find_encoding
 166 {
 167     my ($name,$skip_external) = @_;
 168     return __PACKAGE__->getEncoding($name,$skip_external);
 169 }
 170
 171 sub encode
 172 {
 173     my ($name,$string,$check) = @_;
 174     my $enc = find_encoding($name);
 175     croak("Unknown encoding '$name'") unless defined $enc;
 176     my $octets = $enc->encode($string,$check);
 177     return undef if ($check && length($string));
 178     return $octets;
 179 }
 180
 181 sub decode
 182 {
 183     my ($name,$octets,$check) = @_;
 184     my $enc = find_encoding($name);
 185     croak("Unknown encoding '$name'") unless defined $enc;
 186     my $string = $enc->decode($octets,$check);
 187     $_[1] = $octets if $check;
 188     return $string;
 189 }
 190
 191 sub from_to
 192 {
 193     my ($string,$from,$to,$check) = @_;
 194     my $f = find_encoding($from);
 195     croak("Unknown encoding '$from'") unless defined $f;
 196     my $t = find_encoding($to);
 197     croak("Unknown encoding '$to'") unless defined $t;
 198     my $uni = $f->decode($string,$check);
 199     return undef if ($check && length($string));
 200     $string = $t->encode($uni,$check);
 201     return undef if ($check && length($uni));
 202     return length($_[0] = $string);
 203 }
 204
 205 sub encode_utf8
 206 {
 207     my ($str) = @_;
 208   utf8::encode($str);
 209     return $str;
 210 }
 211
 212 sub decode_utf8
 213 {
 214     my ($str) = @_;
 215     return undef unless utf8::decode($str);
 216     return $str;
 217 }
 218
 219 require Encode::Encoding;
 220 require Encode::XS;
 221 require Encode::Internal;
 222 require Encode::Unicode;
 223 require Encode::utf8;
 224 require Encode::iso10646_1;
 225 require Encode::ucs2_le;
 226
 227 1;
 228
 229 __END__
 230
 231 =head1 NAME
 232
 233 Encode - character encodings
 234
 235 =head1 SYNOPSIS
 236
 237     use Encode;
 238
 239 =head1 DESCRIPTION
 240
 241 The C<Encode> module provides the interfaces between Perl's strings
 242 and the rest of the system.  Perl strings are sequences of B<characters>.
 243
 244 To find more about character encodings, please consult
 245 L<Encode::Details>. This document focuses on programming references.
 246
 247 =head1 PERL ENCODING API
 248
 249 =head2 Generic Encoding Interface
 250
 251 =over 4
 252
 253 =item $bytes  = encode(ENCODING, $string[, CHECK])
 254
 255 Encodes string from Perl's internal form into I<ENCODING> and returns
 256 a sequence of octets.  For CHECK see L</"Handling Malformed Data">.
 257
 258 For example to convert (internally UTF-8 encoded) Unicode data
 259 to octets:
 260
 261         $octets = encode("utf8", $unicode);
 262
 263 =item $string = decode(ENCODING, $bytes[, CHECK])
 264
 265 Decode sequence of octets assumed to be in I<ENCODING> into Perl's
 266 internal form and returns the resulting string.  For CHECK see
 267 L</"Handling Malformed Data">.
 268
 269 For example to convert ISO-8859-1 data to UTF-8:
 270
 271         $utf8 = decode("latin1", $latin1);
 272
 273 =item from_to($string, FROM_ENCODING, TO_ENCODING[, CHECK])
 274
 275 Convert B<in-place> the data between two encodings.  How did the data
 276 in $string originally get to be in FROM_ENCODING?  Either using
 277 encode() or through PerlIO: See L</"Encoding and IO">.  For CHECK
 278 see L</"Handling Malformed Data">.
 279
 280 For example to convert ISO-8859-1 data to UTF-8:
 281
 282         from_to($data, "iso-8859-1", "utf-8");
 283
 284 and to convert it back:
 285
 286         from_to($data, "utf-8", "iso-8859-1");
 287
 288 Note that because the conversion happens in place, the data to be
 289 converted cannot be a string constant, it must be a scalar variable.
 290
 291 =back
 292
 293 =head2 Handling Malformed Data
 294
 295 If CHECK is not set, C<undef> is returned.  If the data is supposed to
 296 be UTF-8, an optional lexical warning (category utf8) is given.  If
 297 CHECK is true but not a code reference, dies.
 298
 299 It would desirable to have a way to indicate that transform should use
 300 the encodings "replacement character" - no such mechanism is defined yet.
 301
 302 It is also planned to allow I<CHECK> to be a code reference.
 303
 304 This is not yet implemented as there are design issues with what its
 305 arguments should be and how it returns its results.
 306
 307 =over 4
 308
 309 =item Scheme 1
 310
 311 Passed remaining fragment of string being processed.
 312 Modifies it in place to remove bytes/characters it can understand
 313 and returns a string used to represent them.
 314 e.g.
 315
 316  sub fixup {
 317    my $ch = substr($_[0],0,1,'');
 318    return sprintf("\x{%02X}",ord($ch);
 319  }
 320
 321 This scheme is close to how underlying C code for Encode works, but gives
 322 the fixup routine very little context.
 323
 324 =item Scheme 2
 325
 326 Passed original string, and an index into it of the problem area, and
 327 output string so far.  Appends what it will to output string and
 328 returns new index into original string.  For example:
 329
 330  sub fixup {
 331    # my ($s,$i,$d) = @_;
 332    my $ch = substr($_[0],$_[1],1);
 333    $_[2] .= sprintf("\x{%02X}",ord($ch);
 334    return $_[1]+1;
 335  }
 336
 337 This scheme gives maximal control to the fixup routine but is more
 338 complicated to code, and may need internals of Encode to be tweaked to
 339 keep original string intact.
 340
 341 =item Other Schemes
 342
 343 Hybrids of above.
 344
 345 Multiple return values rather than in-place modifications.
 346
 347 Index into the string could be C<pos($str)> allowing C<s/\G...//>.
 348
 349 =back
 350
 351 =head2 UTF-8 / utf8
 352
 353 The Unicode consortium defines the UTF-8 standard as a way of encoding
 354 the entire Unicode repertoire as sequences of octets.  This encoding is
 355 expected to become very widespread. Perl can use this form internally
 356 to represent strings, so conversions to and from this form are
 357 particularly efficient (as octets in memory do not have to change,
 358 just the meta-data that tells Perl how to treat them).
 359
 360 =over 4
 361
 362 =item $bytes = encode_utf8($string);
 363
 364 The characters that comprise string are encoded in Perl's superset of UTF-8
 365 and the resulting octets returned as a sequence of bytes. All possible
 366 characters have a UTF-8 representation so this function cannot fail.
 367
 368 =item $string = decode_utf8($bytes [, CHECK]);
 369
 370 The sequence of octets represented by $bytes is decoded from UTF-8
 371 into a sequence of logical characters. Not all sequences of octets
 372 form valid UTF-8 encodings, so it is possible for this call to fail.
 373 For CHECK see L</"Handling Malformed Data">.
 374
 375 =back
 376
 377 =head2 Listing available encodings
 378
 379   use Encode;
 380   @list = Encode->encodings();
 381
 382 Returns a list of the canonical names of the available encodings that
 383 are loaded.  To get a list of all available encodings including the
 384 ones that are not loaded yet, say
 385
 386   @all_encodings = Encode->encodings(":all");
 387
 388 Or you can give the name of specific module.
 389
 390   @with_jp = Encode->encodings("Encode/JP.pm");
 391
 392 Note in this case you have to say C<"Encode/JP.pm"> instead of
 393 C<"Encode::JP">.
 394
 395 To find which encodings are supported by this package in details,
 396 see L<Encode::Supported>.
 397
 398 =head2 Defining Aliases
 399
 400   use Encode;
 401   use Encode::Alias;
 402   define_alias(newName => ENCODING);
 403
 404 Allows newName to be used as am alias for ENCODING. ENCODING may be
 405 either the name of an encoding or and encoding object (as above).
 406
 407 See L<Encode::Alias> on details.
 408
 409 =head1 Defining Encodings
 410
 411     use Encode qw(define_alias);
 412     define_encoding($object, 'canonicalName' [, alias...]);
 413
 414 Causes I<canonicalName> to be associated with I<$object>.  The object
 415 should provide the interface described in L<Encode::Encoding>
 416 below.  If more than two arguments are provided then additional
 417 arguments are taken as aliases for I<$object> as for C<define_alias>.
 418
 419 =head1 Encoding and IO
 420
 421 It is very common to want to do encoding transformations when
 422 reading or writing files, network connections, pipes etc.
 423 If Perl is configured to use the new 'perlio' IO system then
 424 C<Encode> provides a "layer" (See L<perliol>) which can transform
 425 data as it is read or written.
 426
 427 Here is how the blind poet would modernise the encoding:
 428
 429     use Encode;
 430     open(my $iliad,'<:encoding(iso-8859-7)','iliad.greek');
 431     open(my $utf8,'>:utf8','iliad.utf8');
 432     my @epic = <$iliad>;
 433     print $utf8 @epic;
 434     close($utf8);
 435     close($illiad);
 436
 437 In addition the new IO system can also be configured to read/write
 438 UTF-8 encoded characters (as noted above this is efficient):
 439
 440     open(my $fh,'>:utf8','anything');
 441     print $fh "Any \x{0021} string \N{SMILEY FACE}\n";
 442
 443 Either of the above forms of "layer" specifications can be made the default
 444 for a lexical scope with the C<use open ...> pragma. See L<open>.
 445
 446 Once a handle is open is layers can be altered using C<binmode>.
 447
 448 Without any such configuration, or if Perl itself is built using
 449 system's own IO, then write operations assume that file handle accepts
 450 only I<bytes> and will C<die> if a character larger than 255 is
 451 written to the handle. When reading, each octet from the handle
 452 becomes a byte-in-a-character. Note that this default is the same
 453 behaviour as bytes-only languages (including Perl before v5.6) would
 454 have, and is sufficient to handle native 8-bit encodings
 455 e.g. iso-8859-1, EBCDIC etc. and any legacy mechanisms for handling
 456 other encodings and binary data.
 457
 458 In other cases it is the programs responsibility to transform
 459 characters into bytes using the API above before doing writes, and to
 460 transform the bytes read from a handle into characters before doing
 461 "character operations" (e.g. C<lc>, C</\W+/>, ...).
 462
 463 You can also use PerlIO to convert larger amounts of data you don't
 464 want to bring into memory.  For example to convert between ISO-8859-1
 465 (Latin 1) and UTF-8 (or UTF-EBCDIC in EBCDIC machines):
 466
 467     open(F, "<:encoding(iso-8859-1)", "data.txt") or die $!;
 468     open(G, ">:utf8",                 "data.utf") or die $!;
 469     while (<F>) { print G }
 470
 471     # Could also do "print G <F>" but that would pull
 472     # the whole file into memory just to write it out again.
 473
 474 More examples:
 475
 476     open(my $f, "<:encoding(cp1252)")
 477     open(my $g, ">:encoding(iso-8859-2)")
 478     open(my $h, ">:encoding(latin9)")       # iso-8859-15
 479
 480 See L<PerlIO> for more information.
 481
 482 See also L<encoding> for how to change the default encoding of the
 483 data in your script.
 484
 485 =head1 Messing with Perl's Internals
 486
 487 The following API uses parts of Perl's internals in the current
 488 implementation.  As such they are efficient, but may change.
 489
 490 =over 4
 491
 492 =item is_utf8(STRING [, CHECK])
 493
 494 [INTERNAL] Test whether the UTF-8 flag is turned on in the STRING.
 495 If CHECK is true, also checks the data in STRING for being well-formed
 496 UTF-8.  Returns true if successful, false otherwise.
 497
 498 =item _utf8_on(STRING)
 499
 500 [INTERNAL] Turn on the UTF-8 flag in STRING.  The data in STRING is
 501 B<not> checked for being well-formed UTF-8.  Do not use unless you
 502 B<know> that the STRING is well-formed UTF-8.  Returns the previous
 503 state of the UTF-8 flag (so please don't test the return value as
 504 I<not> success or failure), or C<undef> if STRING is not a string.
 505
 506 =item _utf8_off(STRING)
 507
 508 [INTERNAL] Turn off the UTF-8 flag in STRING.  Do not use frivolously.
 509 Returns the previous state of the UTF-8 flag (so please don't test the
 510 return value as I<not> success or failure), or C<undef> if STRING is
 511 not a string.
 512
 513 =back
 514
 515 =head1 SEE ALSO
 516
 517 L<Encode::Details>,
 518 L<Encode::Encoding>,
 519 L<Encode::Supported>,
 520 L<PerlIO>,
 521 L<encoding>,
 522 L<perlebcdic>,
 523 L<perlfunc/open>,
 524 L<perlunicode>,
 525 L<utf8>,
 526 the Perl Unicode Mailing List E<lt>perl-unicode@perl.orgE<gt>
 527
 528 =cut