--- name: "Jcode::Nihongo" section: "3pm" platform: "linux" package: "libjcode-pm-perl" version: "2.06-1.1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Jcode::Nihongo" --- # Jcode::Nihongo(3pm) ## 名前 Jcode - 日本語文字集合ハンドラ ## 概要 ``` use Jcode; # # 古式ゆかしく Jcode::convert($str, $ocode, $icode, "z"); # もしくはオブジェクト指向で！ print Jcode->new($str)->h2z->tr($from, $to)->utf8; ``` ## 説明 Jcode.pmはオブジェクト的なアプローチと従来からのアプローチの両方を サポートしています。オブジェクト的なアプローチを使えばこんな感じで； ``` $iso_2022_jp = Jcode->new($str)->h2z->jis; ``` こちらよりエレガントでしょう： ``` $iso_2022_jp = $str; &jcode::convert(\$iso_2022_jp, 'jis', &jcode::getcode(\$str), "z"); ``` オブジェクトに馴染みの無い人のために、Jcode.pmはまだ`"getcode()"`と `"convert()"`をサポートしています。 Perlのバージョンが5.8.1以上なら、Jcodeは、Perl 5.8以降の標準的な文字集合 ハンドラモジュールであるEncodeのラッパーとして振る舞います。 ## メソッド 特に言及しない限り、ここで挙げるメソッドは全てJcodeオブジェクトを返します。 ### コンストラクタ - $j = Jcode-\>new($str \[, $icode\]) `$strからJcodeオブジェクト`$jを生成します。明示的に$icodeをセットしなければ、 入力コードは自動的に判定されます。利用可能な文字集合については、下の getcodeを参照してください。 Perl 5.8.1以降では、`$icode`にはEncodeが理解できる *どんなエンコーディング名*も使えます。 ``` $j = Jcode->new($european, 'iso-latin1'); ``` オブジェクトを文字列化すると、EUCに変換された文字列が返ります。ですから `"print $j->euc"`とする代わりに、`"print $j"`とできます。 - リファレンス渡し スカラー値の代わりに、以下のようにリファレンスを渡せます。 ``` Jcode->new(\$str); ``` これはほんの少し時間を節約します。その代償として、$strの値そのものが 変換されます（ある意味、$strはjcodeオブジェクトに"tieされる"のです）。 - $j-\>set($str \[, $icode\]) `$jの内部文字列に`$strをセットします。繰り返しJcodeオブジェクトを使うときに 便利です（オブジェクトを生成する時間とメモリの節約になります）。 ``` # mailboxをSJIS形式に変換 my $jconv = new Jcode; $/ = 00; while(<>){ print $jconv->set(\$_)->mime_decode->sjis; } ``` - $j-\>append($str \[, $icode\]); `$jの内部文字列に`$strを加えます。 - $j = jcode($str \[, $icode\]); Jcode-\>**new()** の短縮形。以下のようにできます； ``` $sjis = jcode($str)->sjis; ``` ### 文字列のエンコード 一般に、$j-\>*encoded*とすることで*encoded*に変換された文字列を得ます。 - $sjis = $j-\>sjis - $euc = $j-\>euc - $jis = $j-\>jis - $sjis = $j-\>sjis - $ucs2 = $j-\>ucs2 - $utf8 = $j-\>utf8 自明でしょう。 WYCIWYG = What you code is what you get :) - $iso\_2022\_jp = $j-\>iso\_2022\_jp `"$j->h2z->jis"`と同じです。 半角カナは強制的に全角に変換されます。 Perl 5.8.1以降では、Encodeがサポートするどんなエンコーディング名と エイリアスでも利用できます。例えば： ``` $european = $j->iso_latin1; # メソッド名用に'-'は'_'に置き換えます ``` **参考**：Encode::Encoderがこれと同じ小技を使っています。 - $j-\>fallback($fallback) Perl 5.8.1以降では、Jcodeは内部の文字列をUTF-8で保持します。 *-\>encoding*にマップできない文字は'?'に置き換えられますが、 これはEncodeでの標準動作です。 ``` my $unistr = "\x{262f}"; # 陰陽マーク my $j = jcode($unistr); # $j->euc の結果は '?' に ``` この振る舞いは、Encode同様、フォールバックを指定することで変更できます。 値はEncodeのものと一緒です。便宜のため、`"Jcode::FB_PERLQQ"`、 `"Jcode::FB_XMLCREF"`、`"Jcode::FB_HTMLCREF"`がEncodeのそれらへの エイリアスになっています。 ``` print $j->fallback(Jcode::FB_PERLQQ)->euc; # '\x{262f}' print $j->fallback(Jcode::FB_XMLCREF)->euc; # '☯' print $j->fallback(Jcode::FB_HTMLCREF)->euc; # '☯' ``` グローバル変数`$Jcode::FALLBACK`にデフォルトのフォールバックが保持 されていますので、この値を代入することでオーバーライドできます。 ``` $Jcode::FALLBACK = Jcode::FB_PERLQQ; # デフォルトのフォールバックスキーマを設定 ``` - \[@lines =\] $jcode-\>jfold(\[$width, $newline\_str, $kref\]) `$width`（デフォルト：72）毎にjcode文字列内の行を折り返します。 `$widthは`”半角”文字の数です。全角文字は2文字としてカウントします。 `$newline_str`（デフォルトは"\\n"）で指定された改行文字が加わります。 折り返された全行をリストで返します。 Perl 5.8.1以降は3番目の引数$krefにEUCの文字列の配列リファレンスを 渡すことで、簡易的な行頭禁則処理（ぶら下がり）を行えます。 - $length = $jcode-\>**jlength()**; バイト長ではなく、全角文字も一文字として数えた場合の文字数を返します。 ### MIME::Base64を使うメソッド 下記のメソッドを使うには、MIME::Base64が必要です。インストールは単純に ``` perl -MCPAN -e 'CPAN::Shell->install("MIME::Base64")' ``` とします。お使いのPerlが5.6以降であるなら、MIME::Base64は バンドルされているので、インストールの必要はありません。 - $mime\_header = $j-\>mime\_encode(\[$lf, $bpl\]) `$strをRFC1522にあるMIME`-Headerに変換します。$lfを指定すると、 行の折り返しに$lfが使われます（デフォルト：\\n）。 `$bplを指定すると`、折り返すバイト数に$bplが使われます（デフォルト：76； この数値は76以下でなければなりません）。 Perl 5.8.1以降では、以下のようにしてもMIME Headerエンコードができます： ``` $mime_header = $j->MIME_Header; ``` この場合`$mime_header`の戻り値はMIME-B-encoded UTF-8になります。 一方、`"$j->mime_encode()"`はMIME-B-encoded ISO-2022-JPを返します。 最近のほとんどのメーラーはどちらもサポートしています。 - $j-\>mime\_decode; Jcodeオブジェクトの内部文字列をMIME-Headerデコードします。Perl 5.8.1 以降なら、以下のようにして同じことができます： ``` Jcode->new($str, 'MIME-Header'); ``` こちらの場合、ISO-2022-JPだけではなくUTF-8などにも対応しており、 さらにMIME B EncodingのみならずMIME Q Encodingにも対応している ので、Perl 5.8.1以降であればこちらを使うべきでしょう。 ### 半角 ←→ 全角 - $j-\>h2z(\[$keep\_dakuten\]) X201カナ（半角）をX208カナ（全角）に変換します。 `$keep_dakutenに真値をセットすると`、濁点をそのままにします (これはつまり、「カ＋゛」は「ガ」に変換されずにそのまま になるということです) `$j`-\>nmatchを通じてマッチした数を取得できます。 - $j-\>z2h X208カナ（全角）をX201カナ（半角）に変換します。 `$j`-\>nmatchを通じてマッチした数を取得できます。 ### 正規表現エミュレータ `"->m()"`と`"->s()"`を使うには、Perl 5.8.1以降が 必要です。 - $j-\>tr($from, $to, $opt); Jcodeオブジェクトに`"tr/$from/$to/"`を適用します。$fromと$toは EUC-JPの文字列です。Perl 5.8.1以降では、flag付きのUTF-8文字列 も受け付けます。 `$opt`をセットすると、`"tr/$from/$to/$opt"`が適用されます。`$opt`は 'c'、'd'あるいはそれらの組み合わせでなければなりません。 `$j`-\>nmatchを通じてマッチした数を取得できます。 Perl 5.8.1以降では、trの形式に誤りのあった場合に-\>error\_trを通じて、 $@を取得できます。 以下のメソッドはPerl 5.8.1以降でのみ利用可能です。 - $j-\>s($patter, $replace, $opt); 個々に`"s/$pattern/$replace/$opt"`を適用します。`$opt`は正規表現オプションと 同じです。正規表現のオプションについてはperlreを参照ください。 `"$j->tr()"`、`"$j->s()"`はそのオブジェクト自身を返すので、 以下のように操作を連結できます。 ``` $j->tr("A-Z", "a-z")->s("foo", "bar"); ``` - \[@match = \] $j-\>m($pattern, $opt); `"m/$patter/$opt"`を適用します。このメソッドは”オブジェクトを返さない” ので、`"$j->s()"`のようにメソッドを連結できないことに注意してください。 正規表現の形式に誤りのあった場合、-\>error\_m、-\>error\_sを通じて $@を取得できます。 ### インスタンス変数 もしJcodeオブジェクトのインスタンス変数にアクセスしたいなら、直接それら にアクセスするのではなく、アクセスメソッドを利用しましょう（これぞOOP です）。 参考までに、Jcodeは（一般的な方法である）ハッシュリファレンスの代わりに、 配列リファレンスを使うことで、スピードを最適化しています（実際のところ、 アクセスメソッドを使う限りこのことを知る必要はありません； もう一度 いいますが、これはOOPなのです）。 Perl 5.8.1以降では、ハッシュリファレンスを使うように変更されました。 これにより、Jcodeの拡張はものすごく簡単になります。 - $j-\>r\_str EUC文字列へのリファレンス。 Perl 5.8.1以降ではUTF-8フラグの立ったUTF-8文字列へのリファレンスです。 - $j-\>icode 直近の操作における入力文字コード。 - $j-\>nmatch マッチした数（$j-\>tr等を使ったとき）。 ## サブルーチン - ($code, \[$nmatch\]) = getcode($str) `$strの文字コードを返します`。返るコードは以下の通りです。 ``` ascii Ascii （日本語コードを含まない） binary Binary （テキストファイルではない） euc EUC-JP sjis SHIFT_JIS jis JIS (ISO-2022-JP) ucs2 UCS2 (Raw Unicode) utf8 UTF8 ``` スカラーコンテキストの代わりに配列コンテキストを使うと、何文字分の コードが見つかったのかも返します。上の方で述べたように、$strは\\$str でも構いません。 **jcode.pl 利用者の方へ：** この関数はjcode::**getcode()**と100%上位互換が あります。――まあ、ほぼ100%； ``` * 戻り値が配列のとき、その順番は逆となります； jcode::getcode()は$nmatchを最初に返します。 * jcode::getcode()は、EUC文字とSJIS文字の数が等しいとき、'undef'を 返します。 Jcode::getcode()はEUCを返します。これはJcode.pmには 中間がないためです。 ``` - Jcode::convert($str, \[$ocode, $icode, $opt\]) `$strを`$ocodeで指定した文字コードに変換します。$icodeも指定すると、 入力文字列をgetcode()でチェックする代わりに、$icodeと仮定します。 上の方で述べたように、$strは\\$strでも構いません。 **jcode.pl 利用者の方へ：** この関数はjcode::**convert()**と100%上位互換が あります！ ## バグ Perlが5.8.1以降の場合、JcodeはEncodeのラッパーとして振る舞います。 つまり、JcodeはEncode内のバグの影響を受けます。 ## 謝辞 このパッケージは、動機、デザインそしてコードの多くの点で、 歌代 和正 \氏のPerl4ライブラリjcode.plに負っています。 大崎 博基 \氏は、開発の非常に初期の段階から 正規表現を磨きあげる手助けをしてくれました。 makamaka@donzoko.net の JEncode には、JcodeとEncodeをどう融合させれば いいか大変大きな啓示を受けました。また、本日本語マニュアルも寄贈して いただきました。 そしてJcode ML \の皆さん。この方達なしには、 ここまで完成しなかったことでしょう。 ## 参考 Encode \ ## 著作権 Copyright 1999-2005 Dan Kogai \ This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.