Encode

SYNOPSIS (概要)

   use Encode;

DESCRIPTION (説明)

EncodeモジュールはPerl上での文字列と「取り残された」システム間のインターフェースを提供します。 Perl文字列とは、一連の文字（character）です。

（訳者注： Perl5.8では、文字は全てUnicodeで扱われるようです。 Encodeモジュールは、PerlがUnicode化から取り残された、ShiftJISやEUCなどを基本コードとしているシステムで、ファイルを読み書きする際のフィルタとして働くようです。 ）

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 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 perlebcdic).

Perlが扱うことのできる文字レパートリーとして、最低でもUnicodeコンソーシアムによって定義されたものは網羅されています。 ほとんどのプラットフォーム上では、"ord(ch)"によって返される文字の順序である値は、その文字のUnicode codepointです。 (例外となるのは、ASCIIのスーパーセットではなくEBCDICの変形の一種である、遺産的な符号付けを採用したプラットフォームの場合です- 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 machine's representation of numbers, pixels in an image - or just about anything.

伝統的に、コンピューター上のデータは、「バイト」と呼ばれる8ビット単位の塊で動かされてきました。この塊は、ネットワーク標準では「オクテット」として知られています。Perlは多くのタイプのデータを操作するために広く使用されており、人間またはコンピュータ言語を表わす文字からなる文字列だけでなく、機械的な数(イメージ中のピクセル - あるいはその他の何に対しても)の表現である「バイナリ」データも処理します。

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".

Perlが「バイナリデータ」を処理している場合、プログラマはPerlが「バイト単位データの連続」を処理することを望みます。 これはperlのための問題ではありません。1つのバイトが256の可能な値を持っていることと同様に、それはPerlのはるかに大きな「論理的な文字」とみなされます。

PERL ENCODING API (PerlエンコーディングAPI)

• $octets = encode(ENCODING, $string [, CHECK])

文字列を Perl の内部形式から ENCODING に符号化し、オクテットの列を返します。 ENCODING は正規名でも別名でも構いません。 符号化名と別名については、 /"Defining Aliases" をご覧下さい。 CHECK については、 /"Handling Malformed Data" をご覧下さい。

例えば、文字列を Perl の内部形式から iso-8859-1 (Latin1 とも呼ばれる)に変換するには、こうします。

 $octets = encode("iso-8859-1", $string);

警告:あなたが$octets = encode("utf8", $string)を実行する場合、実行後の $octets は $string と等しくないかもしれません。それらは両方とも同じデータを含んでいますが、$octets のutf8フラグは"常に"オフです。あなたが常にエンコードする場合、完全に有効なutf8ストリングを含んでいる場合さえ、結果のutf8フラグは常にオフです。下記の/"The UTF-8 flag"をご覧下さい。

encode($valid_encoding, undef)は無害ですが、"サブルーチン・エントリーでの初期化されていない値の使用"のために警告が出ます。 encode($valid_encoding, '')は無害で、また警告は出ません。

• $string = decode(ENCODING, $octets [, CHECK])

ENCODING に初期化されているオクテットの列を解読し、Perlの内部形式にして、その文字列を返します。encode()と同じです。 ENCODING は正規名でも別名でも構いません。名前と別名のコード化に関しては、別名を定義するを参照してください。CHECKについては、/"Handling Malformed Data"をご覧下さい。

例えば、文字列を iso-8859-1 から Perl の内部形式に変換するには、こうします。

$string = decode("iso-8859-1", $octets);

警告:あなたが$string = decode("utf8", $octets)を実行する場合、実行後の $string は $octetsと等しくないかもしれません。それらは両方とも同じデータを含んでいますが、もし $octets が、ASCIIデータ(あるいはEBCDIC機械上のEBCDIC)から完全に成らなければ、 $string のためのutf8フラグはオンです。/"The UTF-8 flag"をご覧ください。

decode($valid_encoding, undef)は無害ですが、"サブルーチン・エントリーでの初期化されていない値の使用"のために警告が出ます。 decode($valid_encoding, '')は無害で、また警告は出ません。

• [$length =] from_to($octets, FROM_ENC, TO_ENC [, CHECK])

オクテットの列をその場で FROM_ENC で示された文字列エンコーディングから TO_ENC で示された文字列エンコーディングに変換します。 $octet のデータは Perl の内部形式ではなく、オクテットの列として符号化されている必要があります。

例えばISO-8859-1のデータをマイクロソフトのCP1250エンコーディングに変換するには以下のようにします:

 from_to($octets, "iso-8859-1", "cp1250");

また、元に戻すには以下のようにします。

 from_to($octets, "cp1250", "iso-8859-1");

引数に渡される $octets はあちこちで変更されるため、文字列定数でありえないことに注意して下さい。 それはスカラー変数である必要があります。

(訳者コメント:文字列定数としましたが、文字列リテラルのほうが適当なのかもしれません。間違っていましたらどなたか修正して下さい。)

変換に成功したとき、 from_to() は変換後のオクテットの列に含まれる文字列長を返します。失敗すると、undefを返します。

警告: 次の呼び出しは全く同じに見えますが、完全に等しくはありません。

 from_to($data, "iso-8859-1", "utf8"); #1
 $data = decode("iso-8859-1", $data);  #2

 $data = encode("utf8", decode("iso-8859-1", $data));

/"The UTF-8 flag"をご覧ください。

• $octets = encode_utf8($string);

$octets = encode("utf8", $string); と等価で、Perlの内部形式の $string に含まれる文字が符号化され、結果はオクテットの列として返されます。あらゆる文字はUTF-8表現を持っているため、この呼び出しが失敗することはありません。

• $string = decode_utf8($octets [, CHECK]);

$string = decode("utf8", $octets [, CHECK]) と等価です。 $octetsによって表わされるオクテットの列は論理的な文字列へUTF-8からデコードされます。オクテットのすべてのシーケンスは有効なUTF-8エンコーディングを形成するとは限りません。 したがって、この呼び出しは失敗する可能性があります。 CHECK については、/"Handling Malformed Data"をご覧下さい。

 use Encode;
 @list = Encode->encodings();

 @all_encodings = Encode->encodings(":all");

 @with_jp = Encode->encodings("Encode::JP");

 @ebcdic = Encode->encodings("EBCDIC");

 use Encode;
 use Encode::Alias;
 define_alias(newName => ENCODING);

 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(もし、$nameが正規名であるなら、真)

Encoding via PerlIO (PerlIOによる符号化)

If your perl supports PerlIO (which is the default), you can use a PerlIO layer to decode and encode directly via a filehandle. The following two examples are totally identical in their functionality.

もしあなたのperlがPerlIOをサポートしていれば(デフォルト)、あなたはPerlIOレイヤーを使ってファイルハンドル経由で直接デコードやエンコードすることができます。 以下の２つの例は、機能はまったく同じです。

 # via PerlIO
 open my $in,  "<:encoding(shiftjis)", $infile  or die;
 open my $out, ">:encoding(euc-jp)",   $outfile or die;
 while(<$in>){ print $out $_; }

 # via from_to
 open my $in,  "<", $infile  or die;
 open my $out, ">", $outfile or die;
 while(<$in>){
   from_to($_, "shiftjis", "euc-jp", 1);
   print $out $_;
 }

Unfortunately, it may be that encodings are PerlIO-savvy. You can check if your encoding is supported by PerlIO by calling the perlio_ok method.

不運にもそれは、利用できるエンコーディングがPerlIOに依存しているということかもしれません。 あなたはperlio_okメソッドを呼ぶことによって、エンコードがPerlIOによってサポートされるかどうか確かめることができます。

 Encode::perlio_ok("hz");             # False
 find_encoding("euc-cn")->perlio_ok;  # True where PerlIO is available

 use Encode qw(perlio_ok);            # exported upon request
 perlio_ok("euc-jp")

Fortunately, all encodings that come with Encode core are PerlIO-savvy except for hz and ISO-2022-kr. For gory details, see Encode::Encoding and Encode::PerlIO.

幸運にも、Encodeのコアに付属するすべてのエンコーディングは、hz と ISO-2022-kr を除き、PerlIOにとって既知のものです。 むごたらしい詳細については、Encode::EncodingとEncode::PerlIOを見てください。

Handling Malformed Data (奇形データの取り扱い)

The CHECK argument is used as follows. When you omit it, the behaviour is the same as if you had passed a value of 0 for CHECK.

CHECK 引数は、以下のように利用されます。 省略すると CHECK に値0を渡すのと同じように振る舞います。

（Encode 2.14 より） As of version 2.12 Encode supports coderef values for CHECK. See below.

version 2.12 では Encode は CHECK にコードリファレンスをサポートしています。下記を参照してください。

• CHECK = Encode::FB_DEFAULT ( == 0)

If CHECK is 0, (en|de)code will put a substitution character in place of a malformed character. For hiv symptoms UCM-based encodings, <subchar> will be used. For Unicode, the code point 0xFFFD is used. If the data is supposed to be UTF-8, an optional lexical warning (category utf8) is given.

CHECK が0の場合、(en|de)codeは、代替文字を奇形の文字の位置に入れるでしょう。 UCMに基づいた符号化 (UCM-based encodings) については、<subchar>が使用されるでしょう。 Unicodeについては、コード・ポイント0xFFFDが使用されます。 データがUTF-8であると思われる場合、オプションのレキシカル警告(optional lexical warning) (カテゴリーutf8)が与えられます。

• CHECK = Encode::FB_CROAK ( == 1)

If CHECK is 1, methods will die on error immediately with an error message. Therefore, when CHECK is set to 1, you should trap the fatal error with eval{} unless you really want to let it die on error.

CHECK が1の場合、メソッドはエラーの直後、エラー・メッセージを伴って die が実行されるでしょう。 したがって、CHECK に1をセットする場合、もしエラーでそれを本当に die させたくないのならば、eval{}を用いて致命的なエラーをトラップするべきです。

• CHECK = Encode::FB_QUIET

If CHECK is set to Encode::FB_QUIET, (en|de)code will immediately return the portion of the data that has been processed so far when an error occurs. The data argument will be overwritten with everything after that point (that is, the unprocessed part of data). This is handy when you have to call decode repeatedly in the case where your source data custom writing company may contain partial multi-byte character sequences, for example because you are reading with a fixed-width buffer. Here is some sample code that does exactly this:

もしCHECK がEncode::FB_QUIETにセットされれば、(en|de)codeは、エラーが起こったときまでに処理されたデータの一部分をただちに返すでしょう。 データ引数は、その地点より後(すなわち、処理されていない残りのデータ)ですべて上書きされるでしょう。 例えば、固定長バッファで読み込んでいるなどの理由で、ソースデータがマルチ・バイトの文字列の断片を含むかもしれないケースでdecodeを繰り返し呼ぶ必要があるときに便利です。 ここにちょうどこれをするサンプル・コードがあります:

 my $data = ''; my $utf8 = '';
 while(defined(read $fh, $buffer, 256)){
   # buffer may end in a partial character so we append
   # $buffer は文字の断片で終わっているかもしれないので付け足す
   $data .= $buffer;
   $utf8 .= decode($encoding, $data, ENCODE::FB_QUIET);
   # $data now contains the unprocessed partial character
   # これで $data には未処理の文字の断片が含まれる
 }

• CHECK = Encode::FB_WARN

This is the same as above, except that it warns on error. Handy lupus symptoms when you are debugging the mode above.

これは、それがエラーのときに警告する以外は上記と同じです。 あなたが上記のモードのデバッグをしている時に便利です。

• perlqq mode (CHECK = Encode::FB_PERLQQ)

• HTML charref mode (CHECK = Encode::FB_HTMLCREF)

• XML charref mode (CHECK = Encode::FB_XMLCREF)

For encodings that are implemented by Encode::XS, CHECK == Encode::FB_PERLQQ turns (en|de)code into perlqq fallback mode.

Encode::XSによって実装されている符号化のために、CHECK == Encode::FB_PERLQQは、(en|de)codeをperlqqフォールバックモードに変えます。

When you decode, \xHH will be inserted for a malformed character, where HH is the hex representation of the octet that could not be decoded to utf8. And when you encode, \x{HHHH} will be inserted, where HHHH is the Unicode ID of the character that cannot be found in the character certified resume writer repertoire of the encoding.

デコードするときには、奇形の文字には \xHH が挿入されます。 HH は utf8 に復号化できなかったオクテットの16進表現です。 そして、エンコードするときには、\x{HHHH} が挿入されます。 HHHH は符号化の文字レパートリーには見つからなかった文字のユニコードIDです。

HTML/XML character reference modes are about the same, in place of \x{HHHH}, HTML uses &#NNNN; where NNNN is a decimal digit and XML uses &#xHHHH; where HHHH is the hexadecimal digit.

HTML/XML文字参照モードはほとんど同じですが、\x{HHHH} となるところが、HTML文字参照モードでは10進数字の NNNN を使って &#NNNN; となり、XML文字参照モードでは16進数字の HHHH を使って &#xHHHH; となります。

（Encode 2.14 より） In Encode 2.10 or later, LEAVE_SRC is also implied.

Encode 2.10 およびそれ以降では、LEAVE_SRC も含まれています。

• The bitmask

These modes are actually set via a bitmask. Here is how the FB_XX constants are laid out. You can import the FB_XX constants via use Encode qw(:fallbacks); you can import the generic bitmask constants via use Encode qw(:fallback_all).

これらのモードは、実際にはビットマスク経由でセットされます。 FB_XX定数がどのように設計されているかをここに示します。 あなたは、use Encode qw(:fallbacks)経由でFB_XX定数をインポートすることができます; あなたは、use Encode qw(:fallback_all)経由で一般的なビットマスク定数をインポートすることができます。

                    FB_DEFAULT FB_CROAK FB_QUIET FB_WARN  FB_PERLQQ
DIE_ON_ERR    0x0001             X
WARN_ON_ERR   0x0002                               X
RETURN_ON_ERR 0x0004                      X        X
LEAVE_SRC     0x0008                                        X (*)
PERLQQ        0x0100                                        X
HTMLCREF      0x0200
XMLCREF       0x0400

(*) 訳注: Encode 2.10 以降

 $ascii = encode("ascii", $utf8, sub{ sprintf "<U+%04X>", shift });

Defining Encodings (エンコーディングの定義)

To define a new encoding, use:

新しいエンコーディングを定義するためには、次のものを使用してください:

   use Encode qw(define_encoding);
   define_encoding($object, 'canonicalName' [, alias...]);

canonicalName will be associated with $object. The object should provide the interface described in Encode::Encoding. If more than two arguments are provided then additional arguments are taken as aliases for $object.

canonicalName は $object に関連づけされます。 オブジェクトは、Encode::Encoding で記述されたインターフェースを提供しなければなりません。 もし２つより多くの引数が与えられると、追加の引数は、$object のためのエイリアスとして扱われます。

See Encode::Encoding for more details.

より詳細に関しては Encode::Encoding を参照してください

The UTF-8 flag (UTF-8 フラグ)

Before the introduction of utf8 support in perl, The eq operator just compared the strings represented by two scalars. Beginning with perl 5.8, eq compares two strings with simultaneous consideration of the utf8 flag. To explain why we made it so, I will quote page 402 of Programming Perl, 3rd ed.

utf8 サポートが perl に導入される以前は、eq演算子は、２つのスカラー変数によって表された文字列をただ比べていました。 perl 5.8以降、eqは、２つの文字列を比べると同時にutf8フラグを考慮します。 なぜ私たちがそれをそのように作ったかを説明するために、Programming Perl, 3rd ed. (邦訳 プログラミングPerl 第3版) の402ページを引用しましょう。

Goal #1

Old byte-oriented programs should not spontaneously break on the old byte-oriented data they used to work on.

古いバイト指向のプログラムが、以前は正常に扱うことができていた古いバイト指向のデータを扱えなくなるようなことがあってはなりません。

Goal #2

Old byte-oriented programs should magically start working on the new character-oriented data when appropriate.

古いバイト指向のプログラムは、適切である場合には、魔法のように新しい文字指向のデータを処理しはじめるべきです。

Goal #3

Programs should run just as fast in the new character-oriented mode as in the old byte-oriented mode.

プログラムは、新しい文字指向のモードでも古いバイト指向のモードと同じくらい速く走るべきです。

Goal #4

Perl should remain one language, rather than forking into a byte-oriented Perl and a character-oriented Perl.

バイト指向のPerlと文字指向のPerlに分岐するよりは、Perlは１つの言語の状態のままであるべきです。

Back when Programming Perl, 3rd ed. was written, not even Perl 5.6.0 was born and many features documented in the book remained unimplemented for a long time. Perl 5.8 corrected this and the introduction of the UTF-8 flag is one of them. You can think of this perl notion as of a byte-oriented mode (utf8 flag off) and a character-oriented mode (utf8 flag on).

Programming Perl, 3rd ed. が書かれた頃には、Perl 5.6.0 さえも生まれておらず、その本に記された多くの特徴は、長い間未実装状態のままでした。 Perl 5.8 はこれを正しましたが、UTF-8フラグの導入はその１つです。 あなたは、このperl概念をバイト指向のモード(utf8フラグがオフ)と文字指向のモード(utf8フラグがオン)で考えることができます。

Here is how Encode takes care of the utf8 flag.

以下は、Encode が utf8フラグを扱う方法です。

• When you encode, the resulting utf8 flag is always off.
• あなたがエンコードするとき、utf8フラグはいつもオフになります。

• When you decode, the resulting utf8 flag is on unless you can unambiguously represent data. Here is the definition of dis-ambiguity.
• あなたがデコードするとき、utf8フラグは、あなたが曖昧性無くデータを表現しない限り、オンになります。以下は曖昧性の無さの定義です。

After $utf8 = decode('foo', $octet);,

 When $octet is...   The utf8 flag in $utf8 is
 ---------------------------------------------
 In ASCII only (or EBCDIC only)            OFF
 In ISO-8859-1                              ON
 In any other Encoding                      ON
 ---------------------------------------------

As you see, there is one exception, In ASCII. That way you can assue Goal #1. And with Encode Goal #2 is assumed but you still have to be careful in such cases mentioned in CAVEAT paragraphs.

ご覧のとおり、ASCIIの場合には例外となります。 この方法により、Goal #1 を仮定することができます。そして、Encodeによって、Goal #2 が仮定されますが、あなたは、警告段落で述べられているようなケースに対してまだ注意する必要があります。

This utf8 flag is not visible in perl scripts, exactly for the same reason you cannot (or you don't have to) see if a scalar contains a string, integer, or floating point number. But you can still peek and poke these if you will. See the section below.

utf8フラグは、perl スクリプトでは、スカラー変数に文字列、整数もしくは浮動小数点数が入っているか見ることができない（もしくは見る必要がない）のとちょうど同じ理由により、見えません。しかし、あなたが望むなら、それをのぞき見たりつついたりすることもできます。以下の節を参照してください。

UTF-8 vs. utf8

(Encode 2.14 より)

 ....We now view strings not as sequences of bytes, but as sequences
 of numbers in the range 0 .. 2**32-1 (or in the case of 64-bit
 computers, 0 .. 2**64-1) -- Programming Perl, 3rd ed.

 ...これからは、文字列はバイトの列ではなく、0 .. 2**32-1 の範囲
 (64 ビットの計算機では 0 .. 2**64-1 の範囲) の数値の列としてあつかうことする
 -- Programming Perl、第3版

That has been the perl's notion of UTF-8 but official UTF-8 is more strict; Its ranges is much narrower (0 .. 10FFFF), some sequences are not allowed (i.e. Those used in the surrogate pair, 0xFFFE, et al).

これは Perl での UTF-8 の概念で、公式の UTF-8 はより制限が厳しいです。範囲はもっと狭く (0 .. 10FFFF)、認められない数値列があります (例。サロゲートペアで使うもの、0xFFFE、など)。

Now that is overruled by Larry Wall himself.

その後、Larry Wall 本人がそれをくつがえしてしまいました。

 From: Larry Wall <larry@wall.org>
 Date: December 04, 2004 11:51:58 JST
 To: perl-unicode@perl.org
 Subject: Re: Make Encode.pm support the real UTF-8
 Message-Id: <20041204025158.GA28754@wall.org>
 
 On Fri, Dec 03, 2004 at 10:12:12PM +0000, Tim Bunce wrote:
 : I've no problem with 'utf8' being perl's unrestricted uft8 encoding,
 : but "UTF-8" is the name of the standard and should give the
 : corresponding behaviour.
 
 For what it's worth, that's how I've always kept them straight in my
 head.
 
 Also for what it's worth, Perl 6 will mostly default to strict but
 make it easy to switch back to lax.
 
 Larry

Do you copy? As of Perl 5.8.7, UTF-8 means strict, official UTF-8 while utf8 means liberal, lax, version thereof. And Encode version 2.10 writing help or later thus groks the difference between UTF-8 and utf8.

メモの用意はいいかな? Perl 5.8.7 から、 UTF-8 は制限が厳しい公式の UTF-8 を意味し、 utf8 は寛大でおおらかなほうを意味することになります。 そこで、Encode も 2.10 版以降で、この UTF-8 と utf8 の違いをとりいれています。

 encode("utf8",  "\x{FFFF_FFFF}", 1); # okay
 encode("UTF-8", "\x{FFFF_FFFF}", 1); # croaks

UTF-8 in Encode is actually a canonical name for utf-8-strict. Yes, the hyphen between "UTF" and "8" is important. Without it Encode goes "liberal"

実際、Encode での UTF-8 は utf-8-strict の正規の名前です。 そうです。"UTF" と "8" の間のハイフンは重要なんです。 これがないと Encode は「寛大に」動作します。

 find_encoding("UTF-8")->name # is 'utf-8-strict'
 find_encoding("utf-8")->name # ditto. names are case insensitive
 find_encoding("utf_8")->name  # ditto. "_" are treated as "-"
 find_encoding("UTF8")->name  # is 'utf8'.

SEE ALSO (参照)

Encode::Encoding, Encode::Supported, Encode::PerlIO, encoding, perlebcdic, perlfunc/open, perlunicode, utf8, the Perl Unicode Mailing List <perl-unicode@perl.org>

MAINTAINER (著作権保持者)

This project was originated by Nick Ing-Simmons and later maintained by Dan Kogai <dankogai@dan.co.jp>. See AUTHORS for a full list of people involved. For any questions, use <perl-unicode@perl.org> so we can all share.

このページへのご意見、ご質問

（こちらへお書きください）