3 our $VERSION = do { my @r = (q$Revision: 1.50 $ =~ /\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 exists $INC{"PerlIO/encoding.pm"} or return 0;
69 my $stash = ref($_[0]);
70 $stash ||= ref(find_encoding($_[0]));
71 return ($stash eq "Encode::XS" || $stash eq "Encode::Unicode");
78 $Encoding{$name} = $obj;
80 define_alias($lc => $obj) unless $lc eq $name;
84 define_alias($alias,$obj);
91 my ($class,$name,$skip_external) = @_;
93 if (ref($name) && $name->can('new_sequence'))
98 if (exists $Encoding{$name})
100 return $Encoding{$name};
102 if (exists $Encoding{$lc})
104 return $Encoding{$lc};
107 my $oc = $class->find_alias($name);
108 return $oc if defined $oc;
110 $oc = $class->find_alias($lc) if $lc ne $name;
111 return $oc if defined $oc;
113 unless ($skip_external)
115 if (my $mod = $ExtModule{$name} || $ExtModule{$lc}){
116 $mod =~ s,::,/,g ; $mod .= '.pm';
117 eval{ require $mod; };
118 return $Encoding{$name} if exists $Encoding{$name};
126 my ($name,$skip_external) = @_;
127 return __PACKAGE__->getEncoding($name,$skip_external);
131 my $obj = find_encoding(shift);
132 defined $obj and return $obj->name;
138 my ($name,$string,$check) = @_;
140 my $enc = find_encoding($name);
141 croak("Unknown encoding '$name'") unless defined $enc;
142 my $octets = $enc->encode($string,$check);
143 return undef if ($check && length($string));
149 my ($name,$octets,$check) = @_;
151 my $enc = find_encoding($name);
152 croak("Unknown encoding '$name'") unless defined $enc;
153 my $string = $enc->decode($octets,$check);
154 $_[1] = $octets if $check;
160 my ($string,$from,$to,$check) = @_;
162 my $f = find_encoding($from);
163 croak("Unknown encoding '$from'") unless defined $f;
164 my $t = find_encoding($to);
165 croak("Unknown encoding '$to'") unless defined $t;
166 my $uni = $f->decode($string,$check);
167 return undef if ($check && length($string));
168 $string = $t->encode($uni,$check);
169 return undef if ($check && length($uni));
170 return defined($_[0] = $string) ? length($string) : undef ;
183 return undef unless utf8::decode($str);
187 predefine_encodings();
190 # This is to restore %Encoding if really needed;
192 sub predefine_encodings{
194 # was in Encode::UTF_EBCDIC
195 package Encode::UTF_EBCDIC;
196 *name = sub{ shift->{'Name'} };
197 *new_sequence = sub{ return $_[0] };
199 my ($obj,$str,$chk) = @_;
201 for (my $i = 0; $i < length($str); $i++) {
203 chr(utf8::unicode_to_native(ord(substr($str,$i,1))));
209 my ($obj,$str,$chk) = @_;
211 for (my $i = 0; $i < length($str); $i++) {
213 chr(utf8::native_to_unicode(ord(substr($str,$i,1))));
218 $Encode::Encoding{Unicode} =
219 bless {Name => "UTF_EBCDIC"} => "Encode::UTF_EBCDIC";
221 # was in Encode::UTF_EBCDIC
222 package Encode::Internal;
223 *name = sub{ shift->{'Name'} };
224 *new_sequence = sub{ return $_[0] };
226 my ($obj,$str,$chk) = @_;
232 $Encode::Encoding{Unicode} =
233 bless {Name => "Internal"} => "Encode::Internal";
237 # was in Encode::utf8
238 package Encode::utf8;
239 *name = sub{ shift->{'Name'} };
240 *new_sequence = sub{ return $_[0] };
242 my ($obj,$octets,$chk) = @_;
243 my $str = Encode::decode_utf8($octets);
251 my ($obj,$string,$chk) = @_;
252 my $octets = Encode::encode_utf8($string);
256 $Encode::Encoding{utf8} =
257 bless {Name => "utf8"} => "Encode::utf8";
261 require Encode::Encoding;
262 @Encode::XS::ISA = qw(Encode::Encoding);
271 Encode - character encodings
278 =head2 Table of Contents
280 Encode consists of a collection of modules which details are too big
281 to fit in one document. This POD itself explains the top-level APIs
282 and general topics at a glance. For other topics and more details,
286 --------------------------------------------------------
287 Encode::Alias Alias definitions to encodings
288 Encode::Encoding Encode Implementation Base Class
289 Encode::Supported List of Supported Encodings
290 Encode::CN Simplified Chinese Encodings
291 Encode::JP Japanese Encodings
292 Encode::KR Korean Encodings
293 Encode::TW Traditional Chinese Encodings
294 --------------------------------------------------------
298 The C<Encode> module provides the interfaces between Perl's strings
299 and the rest of the system. Perl strings are sequences of
302 The repertoire of characters that Perl can represent is at least that
303 defined by the Unicode Consortium. On most platforms the ordinal
304 values of the characters (as returned by C<ord(ch)>) is the "Unicode
305 codepoint" for the character (the exceptions are those platforms where
306 the legacy encoding is some variant of EBCDIC rather than a super-set
307 of ASCII - see L<perlebcdic>).
309 Traditionally computer data has been moved around in 8-bit chunks
310 often called "bytes". These chunks are also known as "octets" in
311 networking standards. Perl is widely used to manipulate data of many
312 types - not only strings of characters representing human or computer
313 languages but also "binary" data being the machines representation of
314 numbers, pixels in an image - or just about anything.
316 When Perl is processing "binary data" the programmer wants Perl to
317 process "sequences of bytes". This is not a problem for Perl - as a
318 byte has 256 possible values it easily fits in Perl's much larger
327 I<character>: a character in the range 0..(2**32-1) (or more).
328 (What Perl's strings are made of.)
332 I<byte>: a character in the range 0..255
333 (A special case of a Perl character.)
337 I<octet>: 8 bits of data, with ordinal values 0..255
338 (Term for bytes passed to or from a non-Perl context, e.g. disk file.)
342 The marker [INTERNAL] marks Internal Implementation Details, in
343 general meant only for those who think they know what they are doing,
344 and such details may change in future releases.
346 =head1 PERL ENCODING API
350 =item $octets = encode(ENCODING, $string[, CHECK])
352 Encodes string from Perl's internal form into I<ENCODING> and returns
353 a sequence of octets. ENCODING can be either a canonical name or
354 alias. For encoding names and aliases, see L</"Defining Aliases">.
355 For CHECK see L</"Handling Malformed Data">.
357 For example to convert (internally UTF-8 encoded) Unicode string to
358 iso-8859-1 (also known as Latin1),
360 $octets = encode("iso-8859-1", $unicode);
362 =item $string = decode(ENCODING, $octets[, CHECK])
364 Decode sequence of octets assumed to be in I<ENCODING> into Perl's
365 internal form and returns the resulting string. as in encode(),
366 ENCODING can be either a canonical name or alias. For encoding names
367 and aliases, see L</"Defining Aliases">. For CHECK see
368 L</"Handling Malformed Data">.
370 For example to convert ISO-8859-1 data to UTF-8:
372 $utf8 = decode("iso-8859-1", $latin1);
374 =item [$length =] from_to($string, FROM_ENCODING, TO_ENCODING [,CHECK])
376 Convert B<in-place> the data between two encodings.
377 For example to convert ISO-8859-1 data to UTF-8:
379 from_to($data, "iso-8859-1", "utf-8");
381 and to convert it back:
383 from_to($data, "utf-8", "iso-8859-1");
385 Note that because the conversion happens in place, the data to be
386 converted cannot be a string constant, it must be a scalar variable.
388 from_to() return the length of the converted string on success, undef
395 The Unicode consortium defines the UTF-8 standard as a way of encoding
396 the entire Unicode repertoire as sequences of octets. This encoding is
397 expected to become very widespread. Perl can use this form internally
398 to represent strings, so conversions to and from this form are
399 particularly efficient (as octets in memory do not have to change,
400 just the meta-data that tells Perl how to treat them).
404 =item $octets = encode_utf8($string);
406 The characters that comprise string are encoded in Perl's superset of UTF-8
407 and the resulting octets returned as a sequence of bytes. All possible
408 characters have a UTF-8 representation so this function cannot fail.
410 =item $string = decode_utf8($octets [, CHECK]);
412 The sequence of octets represented by $octets is decoded from UTF-8
413 into a sequence of logical characters. Not all sequences of octets
414 form valid UTF-8 encodings, so it is possible for this call to fail.
415 For CHECK see L</"Handling Malformed Data">.
419 =head2 Listing available encodings
422 @list = Encode->encodings();
424 Returns a list of the canonical names of the available encodings that
425 are loaded. To get a list of all available encodings including the
426 ones that are not loaded yet, say
428 @all_encodings = Encode->encodings(":all");
430 Or you can give the name of specific module.
432 @with_jp = Encode->encodings("Encode::JP");
434 When "::" is not in the name, "Encode::" is assumed.
436 @ebcdic = Encode->encodings("EBCDIC");
438 To find which encodings are supported by this package in details,
439 see L<Encode::Supported>.
441 =head2 Defining Aliases
443 To add new alias to a given encoding, Use;
447 define_alias(newName => ENCODING);
449 After that, newName can be used as an alias for ENCODING.
450 ENCODING may be either the name of an encoding or an
453 But before you do so, make sure the alias is nonexistent with
454 C<resolve_alias()>, which returns the canonical name thereof.
457 Encode::resolve_alias("latin1") eq "iso-8859-1" # true
458 Encode::resolve_alias("iso-8859-12") # false; nonexistent
459 Encode::resolve_alias($name) eq $name # true if $name is canonical
461 This resolve_alias() does not need C<use Encode::Alias> and is
462 exported via C<use encode qw(resolve_alias)>.
464 See L<Encode::Alias> on details.
466 =head1 Encoding via PerlIO
468 If your perl supports I<PerlIO>, you can use PerlIO layer to directly
469 decode and encode via filehandle. The following two examples are
470 totally identical by functionality.
473 open my $in, "<:encoding(shiftjis)", $infile or die;
474 open my $out, ">:encoding(euc-jp)", $outfile or die;
478 open my $in, $infile or die;
479 open my $out, $outfile or die;
481 from_to($_, "shiftjis", "euc", 1);
484 Unfortunately, not all encodings are PerlIO-savvy. You can check if
485 your encoding is supported by PerlIO by C<perlio_ok> method.
487 Encode::perlio_ok("iso-20220jp"); # false
488 find_encoding("iso-2022-jp")->perlio_ok; # false
489 use Encode qw(perlio_ok); # exported upon request
490 perlio_ok("euc-jp") # true if PerlIO is enabled
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, it is
499 identical to I<CHECK> = 0.
501 =item I<CHECK> = Encode::FB_DEFAULT ( == 0)
503 If I<CHECK> is 0, (en|de)code will put I<substitution character> in
504 place of the malformed character. for UCM-based encodings,
505 E<lt>subcharE<gt> will be used. For Unicode, \xFFFD is used. If the
506 data is supposed to be UTF-8, an optional lexical warning (category
509 =item I<CHECK> = Encode::DIE_ON_ERROR (== 1)
511 If I<CHECK> is 1, methods will die immediately with an error
512 message. so when I<CHECK> is set, you should trap the fatal error
513 with eval{} unless you really want to let it die on error.
515 =item I<CHECK> = Encode::FB_QUIET
517 If I<CHECK> is set to Encode::FB_QUIET, (en|de)code will immediately
518 return processed part on error, with data passed via argument
519 overwritten with unprocessed part. This is handy when have to
520 repeatedly call because the source data is chopped in the middle for
521 some reasons, such as fixed-width buffer. Here is a sample code that
525 while(defined(read $fh, $buffer, 256)){
526 # buffer may end in partial character so we append
528 $utf8 .= decode($encoding, $data, ENCODE::FB_QUIET);
529 # $data now contains unprocessed partial character
532 =item I<CHECK> = Encode::FB_WARN
534 This is the same as above, except it warns on error. Handy when you
535 are debugging the mode above.
537 =item perlqq mode (I<CHECK> = Encode::FB_PERLQQ)
539 For encodings that are implemented by Encode::XS, CHECK ==
540 Encode::FB_PERLQQ turns (en|de)code into C<perlqq> fallback mode.
542 When you decode, '\xI<XX>' will be placed where I<XX> is the hex
543 representation of the octet that could not be decoded to utf8. And
544 when you encode, '\x{I<xxxx>}' will be placed where I<xxxx> is the
545 Unicode ID of the character that cannot be found in the character
546 repertoire of the encoding.
550 These modes are actually set via bitmask. here is how FB_XX are laid
551 out. for FB_XX you can import via C<use Encode qw(:fallbacks)> for
552 generic bitmask constants, you can import via
553 C<use Encode qw(:fallback_all)>.
555 FB_DEFAULT FB_CROAK FB_QUIET FB_WARN FB_PERLQQ
558 RETURN_ON_ERR 0x0004 X X
562 =head2 Unemplemented fallback schemes
564 In future you will be able to use a code reference to a callback
565 function for the value of I<CHECK> but its API is still undecided.
567 =head1 Defining Encodings
569 To define a new encoding, use:
571 use Encode qw(define_alias);
572 define_encoding($object, 'canonicalName' [, alias...]);
574 I<canonicalName> will be associated with I<$object>. The object
575 should provide the interface described in L<Encode::Encoding>
576 If more than two arguments are provided then additional
577 arguments are taken as aliases for I<$object> as for C<define_alias>.
579 See L<Encode::Encoding> for more details.
581 =head1 Messing with Perl's Internals
583 The following API uses parts of Perl's internals in the current
584 implementation. As such they are efficient, but may change.
588 =item is_utf8(STRING [, CHECK])
590 [INTERNAL] Test whether the UTF-8 flag is turned on in the STRING.
591 If CHECK is true, also checks the data in STRING for being well-formed
592 UTF-8. Returns true if successful, false otherwise.
594 =item _utf8_on(STRING)
596 [INTERNAL] Turn on the UTF-8 flag in STRING. The data in STRING is
597 B<not> checked for being well-formed UTF-8. Do not use unless you
598 B<know> that the STRING is well-formed UTF-8. Returns the previous
599 state of the UTF-8 flag (so please don't test the return value as
600 I<not> success or failure), or C<undef> if STRING is not a string.
602 =item _utf8_off(STRING)
604 [INTERNAL] Turn off the UTF-8 flag in STRING. Do not use frivolously.
605 Returns the previous state of the UTF-8 flag (so please don't test the
606 return value as I<not> success or failure), or C<undef> if STRING is
614 L<Encode::Supported>,
621 the Perl Unicode Mailing List E<lt>perl-unicode@perl.orgE<gt>
625 This project was originated by Nick Ing-Simmons and later maintained
626 by Dan Kogai E<lt>dankogai@dan.co.jpE<gt>. See AUTHORS for full list
627 of people involved. For any questions, use
628 E<lt>perl-unicode@perl.orgE<gt> so others can share.