library getoptlong

要約

getoptlong は、GNU の getopt_long() とまったく同じ方式でコマンド行オプションの解析を行う Ruby のライブラリです。

GNU getopt_long() とは?

GNU getopt_long() は、コマンド行オプションの解析を行う C の関数です。多くの GNU ソフトウェアがこの関数を使用しています。GNU getopt_long() そして getoptlong には、以下のような特徴があります。

伝統的な一文字オプションに加えて、長いオプションに対応しています。長いオプションは `-' の代わりに `--' で始まります (例: `--version')。
長いオプションは、一意に定まる限り後方を省略することができます (例: `--version' は、`--ver' と略すことができます。ただし、他のオプション名が `--ver' で始まらない場合に限ります)。
特殊な引数 `--' によって、オプションの解析を強制的に終了します。

順序形式 (ordering)

GNU getopt_long() および getoptlong.rb には、`REQUIRE_ORDER', `PERMUTE', `RETURN_IN_ORDER' という、3 つの「順序形式」が用意されています。それぞれの処理形式は、非オプション引数についての扱い方が異なります。

REQUIRE_ORDER: 非オプション引数の後に来たオプションは、オプションとして認識しません。最初に非オプション引数が現れた時点で、オプションの解析処理を中止します。

PERMUTE: コマンド行引数の内容を、走査した順に入れ替え、最終的にはすべての非オプションを末尾に寄せます。この方式では、オプションはどの順序で書いても良いことになります。これは、たとえプログラム側でそうなることを期待しなくても、そうなります。この方式がデフォルトです。

RETURN_IN_ORDER: オプションと他の非オプション引数はどんな順序で並んでも良いが、お互いの順序は保持したままにしたいというプログラムのための形式です。

POSIXLY_CORRECT

環境変数 POSIXLY_CORRECT が定義されていると、処理形式に `PERMUTE' を選択していても、REQUIRE_ORDER 形式で処理されます。

使い方

あなたの作ったプログラムのヘルプメッセージが、次のようになっているものとします。

Usage: command [option...]
Options:
  -m SIZE  --max-size SIZE    Set maximum size
  -q  --quiet  --silence      Suppress all warnings
  --help                      Output this help, then exit
  --version                   Output version number, then exit

まず、`getoptlong.rb' を Ruby で書かれたあなたのプログラムに取り込みます。

require 'getoptlong.rb'

getoptlong はクラスを提供します。クラスの名前は GetoptLong です。 GetoptLong クラスのオブジェクトを生成します。

parser = GetoptLong.new

そして、set_options メソッドを呼び出し、この parser にオプションをセットします。

parser.set_options(
    ['--max-size',           '-m', GetoptLong::REQUIRED_ARGUMENT],
    ['--quiet', '--silence', '-q', GetoptLong::NO_ARGUMENT],
    ['--help',                     GetoptLong::NO_ARGUMENT],
    ['--version',                  GetoptLong::NO_ARGUMENT])

getopts モジュールが行っているように、与えられたオプションを `$OPT_...' という定数に入れたいときは、次のコードをあなたのプログラムに足して下さい。

begin
   parser.each_option do |name, arg|
      eval "$OPT_#{name.sub(/^--/, '').gsub(/-/, '_').upcase} = '#{arg}'"
   end
rescue
   exit(1)
end

each_option メソッドは、常にオプション名を「正式名 (canonical name)」の形で返してきます。「正式名」とは、`set_options' へ渡した個々の引数において、一番左にあるオプション名のことです。たとえば、`--quiet' は、 `-q' と `--silence' の正式名になります。したがって、この節の例で定義される可能性があるのは、`$OPT_MAX_SIZE', `$OPT_QUIET', `$OPT_HELP', `$OPT_VERSION' です。後方が省略されたオプションが与えられたときも、対応する正式名に変換されます。

順序形式の設定

先に記したように、順序形式のデフォルトは `PERMUTE' です。順序形式を変えるには `ordering=' メソッドを用います。

parser.ordering = GetoptLong::REQUIRE_ORDER

エラー

オプションの処理中は、次のような理由でエラーが発生します。

与えれたオプションは名前の後方が省略されていると思われるが、一意に決まらない
知らないオプションが与えられた
与えられたオプションには引数が欠けている
与えられたオプションには引数が伴っているが、そのオプションは引数をとらない

エラーが発生した場合、「静粛 (quiet)」フラグが設定されていなければ、標準エラー出力にエラーメッセージが出力され、例外が発生します。例外には、エラーメッセージも渡されます。

一旦エラーが起きてしまうと、続きのオプションを得ようとする試みはすべて失敗します。`GetoptLong' には、エラーを解除する方法はありません。言い換えると、エラーが起きたら、オプションの処理は諦めなければなりません。

静粛フラグ

エラーが発生すると、デフォルトではエラーメッセージが標準エラー出力に出力されます。「静粛 (quiet)」フラグを設定すると、エラーメッセージの出力は抑制されます。

parser.quiet = true

クラス

GetoptLong

GNU getopt_long() を Ruby で模したクラスです。

例外クラス

GetoptLong::Error	このライブラリで発生する例外の基底クラスです。
GetoptLong::AmbiguousOption	与えられたオプションは名前の後方が省略されていると思われるが、一意に決まらない場合に発生する例外です。
GetoptLong::InvalidOption	知らないオプションが与えられた場合に発生する例外です。
GetoptLong::MissingArgument	与えられたオプションに引数が欠けている場合に発生する例外です。
GetoptLong::NeedlessArgument	与えられたオプションは引数を伴っているが、そのオプションが引数をとらない場合に発生する例外です。