library getoptlong

[edit]

要約

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

GNU getopt_long() とは?

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

順序形式 (ordering)

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

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'

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

与えられたオプションは引数を伴っているが、そのオプションが引数をとらない場合に発生する例外です。