package Encode;
use strict;
-our $VERSION = do { my @r = (q$Revision: 0.94 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };
+our $VERSION = do { my @r = (q$Revision: 1.51 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };
+our $DEBUG = 0;
require DynaLoader;
require Exporter;
our @ISA = qw(Exporter DynaLoader);
# Public, encouraged API is exported by default
-our @EXPORT = qw (
- encode
- decode
- encode_utf8
- decode_utf8
- find_encoding
- encodings
+
+our @EXPORT = qw(
+ decode decode_utf8 encode encode_utf8
+ encodings find_encoding
);
+our @FB_FLAGS = qw(DIE_ON_ERR WARN_ON_ERR RETURN_ON_ERR LEAVE_SRC PERLQQ);
+our @FB_CONSTS = qw(FB_DEFAULT FB_QUIET FB_WARN FB_PERLQQ FB_CROAK);
+
our @EXPORT_OK =
- qw(
- define_encoding
- define_alias
- from_to
- is_utf8
- is_8bit
- is_16bit
- utf8_upgrade
- utf8_downgrade
- _utf8_on
- _utf8_off
- );
+ (
+ qw(
+ _utf8_off _utf8_on define_encoding from_to is_16bit is_8bit
+ is_utf8 perlio_ok resolve_alias utf8_downgrade utf8_upgrade
+ ),
+ @FB_FLAGS, @FB_CONSTS,
+ );
+
+our %EXPORT_TAGS =
+ (
+ all => [ @EXPORT, @EXPORT_OK ],
+ fallbacks => [ @FB_CONSTS ],
+ fallback_all => [ @FB_CONSTS, @FB_FLAGS ],
+ );
+
bootstrap Encode ();
use Carp;
-# Make a %encoding package variable to allow a certain amount of cheating
-our %encoding;
-my @alias; # ordered matching list
-my %alias; # cached known aliases
-
- # 0 1 2 3 4 5 6 7 8 9 10
-our @latin2iso_num = ( 0, 1, 2, 3, 4, 9, 10, 13, 14, 15, 16 );
-
-our %winlatin2cp = (
- 'Latin1' => 1252,
- 'Latin2' => 1250,
- 'Cyrillic' => 1251,
- 'Greek' => 1253,
- 'Turkish' => 1254,
- 'Hebrew' => 1255,
- 'Arabic' => 1256,
- 'Baltic' => 1257,
- 'Vietnamese' => 1258,
- );
-
-our %external_tables =
- (
- 'euc-cn' => 'Encode/CN.pm',
- gb2312 => 'Encode/CN.pm',
- gb12345 => 'Encode/CN.pm',
- gbk => 'Encode/CN.pm',
- cp936 => 'Encode/CN.pm',
- 'iso-ir-165' => 'Encode/CN.pm',
- 'euc-jp' => 'Encode/JP.pm',
- 'iso-2022-jp' => 'Encode/JP.pm',
- '7bit-jis' => 'Encode/JP.pm',
- shiftjis => 'Encode/JP.pm',
- macjapan => 'Encode/JP.pm',
- cp932 => 'Encode/JP.pm',
- 'euc-kr' => 'Encode/KR.pm',
- ksc5601 => 'Encode/KR.pm',
- cp949 => 'Encode/KR.pm',
- big5 => 'Encode/TW.pm',
- 'big5-hkscs' => 'Encode/TW.pm',
- cp950 => 'Encode/TW.pm',
- gb18030 => 'Encode/HanExtra.pm',
- big5plus => 'Encode/HanExtra.pm',
- 'euc-tw' => 'Encode/HanExtra.pm',
- );
+our $ON_EBCDIC = (ord("A") == 193);
-sub encodings
-{
- my ($class) = @_;
- return
- map { $_->[0] }
- sort { $a->[1] cmp $b->[1] }
- map { [$_, lc $_] }
- grep { $_ ne 'Internal' }
- keys %encoding;
-}
+use Encode::Alias;
-sub findAlias
+# Make a %Encoding package variable to allow a certain amount of cheating
+our %Encoding;
+our %ExtModule;
+require Encode::Config;
+eval { require Encode::ConfigLocal };
+
+sub encodings
{
my $class = shift;
- local $_ = shift;
- # print "# findAlias $_\n";
- unless (exists $alias{$_})
- {
- for (my $i=0; $i < @alias; $i += 2)
- {
- my $alias = $alias[$i];
- my $val = $alias[$i+1];
- my $new;
- if (ref($alias) eq 'Regexp' && $_ =~ $alias)
- {
- $new = eval $val;
- }
- elsif (ref($alias) eq 'CODE')
- {
- $new = &{$alias}($val)
- }
- elsif (lc($_) eq lc($alias))
- {
- $new = $val;
- }
- if (defined($new))
- {
- next if $new eq $_; # avoid (direct) recursion on bugs
- my $enc = (ref($new)) ? $new : find_encoding($new);
- if ($enc)
- {
- $alias{$_} = $enc;
- last;
- }
- }
- }
+ my @modules = (@_ and $_[0] eq ":all") ? values %ExtModule : @_;
+ for my $mod (@modules){
+ $mod =~ s,::,/,g or $mod = "Encode/$mod";
+ $mod .= '.pm';
+ $DEBUG and warn "about to require $mod;";
+ eval { require $mod; };
}
- return $alias{$_};
+ my %modules = map {$_ => 1} @modules;
+ return
+ sort { lc $a cmp lc $b }
+ grep {!/^(?:Internal|Unicode)$/o} keys %Encoding;
}
-sub define_alias
-{
- while (@_)
- {
- my ($alias,$name) = splice(@_,0,2);
- push(@alias, $alias => $name);
- }
+sub perlio_ok{
+ exists $INC{"PerlIO/encoding.pm"} or return 0;
+ my $stash = ref($_[0]);
+ $stash ||= ref(find_encoding($_[0]));
+ return ($stash eq "Encode::XS" || $stash eq "Encode::Unicode");
}
-# Allow variants of iso-8859-1 etc.
-define_alias( qr/^iso[-_]?(\d+)[-_](\d+)$/i => '"iso-$1-$2"' );
-
-# At least HP-UX has these.
-define_alias( qr/^iso8859(\d+)$/i => '"iso-8859-$1"' );
-
-# More HP stuff.
-define_alias( qr/^(?:hp-)?(arabic|greek|hebrew|kana|roman|thai|turkish)8$/i => '"${1}8"' );
-
-# The Official name of ASCII.
-define_alias( qr/^ANSI[-_]?X3\.4[-_]?1968$/i => '"ascii"' );
-
-# This is a font issue, not an encoding issue.
-# (The currency symbol of the Latin 1 upper half
-# has been redefined as the euro symbol.)
-define_alias( qr/^(.+)\@euro$/i => '"$1"' );
-
-# Allow latin-1 style names as well
-define_alias( qr/^(?:iso[-_]?)?latin[-_]?(\d+)$/i => '"iso-8859-$latin2iso_num[$1]"' );
-
-# Allow winlatin1 style names as well
-define_alias( qr/^win(latin[12]|cyrillic|baltic|greek|turkish|hebrew|arabic|baltic|vietnamese)$/i => '"cp$winlatin2cp{\u$1}"' );
-
-# Common names for non-latin prefered MIME names
-define_alias( 'ascii' => 'US-ascii',
- 'cyrillic' => 'iso-8859-5',
- 'arabic' => 'iso-8859-6',
- 'greek' => 'iso-8859-7',
- 'hebrew' => 'iso-8859-8',
- 'thai' => 'iso-8859-11',
- 'tis620' => 'iso-8859-11',
- );
-
-# At least AIX has IBM-NNN (surprisingly...) instead of cpNNN.
-# And Microsoft has their own naming (again, surprisingly).
-define_alias( qr/^(?:ibm|ms)[-_]?(\d\d\d\d?)$/i => '"cp$1"');
-
-# Sometimes seen with a leading zero.
-define_alias( qr/^cp037$/i => '"cp37"');
-
-# Ououououou.
-define_alias( qr/^macRomanian$/i => '"macRumanian"');
-
-# Standardize on the dashed versions.
-define_alias( qr/^utf8$/i => 'utf-8' );
-define_alias( qr/^koi8r$/i => 'koi8-r' );
-define_alias( qr/^koi8u$/i => 'koi8-u' );
-
-# Seen in some Linuxes.
-define_alias( qr/^ujis$/i => 'euc-jp' );
-
-# CP936 doesn't have vendor-addon for GBK, so they're identical.
-define_alias( qr/^gbk$/i => '"cp936"');
-
-# TODO: HP-UX '8' encodings arabic8 greek8 hebrew8 kana8 thai8 turkish8
-# TODO: HP-UX '15' encodings japanese15 korean15 roi15
-# TODO: Cyrillic encoding ISO-IR-111 (useful?)
-# TODO: Armenian encoding ARMSCII-8
-# TODO: Hebrew encoding ISO-8859-8-1
-# TODO: Thai encoding TCVN
-# TODO: Korean encoding Johab
-# TODO: Vietnamese encodings VPS
-# TODO: Mac Asian+African encodings: Arabic Armenian Bengali Burmese
-# ChineseSimp ChineseTrad Devanagari Ethiopic ExtArabic
-# Farsi Georgian Gujarati Gurmukhi Hebrew Japanese
-# Kannada Khmer Korean Laotian Malayalam Mongolian
-# Oriya Sinhalese Symbol Tamil Telugu Tibetan Vietnamese
-
-# Map white space and _ to '-'
-define_alias( qr/^(\S+)[\s_]+(.*)$/i => '"$1-$2"' );
-
sub define_encoding
{
my $obj = shift;
my $name = shift;
- $encoding{$name} = $obj;
+ $Encoding{$name} = $obj;
my $lc = lc($name);
define_alias($lc => $obj) unless $lc eq $name;
while (@_)
return $name;
}
my $lc = lc $name;
- if (exists $encoding{$name})
+ if (exists $Encoding{$name})
{
- return $encoding{$name};
+ return $Encoding{$name};
}
- if (exists $encoding{$lc})
+ if (exists $Encoding{$lc})
{
- return $encoding{$lc};
+ return $Encoding{$lc};
}
- my $oc = $class->findAlias($name);
+ my $oc = $class->find_alias($name);
return $oc if defined $oc;
- $oc = $class->findAlias($lc) if $lc ne $name;
+ $oc = $class->find_alias($lc) if $lc ne $name;
return $oc if defined $oc;
- if (!$skip_external and exists $external_tables{$lc})
+ unless ($skip_external)
{
- require $external_tables{$lc};
- return $encoding{$name} if exists $encoding{$name};
+ if (my $mod = $ExtModule{$name} || $ExtModule{$lc}){
+ $mod =~ s,::,/,g ; $mod .= '.pm';
+ eval{ require $mod; };
+ return $Encoding{$name} if exists $Encoding{$name};
+ }
}
-
return;
}
return __PACKAGE__->getEncoding($name,$skip_external);
}
-sub encode
+sub resolve_alias {
+ my $obj = find_encoding(shift);
+ defined $obj and return $obj->name;
+ return;
+}
+
+sub encode($$;$)
{
my ($name,$string,$check) = @_;
+ $check ||=0;
my $enc = find_encoding($name);
croak("Unknown encoding '$name'") unless defined $enc;
my $octets = $enc->encode($string,$check);
return $octets;
}
-sub decode
+sub decode($$;$)
{
my ($name,$octets,$check) = @_;
+ $check ||=0;
my $enc = find_encoding($name);
croak("Unknown encoding '$name'") unless defined $enc;
my $string = $enc->decode($octets,$check);
return $string;
}
-sub from_to
+sub from_to($$$;$)
{
my ($string,$from,$to,$check) = @_;
+ $check ||=0;
my $f = find_encoding($from);
croak("Unknown encoding '$from'") unless defined $f;
my $t = find_encoding($to);
croak("Unknown encoding '$to'") unless defined $t;
my $uni = $f->decode($string,$check);
return undef if ($check && length($string));
- $string = $t->encode($uni,$check);
+ $string = $t->encode($uni,$check);
return undef if ($check && length($uni));
- return length($_[0] = $string);
+ return defined($_[0] = $string) ? length($string) : undef ;
}
-sub encode_utf8
+sub encode_utf8($)
{
my ($str) = @_;
- utf8::encode($str);
+ utf8::encode($str);
return $str;
}
-sub decode_utf8
+sub decode_utf8($)
{
my ($str) = @_;
return undef unless utf8::decode($str);
return $str;
}
+predefine_encodings();
+
+#
+# This is to restore %Encoding if really needed;
+#
+sub predefine_encodings{
+ if ($ON_EBCDIC) {
+ # was in Encode::UTF_EBCDIC
+ package Encode::UTF_EBCDIC;
+ *name = sub{ shift->{'Name'} };
+ *new_sequence = sub{ return $_[0] };
+ *decode = sub{
+ my ($obj,$str,$chk) = @_;
+ my $res = '';
+ for (my $i = 0; $i < length($str); $i++) {
+ $res .=
+ chr(utf8::unicode_to_native(ord(substr($str,$i,1))));
+ }
+ $_[1] = '' if $chk;
+ return $res;
+ };
+ *encode = sub{
+ my ($obj,$str,$chk) = @_;
+ my $res = '';
+ for (my $i = 0; $i < length($str); $i++) {
+ $res .=
+ chr(utf8::native_to_unicode(ord(substr($str,$i,1))));
+ }
+ $_[1] = '' if $chk;
+ return $res;
+ };
+ $Encode::Encoding{Unicode} =
+ bless {Name => "UTF_EBCDIC"} => "Encode::UTF_EBCDIC";
+ } else {
+ # was in Encode::UTF_EBCDIC
+ package Encode::Internal;
+ *name = sub{ shift->{'Name'} };
+ *new_sequence = sub{ return $_[0] };
+ *decode = sub{
+ my ($obj,$str,$chk) = @_;
+ utf8::upgrade($str);
+ $_[1] = '' if $chk;
+ return $str;
+ };
+ *encode = \&decode;
+ $Encode::Encoding{Unicode} =
+ bless {Name => "Internal"} => "Encode::Internal";
+ }
+
+ {
+ # was in Encode::utf8
+ package Encode::utf8;
+ *name = sub{ shift->{'Name'} };
+ *new_sequence = sub{ return $_[0] };
+ *decode = sub{
+ my ($obj,$octets,$chk) = @_;
+ my $str = Encode::decode_utf8($octets);
+ if (defined $str) {
+ $_[1] = '' if $chk;
+ return $str;
+ }
+ return undef;
+ };
+ *encode = sub {
+ my ($obj,$string,$chk) = @_;
+ my $octets = Encode::encode_utf8($string);
+ $_[1] = '' if $chk;
+ return $octets;
+ };
+ $Encode::Encoding{utf8} =
+ bless {Name => "utf8"} => "Encode::utf8";
+ }
+}
+
require Encode::Encoding;
-require Encode::XS;
-require Encode::Internal;
-require Encode::Unicode;
-require Encode::utf8;
-require Encode::iso10646_1;
-require Encode::ucs2_le;
+
+eval {
+ require PerlIO::encoding;
+ unless (PerlIO::encoding->VERSION >= 0.02){
+ delete $INC{"PerlIO/encoding.pm"};
+ }
+};
+# warn $@ if $@;
1;
use Encode;
-=head1 DESCRIPTION
-The C<Encode> module provides the interfaces between Perl's strings
-and the rest of the system. Perl strings are sequences of B<characters>.
+=head2 Table of Contents
-To find more about character encodings, please consult
-L<Encode::Description> . This document focuses on programming references.
+Encode consists of a collection of modules which details are too big
+to fit in one document. This POD itself explains the top-level APIs
+and general topics at a glance. For other topics and more details,
+see the PODs below;
-=head1 PERL ENCODING API
+ Name Description
+ --------------------------------------------------------
+ Encode::Alias Alias defintions to encodings
+ Encode::Encoding Encode Implementation Base Class
+ Encode::Supported List of Supported Encodings
+ Encode::CN Simplified Chinese Encodings
+ Encode::JP Japanese Encodings
+ Encode::KR Korean Encodings
+ Encode::TW Traditional Chinese Encodings
+ --------------------------------------------------------
-=head2 Generic Encoding Interface
+=head1 DESCRIPTION
+
+The C<Encode> module provides the interfaces between Perl's strings
+and the rest of the system. Perl strings are sequences of
+B<characters>.
+
+The repertoire of characters that Perl can represent is at least that
+defined by the Unicode Consortium. On most platforms the ordinal
+values of the characters (as returned by C<ord(ch)>) is the "Unicode
+codepoint" for the character (the exceptions are those platforms where
+the legacy encoding is some variant of EBCDIC rather than a super-set
+of ASCII - see L<perlebcdic>).
+
+Traditionally computer data has been moved around in 8-bit chunks
+often called "bytes". These chunks are also known as "octets" in
+networking standards. Perl is widely used to manipulate data of many
+types - not only strings of characters representing human or computer
+languages but also "binary" data being the machines representation of
+numbers, pixels in an image - or just about anything.
+
+When Perl is processing "binary data" the programmer wants Perl to
+process "sequences of bytes". This is not a problem for Perl - as a
+byte has 256 possible values it easily fits in Perl's much larger
+"logical character".
+
+=head2 TERMINOLOGY
=over 4
=item *
- $bytes = encode(ENCODING, $string[, CHECK])
-
-Encodes string from Perl's internal form into I<ENCODING> and returns
-a sequence of octets. For CHECK see L</"Handling Malformed Data">.
-
-For example to convert (internally UTF-8 encoded) Unicode data
-to octets:
-
- $octets = encode("utf8", $unicode);
+I<character>: a character in the range 0..(2**32-1) (or more).
+(What Perl's strings are made of.)
=item *
- $string = decode(ENCODING, $bytes[, CHECK])
-
-Decode sequence of octets assumed to be in I<ENCODING> into Perl's
-internal form and returns the resulting string. For CHECK see
-L</"Handling Malformed Data">.
-
-For example to convert ISO-8859-1 data to UTF-8:
-
- $utf8 = decode("latin1", $latin1);
+I<byte>: a character in the range 0..255
+(A special case of a Perl character.)
=item *
- from_to($string, FROM_ENCODING, TO_ENCODING[, CHECK])
-
-Convert B<in-place> the data between two encodings. How did the data
-in $string originally get to be in FROM_ENCODING? Either using
-encode() or through PerlIO: See L</"Encoding and IO">. For CHECK
-see L</"Handling Malformed Data">.
-
-For example to convert ISO-8859-1 data to UTF-8:
-
- from_to($data, "iso-8859-1", "utf-8");
-
-and to convert it back:
-
- from_to($data, "utf-8", "iso-8859-1");
-
-Note that because the conversion happens in place, the data to be
-converted cannot be a string constant, it must be a scalar variable.
+I<octet>: 8 bits of data, with ordinal values 0..255
+(Term for bytes passed to or from a non-Perl context, e.g. disk file.)
=back
-=head2 Handling Malformed Data
+The marker [INTERNAL] marks Internal Implementation Details, in
+general meant only for those who think they know what they are doing,
+and such details may change in future releases.
-If CHECK is not set, C<undef> is returned. If the data is supposed to
-be UTF-8, an optional lexical warning (category utf8) is given. If
-CHECK is true but not a code reference, dies.
+=head1 PERL ENCODING API
-It would desirable to have a way to indicate that transform should use
-the encodings "replacement character" - no such mechanism is defined yet.
+=over 4
-It is also planned to allow I<CHECK> to be a code reference.
+=item $octets = encode(ENCODING, $string[, CHECK])
-This is not yet implemented as there are design issues with what its
-arguments should be and how it returns its results.
+Encodes string from Perl's internal form into I<ENCODING> and returns
+a sequence of octets. ENCODING can be either a canonical name or
+alias. For encoding names and aliases, see L</"Defining Aliases">.
+For CHECK see L</"Handling Malformed Data">.
-=over 4
+For example to convert (internally UTF-8 encoded) Unicode string to
+iso-8859-1 (also known as Latin1),
-=item Scheme 1
+ $octets = encode("iso-8859-1", $unicode);
-Passed remaining fragment of string being processed.
-Modifies it in place to remove bytes/characters it can understand
-and returns a string used to represent them.
-e.g.
+=item $string = decode(ENCODING, $octets[, CHECK])
- sub fixup {
- my $ch = substr($_[0],0,1,'');
- return sprintf("\x{%02X}",ord($ch);
- }
+Decode sequence of octets assumed to be in I<ENCODING> into Perl's
+internal form and returns the resulting string. as in encode(),
+ENCODING can be either a canonical name or alias. For encoding names
+and aliases, see L</"Defining Aliases">. For CHECK see
+L</"Handling Malformed Data">.
-This scheme is close to how underlying C code for Encode works, but gives
-the fixup routine very little context.
+For example to convert ISO-8859-1 data to UTF-8:
-=item Scheme 2
+ $utf8 = decode("iso-8859-1", $latin1);
-Passed original string, and an index into it of the problem area, and
-output string so far. Appends what it will to output string and
-returns new index into original string. For example:
+=item [$length =] from_to($string, FROM_ENCODING, TO_ENCODING [,CHECK])
- sub fixup {
- # my ($s,$i,$d) = @_;
- my $ch = substr($_[0],$_[1],1);
- $_[2] .= sprintf("\x{%02X}",ord($ch);
- return $_[1]+1;
- }
+Convert B<in-place> the data between two encodings.
+For example to convert ISO-8859-1 data to UTF-8:
-This scheme gives maximal control to the fixup routine but is more
-complicated to code, and may need internals of Encode to be tweaked to
-keep original string intact.
+ from_to($data, "iso-8859-1", "utf-8");
-=item Other Schemes
+and to convert it back:
-Hybrids of above.
+ from_to($data, "utf-8", "iso-8859-1");
-Multiple return values rather than in-place modifications.
+Note that because the conversion happens in place, the data to be
+converted cannot be a string constant, it must be a scalar variable.
-Index into the string could be pos($str) allowing s/\G...//.
+from_to() return the length of the converted string on success, undef
+otherwise.
=back
=head2 UTF-8 / utf8
The Unicode consortium defines the UTF-8 standard as a way of encoding
-the entire Unicode repertiore as sequences of octets. This encoding is
-expected to become very widespread. Perl can use this form internaly
+the entire Unicode repertoire as sequences of octets. This encoding is
+expected to become very widespread. Perl can use this form internally
to represent strings, so conversions to and from this form are
particularly efficient (as octets in memory do not have to change,
just the meta-data that tells Perl how to treat them).
=over 4
-=item *
-
- $bytes = encode_utf8($string);
+=item $octets = encode_utf8($string);
The characters that comprise string are encoded in Perl's superset of UTF-8
and the resulting octets returned as a sequence of bytes. All possible
characters have a UTF-8 representation so this function cannot fail.
-=item *
+=item $string = decode_utf8($octets [, CHECK]);
- $string = decode_utf8($bytes [,CHECK]);
-
-The sequence of octets represented by $bytes is decoded from UTF-8
+The sequence of octets represented by $octets is decoded from UTF-8
into a sequence of logical characters. Not all sequences of octets
form valid UTF-8 encodings, so it is possible for this call to fail.
For CHECK see L</"Handling Malformed Data">.
=head2 Listing available encodings
- use Encode qw(encodings);
- @list = encodings();
+ use Encode;
+ @list = Encode->encodings();
+
+Returns a list of the canonical names of the available encodings that
+are loaded. To get a list of all available encodings including the
+ones that are not loaded yet, say
+
+ @all_encodings = Encode->encodings(":all");
-Returns a list of the canonical names of the available encodings.
+Or you can give the name of specific module.
+
+ @with_jp = Encode->encodings("Encode::JP");
+
+When "::" is not in the name, "Encode::" is assumed.
+
+ @ebcdic = Encode->encodings("EBCDIC");
+
+To find which encodings are supported by this package in details,
+see L<Encode::Supported>.
=head2 Defining Aliases
- use Encode qw(define_alias);
- define_alias( newName => ENCODING);
+To add new alias to a given encoding, Use;
-Allows newName to be used as am alias for ENCODING. ENCODING may be
-either the name of an encoding or and encoding object (as above).
+ use Encode;
+ use Encode::Alias;
+ define_alias(newName => ENCODING);
-Currently I<newName> can be specified in the following ways:
+After that, newName can be used as an alias for ENCODING.
+ENCODING may be either the name of an encoding or an
+I<encoding object>
-=over 4
+But before you do so, make sure the alias is nonexistent with
+C<resolve_alias()>, which returns the canonical name thereof.
+i.e.
-=item As a simple string.
+ Encode::resolve_alias("latin1") eq "iso-8859-1" # true
+ Encode::resolve_alias("iso-8859-12") # false; nonexistent
+ Encode::resolve_alias($name) eq $name # true if $name is canonical
-=item As a qr// compiled regular expression, e.g.:
+This resolve_alias() does not need C<use Encode::Alias> and is
+exported via C<use encode qw(resolve_alias)>.
- define_alias( qr/^iso8859-(\d+)$/i => '"iso-8859-$1"' );
+See L<Encode::Alias> on details.
-In this case if I<ENCODING> is not a reference it is C<eval>-ed to
-allow C<$1> etc. to be subsituted. The example is one way to names as
-used in X11 font names to alias the MIME names for the iso-8859-*
-family. Note the double quote inside the single quote. If you are
-using regex here, you have to do so or it won't work in this case.
+=head1 Encoding via PerlIO
-=item As a code reference, e.g.:
+If your perl supports I<PerlIO>, you can use PerlIO layer to directly
+decode and encode via filehandle. The following two examples are
+totally identical by functionality.
- define_alias( sub { return /^iso8859-(\d+)$/i ? "iso-8859-$1" : undef } , '');
+ # via PerlIO
+ open my $in, "<:encoding(shiftjis)", $infile or die;
+ open my $out, ">:encoding(euc-jp)", $outfile or die;
+ while(<>){ print; }
-In this case C<$_> will be set to the name that is being looked up and
-I<ENCODING> is passed to the sub as its first argument. The example
-is another way to names as used in X11 font names to alias the MIME
-names for the iso-8859-* family.
+ # via from_to
+ open my $in, $infile or die;
+ open my $out, $outfile or die;
+ while(<>){
+ from_to($_, "shiftjis", "euc", 1);
+ }
-=back
+Unfortunately, not all encodings are PerlIO-savvy. You can check if
+your encoding is supported by PerlIO by C<perlio_ok> method.
-=head1 Defining Encodings
+ Encode::perlio_ok("iso-20220jp"); # false
+ find_encoding("iso-2022-jp")->perlio_ok; # false
+ use Encode qw(perlio_ok); # exported upon request
+ perlio_ok("euc-jp") # true if PerlIO is enabled
- use Encode qw(define_alias);
- define_encoding( $object, 'canonicalName' [,alias...]);
+For gory details, see L<Encode::PerlIO>;
-Causes I<canonicalName> to be associated with I<$object>. The object
-should provide the interface described in L<Encode::Encoding>
-below. If more than two arguments are provided then additional
-arguments are taken as aliases for I<$object> as for C<define_alias>.
+=head1 Handling Malformed Data
-=head1 Encoding and IO
+=over 4
-It is very common to want to do encoding transformations when
-reading or writing files, network connections, pipes etc.
-If Perl is configured to use the new 'perlio' IO system then
-C<Encode> provides a "layer" (See L<perliol>) which can transform
-data as it is read or written.
+THE I<CHECK> argument is used as follows. When you omit it, it is
+identical to I<CHECK> = 0.
-Here is how the blind poet would modernise the encoding:
+=item I<CHECK> = Encode::FB_DEFAULT ( == 0)
- use Encode;
- open(my $iliad,'<:encoding(iso-8859-7)','iliad.greek');
- open(my $utf8,'>:utf8','iliad.utf8');
- my @epic = <$iliad>;
- print $utf8 @epic;
- close($utf8);
- close($illiad);
+If I<CHECK> is 0, (en|de)code will put I<substitution character> in
+place of the malformed character. for UCM-based encodings,
+E<lt>subcharE<gt> will be used. For Unicode, \xFFFD is used. If the
+data is supposed to be UTF-8, an optional lexical warning (category
+utf8) is given.
-In addition the new IO system can also be configured to read/write
-UTF-8 encoded characters (as noted above this is efficient):
+=item I<CHECK> = Encode::DIE_ON_ERROR (== 1)
- open(my $fh,'>:utf8','anything');
- print $fh "Any \x{0021} string \N{SMILEY FACE}\n";
+If I<CHECK> is 1, methods will die immediately with an error
+message. so when I<CHECK> is set, you should trap the fatal error
+with eval{} unless you really want to let it die on error.
-Either of the above forms of "layer" specifications can be made the default
-for a lexical scope with the C<use open ...> pragma. See L<open>.
+=item I<CHECK> = Encode::FB_QUIET
-Once a handle is open is layers can be altered using C<binmode>.
+If I<CHECK> is set to Encode::FB_QUIET, (en|de)code will immediately
+return proccessed part on error, with data passed via argument
+overwritten with unproccessed part. This is handy when have to
+repeatedly call because the source data is chopped in the middle for
+some reasons, such as fixed-width buffer. Here is a sample code that
+just does this.
-Without any such configuration, or if Perl itself is built using
-system's own IO, then write operations assume that file handle accepts
-only I<bytes> and will C<die> if a character larger than 255 is
-written to the handle. When reading, each octet from the handle
-becomes a byte-in-a-character. Note that this default is the same
-behaviour as bytes-only languages (including Perl before v5.6) would
-have, and is sufficient to handle native 8-bit encodings
-e.g. iso-8859-1, EBCDIC etc. and any legacy mechanisms for handling
-other encodings and binary data.
+ my $data = '';
+ while(defined(read $fh, $buffer, 256)){
+ # buffer may end in partial character so we append
+ $data .= $buffer;
+ $utf8 .= decode($encoding, $data, ENCODE::FB_QUIET);
+ # $data now contains unprocessed partial character
+ }
-In other cases it is the programs responsibility to transform
-characters into bytes using the API above before doing writes, and to
-transform the bytes read from a handle into characters before doing
-"character operations" (e.g. C<lc>, C</\W+/>, ...).
+=item I<CHECK> = Encode::FB_WARN
-You can also use PerlIO to convert larger amounts of data you don't
-want to bring into memory. For example to convert between ISO-8859-1
-(Latin 1) and UTF-8 (or UTF-EBCDIC in EBCDIC machines):
+This is the same as above, except it warns on error. Handy when you
+are debugging the mode above.
- open(F, "<:encoding(iso-8859-1)", "data.txt") or die $!;
- open(G, ">:utf8", "data.utf") or die $!;
- while (<F>) { print G }
+=item perlqq mode (I<CHECK> = Encode::FB_PERLQQ)
- # Could also do "print G <F>" but that would pull
- # the whole file into memory just to write it out again.
+For encodings that are implemented by Encode::XS, CHECK ==
+Encode::FB_PERLQQ turns (en|de)code into C<perlqq> fallback mode.
-More examples:
+When you decode, '\xI<XX>' will be placed where I<XX> is the hex
+representation of the octet that could not be decoded to utf8. And
+when you encode, '\x{I<xxxx>}' will be placed where I<xxxx> is the
+Unicode ID of the character that cannot be found in the character
+repartoire of the encoding.
- open(my $f, "<:encoding(cp1252)")
- open(my $g, ">:encoding(iso-8859-2)")
- open(my $h, ">:encoding(latin9)") # iso-8859-15
+=item The bitmask
-See L<PerlIO> for more information.
+These modes are actually set via bitmask. here is how FB_XX are laid
+out. for FB_XX you can import via C<use Encode qw(:fallbacks)> for
+generic bitmask constants, you can import via
+ C<use Encode qw(:fallback_all)>.
-See also L<encoding> for how to change the default encoding of the
-data in your script.
+ FB_DEFAULT FB_CROAK FB_QUIET FB_WARN FB_PERLQQ
+ DIE_ON_ERR 0x0001 X
+ WARN_ON_ER 0x0002 X
+ RETURN_ON_ERR 0x0004 X X
+ LEAVE_SRC 0x0008
+ PERLQQ 0x0100 X
+
+=head2 Unemplemented fallback schemes
+
+In future you will be able to use a code reference to a callback
+function for the value of I<CHECK> but its API is still undecided.
+
+=head1 Defining Encodings
+
+To define a new encoding, use:
+
+ use Encode qw(define_alias);
+ define_encoding($object, 'canonicalName' [, alias...]);
+
+I<canonicalName> will be associated with I<$object>. The object
+should provide the interface described in L<Encode::Encoding>
+If more than two arguments are provided then additional
+arguments are taken as aliases for I<$object> as for C<define_alias>.
+
+See L<Encode::Encoding> for more details.
=head1 Messing with Perl's Internals
=over 4
-=item * is_utf8(STRING [, CHECK])
+=item is_utf8(STRING [, CHECK])
[INTERNAL] Test whether the UTF-8 flag is turned on in the STRING.
If CHECK is true, also checks the data in STRING for being well-formed
UTF-8. Returns true if successful, false otherwise.
-=item *
-
- _utf8_on(STRING)
+=item _utf8_on(STRING)
[INTERNAL] Turn on the UTF-8 flag in STRING. The data in STRING is
B<not> checked for being well-formed UTF-8. Do not use unless you
state of the UTF-8 flag (so please don't test the return value as
I<not> success or failure), or C<undef> if STRING is not a string.
-=item *
-
- _utf8_off(STRING)
+=item _utf8_off(STRING)
[INTERNAL] Turn off the UTF-8 flag in STRING. Do not use frivolously.
Returns the previous state of the UTF-8 flag (so please don't test the
=head1 SEE ALSO
-L<perlunicode>, L<perlebcdic>, L<perlfunc/open>, L<PerlIO>, L<encoding>,
-L<utf8>, L<Encode::Description>, L<Encode::Encoding> the Perl Unicode Mailing List E<lt>perl-unicode@perl.orgE<gt>
+L<Encode::Encoding>,
+L<Encode::Supported>,
+L<Encode::PerlIO>,
+L<encoding>,
+L<perlebcdic>,
+L<perlfunc/open>,
+L<perlunicode>,
+L<utf8>,
+the Perl Unicode Mailing List E<lt>perl-unicode@perl.orgE<gt>
+=head1 MAINTAINER
-=cut
+This project was originated by Nick Ing-Simmons and later maintained
+by Dan Kogai E<lt>dankogai@dan.co.jpE<gt>. See AUTHORS for full list
+of people involved. For any questions, use
+E<lt>perl-unicode@perl.orgE<gt> so others can share.
+=cut
projects / p5sagit/p5-mst-13.2.git / blobdiff