[ruby-list:9557] getoptlong

SRA の笠原と申します。はじめまして。

Ruby プログラミングの練習として、getoptlong というものを作ってみました。
これは、コマンド行引数のオプションを解析するライブラリで、Ruby には既
に同様のものとして getotps, parsearg がありますが、getoptlong は glibc
の getopt_long() と同じ動作をするように作ってある、という特徴がありま
す。

(glibc の getopt.c をコンパイルして拡張モジュール化しても良かったので
すが、以前 Perl 4 で同じものを作ったことがあった手前、すべて Ruby で書
いてあります。^_^;)

ただ、Ruby の作法が十分理解しないまま見様見真似で書いたので、おかしな
点があるかも知れません。興味がありましたら、触ってみて頂けると嬉しいで
す。

    http://www.sra.co.jp/people/m-kasahr/tmp/getoptlong-1.0.tar.gz

README、ドキュメント、テストプログラム、それから getoptlong の使用例と
して、textuitl-1.22f と同等の動作をする Ruby 版 `wc' コマンドを添付し
てあります。

やや長いですが、getotplong のドキュメントを載せます。

----------------------------------------------------------------------

			    getoptlong.rb

			      笠原 基之
			 ([e-mail])


Copyright 1998  Motoyuki Kasahara

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by Free Software Foundation, Inc.


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

このプログラムはフリーソフトウェアです。あなたは、Free Software
Foundation が公表した GNU General Public License (GNU 一般公有使用許諾)
バージョン 2 あるいはそれ以降の各バージョンの中からいずれかを選択し、
そのバージョンが定める条項に従って本プログラムを再頒布または変更するこ
とができます。

このプログラムは有用とは思いますが、頒布にあたっては、市場性及び特定目
的適合性についての暗黙の保証を含めて、いかなる保証も行ないません。詳細
については GNU General Public License をお読みください。


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

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


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

* 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'

`getopts.rb' や `parsearg.rb' とは異なり、`getoptlong.rb' はモジュール
ではなくクラスを提供します。クラスの名前は `GetoptLong' です。
`GetoptLong' クラスのオブジェクトを生成します。

    parser = GetoptLong.new

そして、`set_optins' メソッドを呼び出し、この `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' です。後方が省略されたオプションが与えられたときも、対
応する正式名に変換されます。


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

    parser.ordering = GetoptLong::REQUIRE_ORDER


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

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

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

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


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

    parser.quiet = TRUE


GetoptLong クラスの詳細
=======================

スーパークラス
--------------
Object

クラスメソッド
--------------
new([*options])
	`GetoptLong' のオブジェクトを生成します。`option' が与えられる
	たときは、それを `set_options' メソッドに渡します。

メソッド
--------
each {|optname, optarg|...}
each_option {|optname, optarg|...}
	`get' メソッドのイテレータ版です。オプションとその引数の取得を
	繰り返し行います。詳しくは `get' の説明を参照して下さい。

get
get_option
	ARGV から、次のオプションの名前と、もしあればその引数の組を取
	得します。メソッドは 2 つの値を返し、1 つ目の値がオプション名
	(例: `--max-size') で、2 つ目がオプションの引数 (例: `20K') で
	す。`get' の通常の呼び出し方は次の通りです。

	    optname, optarg = option_parser.get

	`get' と `get_option' は常にオプション名を正式名 (canonical
	name) で返します。与えられたオプションが引数を取らないときは、
	空の文字列 ('') が `optarg' にセットされます。オプションが
	ARGV に残っていないときは、`optname', `optarg' ともに `nil'
	にセットされます。メソッドから戻る際に、取得したオプションと引
	数は自動的に ARGV から取り除かれます。

	与えられたコマンド行引数があなたのプログラムのオプションの設定
	に合わない場合は、エラーとなって、以下のいずれかの例外が発生し
	ます。

	GetoptLong::AmbigousOption
	    与えられたオプションは名前の後方が省略されていると思われる
	    が、一意に決まらない。
	
	GetoptLong::InvalidOption
	    知らないオプションが与えられた。

	GetoptLong::MissingArgument
	    与えられたオプションには引数が欠けている。

	GetoptLong::NeedlessArgument
	    与えられたオプションは引数を伴っているが、そのオプションは
	    引数をとらない。

	加えて、静粛 (quiet) モードが立っている場合は、エラーメッセー
	ジを標準エラー出力に出力します。

error
error?
	現在のエラーのエラーの型を返します。エラーが発生していなければ、
	`nil' を返します。

error_message
	現在のエラーのエラーメッセージを返します。エラーが発生していな
	ければ、`nil' を返します。

ordering=(ordering)
	順序形式 (ordering) を設定します。引数 `ordering' は、
	`PERMUTE', `REQUIRE_ORDER', `RETURN_IN_ORDER' のいずれかでなく
	てはなりません。それ以外の値を代入しようとすると、例外
	`ArgumentError' が発生します。

	順序形式を設定できるのは、`get', `get_option', `each',
	`each_option' メソッドを呼び出す前だけです。これらのメソッドを
	呼び出した後で順序形式を設定しようとすると、`RuntimeError' 例
	外が発生します。

	環境変数 `POSIXLY_CORRECT' が定義されていると、引数に 
	`PERMUTE' を与えてこのメソッドを呼び出しても、実際のところの順
	序形式は `REQUIRE_ORDER' に設定されます。

	環境変数 `POSIXLY_CORRECT' が定義されていない限り、`PERMUTE' 
	がデフォルトです。定義されていれば、`REQUIRE_ORDER' がデフォル
	トになります。

ordering
	現在の順序形式を返します。

quiet=(flag)
	`flag' が `TRUE' なら、静粛 (quiet) モードが有効になります。
	静粛モードが有効になっていると、レシーバのオブジェクトは、
	`get', `get_option', `each', `each_option' メソッドでエラーが
	発生しても、エラーメッセージを出力しません。

quiet
quiet?
	静粛モードが有効であれば、`TRUE' が返ります。そうでなければ、
	`FALSE' が返ります。

set_options(*options)
	あなたのプログラムで、認識させたいオプションをセットします。
	`options' の中の個々の引数は、オプション名と引数のフラグからな
	る配列でなければいけません。

	    parser.set_options(['-d', '--debug', GetoptLong::NO_ARGUMENT],
	                       ['--version',     GetoptLong::NO_ARGUMENT],
                               ['--help',        GetoptLong::NO_ARGUMENT])

	配列中のオプション名は、一文字オプション (例: '-d') か長いオプ
	ション (例: '--debug') を表した文字列のいずれかでなければなり
	ません。配列の中の一番左端のオプション名が、オプションの正式名
	になります。配列中の引数のフラグは、NO_ARGUMENT, REQUIRE_ARGUMENT,
	OPTIONAL_ARGUMENT のいずれかでなくてはなりません。

	オプション名と引数のフラグの順番に決まりはないので、次のような
	形式でも構いません。

	    parser.set_options([GetoptLong::NO_ARGUMENT, '-d', '--debug'],
	                       [GetoptLong::NO_ARGUMENT, '--version'],
                               [GetoptLong::NO_ARGUMENT, '--help'])

	不正な引数が `set_option' メソッドに与えられると、例外
	`ArgumentError' が発生します。

	オプションを設定できるのは、`get', `get_option', `each',
	`each_option' メソッドを呼び出す前だけです。これらのメソッドを
	呼び出した後でオプションを設定しようとすると、`RuntimeError'
	例外が発生します。

	デフォルトでは、オプションは何も設定されていません。

terminate?
	エラーが起きずにオプションの処理が終了しているときは `TRUE' が
	返ります。それ以外のときは、`FALSE' が返ります。

定数
----
PERMUTE
REQUIRE_ORDER
RETURN_IN_ORDER
	順序形式を表しています。

NO_ARGUMENT
REQUIRED_ARGUMENT
OPTIONAL_ARGUMENT
	オプションへの引数のフラグです。