# idnconv2コマンドの使用方法

idnkitに付属する、idnconvコマンドの使用方法について解説します。

- idnconv2とは
- idnconv2の起動
- idnconv2の実行例
- idnconv2のオプション
- idnconv2の変換処理

## idnconv2とは

idnconv2コマンドは、国際化ドメイン名のエンコードとデコードを行うための ツールです。 idnkitバージョン2に収録されているidnconv2はIDNA2008規格にだけ対応 しています。 IDNA2003に対応したものを利用したいときは、idnkitバージョン1に収録 されているidnconvを使って下さい。

DNSサーバで国際化ドメイン名を扱うためには、サーバの設定ファイル (BIND 9の`named.conf`、NSDの`nsd.conf`) や ゾーンファイルのエンコーディングを変換する必要がありますが、 idnconv2を使うとこの変換を容易に行うことができます。 DNSサーバ関連のファイルの変換については、利用者ガイドの 「DNSサーバの設定」 に詳しく記してありますので、そちらをご覧下さい。

## idnconv2の起動

idnconv2を起動する際の、コマンド行の形式は次の通りです。

> `% idnconv2` [オプション...] [ファイル名]

idnconv2は引数で指定されたファイル、あるいは標準入力からテキストデータ を読み込み、テキストに含まれている国際化ドメイン名を変換し、変換結果を 標準出力に書き出します。

便宜上ここでは、ローカルエンコーディングからPunycodeへの変換を 「エンコード」、その逆の変換を「デコード」と呼ぶことにします。

## idnconv2の実行例

idnconv2の実行例をいくつか示します。 まず、もっとも簡単な実行例は次のようになります。

> `% idnconv2`

この場合、(ファイル名が指定されていないので) idnconv2は標準入力から データを読み込みます。 入力データはローカルエンコーディングで記述されていると見なされ、 エンコード処理は標準の設定 (設定ファイルがあればその設定、なければ idnkitの標準の設定) にしたがって行われます。

以下は、データを入力したときの様子です。一行入力すると、エンコード結果 が標準出力に出力されます。

>     % idnconv2
>     привет.мир
>     xn--b1agh1afp.xn--h1ahn

EOF (通常はコントロール + Dキー) を入力すると、idnconv2は終了します。

入力データのエンコーディングを指定する場合は、`-in` オプションを指定します。 たとえば、エンコーディングをKOI8-rにしたいときは、次のようにします。

> `% idnconv2 -in KOI8-r`

デコード (逆変換) を行う場合は、`-reverse`オプションを 使います。

>     % idnconv2 -reverse
>     xn--b1agh1afp.xn--h1ahn
>     привет.мир

デコード時にローカルエンコーディングを指定する場合は、`-out` オプションを使います。 KOI8-rにしたいときは、次のようにします。

> `% idnconv2 -reverse -out KOI8-r`

対話的に入力して変換するのではなく、ファイル全体を変換する場合は 次のように標準入力をファイルにリダイレクトするか、

> `% idnconv2 < filename`

あるいは、ファイル名をidnconv2の引数として与えるかします。

> `% idnconv2 filename`

## idnconv2のオプション

idnconv2が認識するオプションは、次の通りです。 よく使われると思われるオプションに関しては、短縮形として1文字のオプション を用意してあります。

オプション | 説明
--- | ---
`-in` エンコーディング | 入力テキストのエンコーディングを指定します。 以下のエンコーディング名称を認識します。 `iconv_open()`関数が認識するエンコード名 Punycode UTF-8 エンコーディング別名定義ファイル (`idnalias.conf`) で 定義された別名 エンコード (通常変換) モードでのデフォルトは、環境変数 `IDN_LOCAL_CODESET`がセットされている場合はその値となり、 セットされていなければロケール情報から取得したエンコーディング となります (「ローカルエンコーディング」 参照)。 デコード (逆変換) モードでは、デフォルトはPunycodeになります。
`-i` エンコーディング
`-out` エンコーディング | 出力テキストのエンコーディング名を指定します。 エンコード (通常変換) モードでは、デフォルトはPunycodeになります。 デコード (逆変換) モードでは、デフォルトは環境変数 `IDN_LOCAL_CODESET`がセットされている場合はその値となり、 セットされていなければロケール情報から取得したエンコーディングと なります (「ローカルエンコーディング」 参照)。
`-o` エンコーディング
`-conf` パス | idnkitの設定ファイルのパスを指定します (デフォルトで読み込まれる設定ファイルのパスは、 「設定ファイルについて」 を参照)。 `-noconf`ないし`-C`オプションと一緒に指定 した場合はそちらが優先され、設定ファイルは読み込まれません。
`-c` パス
`-noconf` | idnkitの設定ファイルを読み込まないようにします。
`-C`
`-reverse` | エンコード (通常変換) ではなく、デコード (逆変換) を行います。
`-r`
`-registration` (デフォルト) | IDNA2008の「ドメイン名登録プロトコル (registration protocol)」 を使用します。 デフォルトでは、こちらのプロトコルを使用します。
`-g` (デフォルト)
`-lookup` | IDNA2008の「ドメイン名参照プロトコル (lookup protocol)」 を使用します。 ドメイン名登録プロトコルでは行われる「ハイフンチェック」が省略され、 「その他文脈依存文字 (CONTEXTO)」のチェックも簡素化されます。 詳しくは、「idnconv2の変換処理」を参照して 下さい。
`-l`
`-nomap` | マッピング処理を行いません。 「`-skip map`」と等価です。
`-M`
`-skip` アクション名,... | アクション名で指定されたエンコード/デコード処理工程 の実行を省略します。 "`,`" で区切って複数のアクションを指定することが可能です。 また、複数回`-skip`オプションを指定しても構いません。 アクション名として以下の名称を認識します。 map マッピング asclower ASCIIの英大文字を小文字に変換 rtconv エンコード時に行う、PunycodeからUnicodeへの変換 prohcheck 禁止コードポイントチェック unascheck 未割り当てコードポイントチェック nfccheck NFC適用済みチェック prefcheck ACE接頭辞チェック hyphcheck ハイフンチェック combcheck 合成文字チェック ctxjcheck 「連結制御文脈依存文字 (CONTEXTJ)」チェック ctxocheck ドメイン名登録プロトコル (registration protocol) 用の 「その他制御文脈依存文字 (CONTEXTO)」チェック ctxolitecheck ドメイン名参照プロトコル (lookup protocol) 用の 「その他文脈依存文字 (CONTEXTO)」チェック bidicheck BIDI (bidirectional display; 双方向表示) チェック idnconv エンコード時は、UnicodeからPunycodeへの変換 。 デコード時はPunycodeからUnicodeの変換。 lencheck ラベル長チェック rtcheck ラウンドトリップチェック
`-whole` | 読み込んだ行全体を、1つのドメイン名とみなして処理します。 このオプションを指定しなければ、国際化ドメイン名だと判断された部分のみ が変換対象となります。
`-w`
`-localcheck` ファイル | 追加で、各コードポイントに対する「ローカルチェック」 を行います。 詳しくは、 「セットファイル」 を参照して下さい。
`-e` ファイル
`-flush` | 行ごとに出力をフラッシュします。idnconv2はファイルや パイプへの出力の場合、通常は複数行のデータをまとめて書き出しますが、この オプションを指定すると1行ごとに変換結果を書き出します。 通常はこのオプションを指定する必要はありませんが、 idnconv2をフィルタプログラムとして他のプログラムから利用する場合などに 便利なことがあります。
`-test` | 現在のオプション指定と環境変数等の設定状況で実行すると、 「現在の言語」とローカルエンコーディングが何になるのかを表示し、 終了します。
`-t`
`-version` | バージョン情報を表示して実行を終了します。
`-v`
`-help` | ヘルプメッセージを表示して終了します。
`-h`

## idnconv2の変換処理

### idnconv2のエンコード処理

idnconv2のエンコード (通常変換) モードでは、入力データに対して一行ずつ 次のような処理を行います。

1. 入力行の読み込み
   ファイルあるいは標準入力から1行分のテキストデータを読み込みます。
2. Unicodeへの変換
   読み込んだ行を入力エンコーディングで記述されているとみなして、 Unicodeに変換します。
3. 国際化ドメイン名が書かれた部分の検出
   入力行を調べ、国際化ドメイン名とみなせる部分をすべて取り出します。 具体的には次の条件をすべて満たす部分を、国際化ドメイン名とみなして 取り出します。
   - 1文字以上の非ASCII文字を含むこと
   - 従来のドメイン名に許される文字 (アルファベット、数字、ハイフン)、 非ASCII文字、ピリオドだけから構成されていること
   ただし、`-whole` (または `-w`) オプションが 指定された場合は入力行全体 (行末の改行文字は除く) を1つの国際化 ドメイン名とみなして取り出します。
4. 取り出した国際化ドメイン名の変換
   前項で取り出した国際化ドメイン名をIDNA2008のドメイン名登録プロトコル ないし参照プロトコルを用いてPunycodeに変換します。 具体的な変換手順は、 「エンコード処理の詳細」 に記しましたので、そちらをご覧下さい。 ただし、`-skip`オプションを指定していると、該当する処理 は行われません。 同様に、`-nomap`ないし`-M`を指定していると、 「マッピング」は行われません。
5. 結果を出力
   行の内容を、変換結果として標準出力に出力します。

### idnconv2のデコード処理

idnconv2のデコード (-reverseオプション指定時の動作、逆変換) は 入力データに対して一行ずつ次のような処理を行います。

1. 入力行の読み込み
   ファイルあるいは標準入力から1行分のデータを読み込みます。
2. Unicodeへの変換
   入力行をローカルエンコーディングで記述されているとみなして、Unicodeに 変換します。
3. 国際化ドメイン名が書かれた部分の検出
   入力行を調べ、国際化ドメイン名とみなせる部分をすべて取り出します。 具体的には次の条件をすべて満たす部分を、国際化ドメイン名とみなして 取り出します。
   - 従来のドメイン名に許される文字 (アルファベット、数字、ハイフン)、 ピリオドだけから構成されていること
   - ".-", "-.", ".." という文字列を含まないこと
   ただし、`-whole` (または `-w`) オプションが 指定された場合は入力行全体 (行末の改行文字は除く) を1つの国際化 ドメイン名とみなして取り出します。
4. 取り出した国際化ドメイン名の変換
   前項で取り出した国際化ドメイン名をIDNA2008のドメイン名登録プロトコル ないし参照プロトコルを用いてUnicodeに変換します。 ただし、`-whole` (または `-w`) オプションが 指定されていない場合、デコード処理に失敗してもエラーにはならず、 変換前の文字列のままとなります。 具体的な変換手順は、 「デコード処理の詳細」 に記しましたので、そちらをご覧下さい。 ただし、`-skip`オプションを指定していると、該当する処理 は行われません。 同様に、`-nomap`ないし`-M`を指定していると、 「マッピング」は行われません。
5. 結果を出力
   行の内容を、変換結果として標準出力に出力します。