3 our $VERSION = do { my @r = (q$Revision: 1.58 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };
6 XSLoader::load 'Encode';
9 our @ISA = qw(Exporter);
11 # Public, encouraged API is exported by default
14 decode decode_utf8 encode encode_utf8
15 encodings find_encoding
18 our @FB_FLAGS = qw(DIE_ON_ERR WARN_ON_ERR RETURN_ON_ERR LEAVE_SRC PERLQQ);
19 our @FB_CONSTS = qw(FB_DEFAULT FB_QUIET FB_WARN FB_PERLQQ FB_CROAK);
24 _utf8_off _utf8_on define_encoding from_to is_16bit is_8bit
25 is_utf8 perlio_ok resolve_alias utf8_downgrade utf8_upgrade
27 @FB_FLAGS, @FB_CONSTS,
32 all => [ @EXPORT, @EXPORT_OK ],
33 fallbacks => [ @FB_CONSTS ],
34 fallback_all => [ @FB_CONSTS, @FB_FLAGS ],
37 # Documentation moved after __END__ for speed - NI-S
41 our $ON_EBCDIC = (ord("A") == 193);
45 # Make a %Encoding package variable to allow a certain amount of cheating
48 require Encode::Config;
49 eval { require Encode::ConfigLocal };
54 my @modules = (@_ and $_[0] eq ":all") ? values %ExtModule : @_;
55 for my $mod (@modules){
56 $mod =~ s,::,/,g or $mod = "Encode/$mod";
58 $DEBUG and warn "about to require $mod;";
59 eval { require $mod; };
61 my %modules = map {$_ => 1} @modules;
63 sort { lc $a cmp lc $b }
64 grep {!/^(?:Internal|Unicode)$/o} keys %Encoding;
68 my $obj = ref($_[0]) ? $_[0] : find_encoding($_[0]);
69 $obj->can("perlio_ok") and return $obj->perlio_ok();
70 return 0; # safety net
77 $Encoding{$name} = $obj;
79 define_alias($lc => $obj) unless $lc eq $name;
83 define_alias($alias,$obj);
90 my ($class,$name,$skip_external) = @_;
92 if (ref($name) && $name->can('new_sequence'))
97 if (exists $Encoding{$name})
99 return $Encoding{$name};
101 if (exists $Encoding{$lc})
103 return $Encoding{$lc};
106 my $oc = $class->find_alias($name);
107 return $oc if defined $oc;
109 $oc = $class->find_alias($lc) if $lc ne $name;
110 return $oc if defined $oc;
112 unless ($skip_external)
114 if (my $mod = $ExtModule{$name} || $ExtModule{$lc}){
115 $mod =~ s,::,/,g ; $mod .= '.pm';
116 eval{ require $mod; };
117 return $Encoding{$name} if exists $Encoding{$name};
125 my ($name,$skip_external) = @_;
126 return __PACKAGE__->getEncoding($name,$skip_external);
130 my $obj = find_encoding(shift);
131 defined $obj and return $obj->name;
137 my ($name,$string,$check) = @_;
139 my $enc = find_encoding($name);
140 croak("Unknown encoding '$name'") unless defined $enc;
141 my $octets = $enc->encode($string,$check);
142 return undef if ($check && length($string));
148 my ($name,$octets,$check) = @_;
150 my $enc = find_encoding($name);
151 croak("Unknown encoding '$name'") unless defined $enc;
152 my $string = $enc->decode($octets,$check);
153 $_[1] = $octets if $check;
159 my ($string,$from,$to,$check) = @_;
161 my $f = find_encoding($from);
162 croak("Unknown encoding '$from'") unless defined $f;
163 my $t = find_encoding($to);
164 croak("Unknown encoding '$to'") unless defined $t;
165 my $uni = $f->decode($string,$check);
166 return undef if ($check && length($string));
167 $string = $t->encode($uni,$check);
168 return undef if ($check && length($uni));
169 return defined($_[0] = $string) ? length($string) : undef ;
182 return undef unless utf8::decode($str);
186 predefine_encodings();
189 # This is to restore %Encoding if really needed;
191 sub predefine_encodings{
193 # was in Encode::UTF_EBCDIC
194 package Encode::UTF_EBCDIC;
195 *name = sub{ shift->{'Name'} };
196 *new_sequence = sub{ return $_[0] };
198 my ($obj,$str,$chk) = @_;
200 for (my $i = 0; $i < length($str); $i++) {
202 chr(utf8::unicode_to_native(ord(substr($str,$i,1))));
208 my ($obj,$str,$chk) = @_;
210 for (my $i = 0; $i < length($str); $i++) {
212 chr(utf8::native_to_unicode(ord(substr($str,$i,1))));
217 $Encode::Encoding{Unicode} =
218 bless {Name => "UTF_EBCDIC"} => "Encode::UTF_EBCDIC";
220 # was in Encode::UTF_EBCDIC
221 package Encode::Internal;
222 *name = sub{ shift->{'Name'} };
223 *new_sequence = sub{ return $_[0] };
225 my ($obj,$str,$chk) = @_;
231 $Encode::Encoding{Unicode} =
232 bless {Name => "Internal"} => "Encode::Internal";
236 # was in Encode::utf8
237 package Encode::utf8;
238 *name = sub{ shift->{'Name'} };
239 *new_sequence = sub{ return $_[0] };
241 my ($obj,$octets,$chk) = @_;
242 my $str = Encode::decode_utf8($octets);
250 my ($obj,$string,$chk) = @_;
251 my $octets = Encode::encode_utf8($string);
255 $Encode::Encoding{utf8} =
256 bless {Name => "utf8"} => "Encode::utf8";
266 Encode - character encodings
272 =head2 Table of Contents
274 Encode consists of a collection of modules whose details are too big
275 to fit in one document. This POD itself explains the top-level APIs
276 and general topics at a glance. For other topics and more details,
280 --------------------------------------------------------
281 Encode::Alias Alias definitions to encodings
282 Encode::Encoding Encode Implementation Base Class
283 Encode::Supported List of Supported Encodings
284 Encode::CN Simplified Chinese Encodings
285 Encode::JP Japanese Encodings
286 Encode::KR Korean Encodings
287 Encode::TW Traditional Chinese Encodings
288 --------------------------------------------------------
292 The C<Encode> module provides the interfaces between Perl's strings
293 and the rest of the system. Perl strings are sequences of
296 The repertoire of characters that Perl can represent is at least that
297 defined by the Unicode Consortium. On most platforms the ordinal
298 values of the characters (as returned by C<ord(ch)>) is the "Unicode
299 codepoint" for the character (the exceptions are those platforms where
300 the legacy encoding is some variant of EBCDIC rather than a super-set
301 of ASCII - see L<perlebcdic>).
303 Traditionally, computer data has been moved around in 8-bit chunks
304 often called "bytes". These chunks are also known as "octets" in
305 networking standards. Perl is widely used to manipulate data of many
306 types - not only strings of characters representing human or computer
307 languages but also "binary" data being the machine's representation of
308 numbers, pixels in an image - or just about anything.
310 When Perl is processing "binary data", the programmer wants Perl to
311 process "sequences of bytes". This is not a problem for Perl - as a
312 byte has 256 possible values, it easily fits in Perl's much larger
321 I<character>: a character in the range 0..(2**32-1) (or more).
322 (What Perl's strings are made of.)
326 I<byte>: a character in the range 0..255
327 (A special case of a Perl character.)
331 I<octet>: 8 bits of data, with ordinal values 0..255
332 (Term for bytes passed to or from a non-Perl context, e.g. a disk file.)
336 The marker [INTERNAL] marks Internal Implementation Details, in
337 general meant only for those who think they know what they are doing,
338 and such details may change in future releases.
340 =head1 PERL ENCODING API
344 =item $octets = encode(ENCODING, $string[, CHECK])
346 Encodes a string from Perl's internal form into I<ENCODING> and returns
347 a sequence of octets. ENCODING can be either a canonical name or
348 an alias. For encoding names and aliases, see L</"Defining Aliases">.
349 For CHECK, see L</"Handling Malformed Data">.
351 For example, to convert (internally UTF-8 encoded) Unicode string to
352 iso-8859-1 (also known as Latin1),
354 $octets = encode("iso-8859-1", $unicode);
356 =item $string = decode(ENCODING, $octets[, CHECK])
358 Decodes a sequence of octets assumed to be in I<ENCODING> into Perl's
359 internal form and returns the resulting string. As in encode(),
360 ENCODING can be either a canonical name or an alias. For encoding names
361 and aliases, see L</"Defining Aliases">. For CHECK, see
362 L</"Handling Malformed Data">.
364 For example, to convert ISO-8859-1 data to UTF-8:
366 $utf8 = decode("iso-8859-1", $latin1);
368 =item [$length =] from_to($string, FROM_ENCODING, TO_ENCODING [,CHECK])
370 Converts B<in-place> data between two encodings.
371 For example, to convert ISO-8859-1 data to UTF-8:
373 from_to($data, "iso-8859-1", "utf-8");
375 and to convert it back:
377 from_to($data, "utf-8", "iso-8859-1");
379 Note that because the conversion happens in place, the data to be
380 converted cannot be a string constant; it must be a scalar variable.
382 from_to() returns the length of the converted string on success, undef
389 The Unicode Consortium defines the UTF-8 transformation format as a
390 way of encoding the entire Unicode repertoire as sequences of octets.
391 This encoding is expected to become very widespread. Perl can use this
392 form internally to represent strings, so conversions to and from this
393 form are particularly efficient (as octets in memory do not have to
394 change, just the meta-data that tells Perl how to treat them).
398 =item $octets = encode_utf8($string);
400 The characters that comprise $string are encoded in Perl's superset of
401 UTF-8 and the resulting octets are returned as a sequence of bytes. All
402 possible characters have a UTF-8 representation so this function cannot
405 =item $string = decode_utf8($octets [, CHECK]);
407 The sequence of octets represented by $octets is decoded from UTF-8
408 into a sequence of logical characters. Not all sequences of octets
409 form valid UTF-8 encodings, so it is possible for this call to fail.
410 For CHECK, see L</"Handling Malformed Data">.
414 =head2 Listing available encodings
417 @list = Encode->encodings();
419 Returns a list of the canonical names of the available encodings that
420 are loaded. To get a list of all available encodings including the
421 ones that are not loaded yet, say
423 @all_encodings = Encode->encodings(":all");
425 Or you can give the name of a specific module.
427 @with_jp = Encode->encodings("Encode::JP");
429 When "::" is not in the name, "Encode::" is assumed.
431 @ebcdic = Encode->encodings("EBCDIC");
433 To find out in detail which encodings are supported by this package,
434 see L<Encode::Supported>.
436 =head2 Defining Aliases
438 To add a new alias to a given encoding, use:
442 define_alias(newName => ENCODING);
444 After that, newName can be used as an alias for ENCODING.
445 ENCODING may be either the name of an encoding or an
448 But before you do so, make sure the alias is nonexistent with
449 C<resolve_alias()>, which returns the canonical name thereof.
452 Encode::resolve_alias("latin1") eq "iso-8859-1" # true
453 Encode::resolve_alias("iso-8859-12") # false; nonexistent
454 Encode::resolve_alias($name) eq $name # true if $name is canonical
456 resolve_alias() does not need C<use Encode::Alias>; it can be
457 exported via C<use Encode qw(resolve_alias)>.
459 See L<Encode::Alias> for details.
461 =head1 Encoding via PerlIO
463 If your perl supports I<PerlIO>, you can use a PerlIO layer to decode
464 and encode directly via a filehandle. The following two examples
465 are totally identical in their functionality.
468 open my $in, "<:encoding(shiftjis)", $infile or die;
469 open my $out, ">:encoding(euc-jp)", $outfile or die;
473 open my $in, "<", $infile or die;
474 open my $out, ">", $outfile or die;
476 from_to($_, "shiftjis", "euc-jp", 1);
479 Unfortunately, there may be encodings are PerlIO-savvy. You can check
480 if your encoding is supported by PerlIO by calling the C<perlio_ok>
483 Encode::perlio_ok("hz"); # False
484 find_encoding("euc-cn")->perlio_ok; # True where PerlIO is available
486 use Encode qw(perlio_ok); # exported upon request
489 Fortunately, all encodings that come with Encode core are PerlIO-savvy
490 except for hz and ISO-2022-kr. See L<Encode::Encoding> for details.
492 For gory details, see L<Encode::PerlIO>.
494 =head1 Handling Malformed Data
498 The I<CHECK> argument is used as follows. When you omit it,
499 the behaviour is the same as if you had passed a value of 0 for
502 =item I<CHECK> = Encode::FB_DEFAULT ( == 0)
504 If I<CHECK> is 0, (en|de)code will put a I<substitution character>
505 in place of a malformed character. For UCM-based encodings,
506 E<lt>subcharE<gt> will be used. For Unicode, "\x{FFFD}" is used.
507 If the data is supposed to be UTF-8, an optional lexical warning
508 (category utf8) is given.
510 =item I<CHECK> = Encode::DIE_ON_ERROR (== 1)
512 If I<CHECK> is 1, methods will die immediately with an error
513 message. Therefore, when I<CHECK> is set to 1, you should trap the
514 fatal error with eval{} unless you really want to let it die on error.
516 =item I<CHECK> = Encode::FB_QUIET
518 If I<CHECK> is set to Encode::FB_QUIET, (en|de)code will immediately
519 return the portion of the data that has been processed so far when
520 an error occurs. The data argument will be overwritten with
521 everything after that point (that is, the unprocessed part of data).
522 This is handy when you have to call decode repeatedly in the case
523 where your source data may contain partial multi-byte character
524 sequences, for example because you are reading with a fixed-width
525 buffer. Here is some sample code that does exactly this:
528 while(defined(read $fh, $buffer, 256)){
529 # buffer may end in a partial character so we append
531 $utf8 .= decode($encoding, $data, ENCODE::FB_QUIET);
532 # $data now contains the unprocessed partial character
535 =item I<CHECK> = Encode::FB_WARN
537 This is the same as above, except that it warns on error. Handy when
538 you are debugging the mode above.
540 =item perlqq mode (I<CHECK> = Encode::FB_PERLQQ)
542 For encodings that are implemented by Encode::XS, CHECK ==
543 Encode::FB_PERLQQ turns (en|de)code into C<perlqq> fallback mode.
545 When you decode, '\xI<XX>' will be inserted for a malformed character,
546 where I<XX> is the hex representation of the octet that could not be
547 decoded to utf8. And when you encode, '\x{I<xxxx>}' will be inserted,
548 where I<xxxx> is the Unicode ID of the character that cannot be found
549 in the character repertoire of the encoding.
553 These modes are actually set via a bitmask. Here is how the FB_XX
554 constants are laid out. You can import the FB_XX constants via
555 C<use Encode qw(:fallbacks)>; you can import the generic bitmask
556 constants via C<use Encode qw(:fallback_all)>.
558 FB_DEFAULT FB_CROAK FB_QUIET FB_WARN FB_PERLQQ
561 RETURN_ON_ERR 0x0004 X X
565 =head2 Unimplemented fallback schemes
567 In the future, you will be able to use a code reference to a callback
568 function for the value of I<CHECK> but its API is still undecided.
570 =head1 Defining Encodings
572 To define a new encoding, use:
574 use Encode qw(define_alias);
575 define_encoding($object, 'canonicalName' [, alias...]);
577 I<canonicalName> will be associated with I<$object>. The object
578 should provide the interface described in L<Encode::Encoding>.
579 If more than two arguments are provided then additional
580 arguments are taken as aliases for I<$object>, as for C<define_alias>.
582 See L<Encode::Encoding> for more details.
584 =head1 Messing with Perl's Internals
586 The following API uses parts of Perl's internals in the current
587 implementation. As such, they are efficient but may change.
591 =item is_utf8(STRING [, CHECK])
593 [INTERNAL] Tests whether the UTF-8 flag is turned on in the STRING.
594 If CHECK is true, also checks the data in STRING for being well-formed
595 UTF-8. Returns true if successful, false otherwise.
597 =item _utf8_on(STRING)
599 [INTERNAL] Turns on the UTF-8 flag in STRING. The data in STRING is
600 B<not> checked for being well-formed UTF-8. Do not use unless you
601 B<know> that the STRING is well-formed UTF-8. Returns the previous
602 state of the UTF-8 flag (so please don't treat the return value as
603 indicating success or failure), or C<undef> if STRING is not a string.
605 =item _utf8_off(STRING)
607 [INTERNAL] Turns off the UTF-8 flag in STRING. Do not use frivolously.
608 Returns the previous state of the UTF-8 flag (so please don't treat the
609 return value as indicating success or failure), or C<undef> if STRING is
617 L<Encode::Supported>,
624 the Perl Unicode Mailing List E<lt>perl-unicode@perl.orgE<gt>
628 This project was originated by Nick Ing-Simmons and later maintained
629 by Dan Kogai E<lt>dankogai@dan.co.jpE<gt>. See AUTHORS for a full list
630 of people involved. For any questions, use
631 E<lt>perl-unicode@perl.orgE<gt> so others can share.