ruby-trad-getopt
伝統的な getopt に近い getopt。コマンドラインオプションを解析する。
getopt(argv, opts, longopts = nil, KWARGS…)
argv にはコマンドライン引数文字列のリストをとる。opts にはショートオプ ションとする文字を並べた文字列、longopts にはロングオプションを定義す るハッシュをとる。
argv の先頭の要素が opts または longopts に定義されたコマンドラインオ プションであるなら、オプションの種類に応じて次のような、オプション文字 (列)を第 1 要素とするリストを返す。
・引数なしオプションなら [ "オプション文字" ] ・引数つきオプションなら [ "オプション文字", "引数" ] ・オプショナル引数つきオプションの場合、引数が、 ・あるなら [ "オプション文字", "引数" ] ・無いなら [ "オプション文字", nil ]
argv の先頭の要素がコマンドラインオプションでない場合、または argv が 空の場合には nil を返す。
コマンドラインオプションとして処理した要素は argv から削除する。argv は破壊的に変更されるので、解析をリセットする必要がある場合、あらかじめ 呼び出し側で複製した argv を用いる必要がある。
単独の `–' はオプション解析の停止を意味する特別なオプションとして扱い、 argv からは削除して nil を返す。単独の `-' は非オプションとして扱い、 argv から削除せず nil を返す。
エラーした場合、第 1 要素にエラーの種類を表すシンボル、第 2 要素にエラー したオプション文字(列)を置いたリストを返す。
ショートオプション¶ ↑
opts には “ab:c” のような、ショートオプションとする文字を並べた文字列 をとる。
・通常の文字は引数なしショートオプションとなる ・後ろに `:' を置いた文字は引数つきショートオプションとなる ・後ろに `::' を置いた文字はオプショナル引数つきショートオプションと なる
引数つきショートオプションのオプションと引数は、argv 上の続く 2 要素で あっても ([ “-a”, “foo” ])、1 つの要素であっても ([ “-afoo” ]) よい。 オプショナル引数つきショートオプションはオプションと引数が 1 つの要素 で指定されたときのみ引数ありと解釈する。
argv 上で [ “-a”, “-b”, “-c”, “foo” ] のように連続しているショートオプ ションが [ “-abcfoo” ] のように連結されていてもよい。このとき getotpt() はこの要素を、呼び出し毎に “-bcfoo”、“-cfoo”、削除、と変更す る。
ロングオプション¶ ↑
longopts にはキーをオプション名、値をシンボルとするハッシュをとる。有 効なシンボルは次の通り。
・:no_argument - 引数なしロングオプション ・:required_argument - 引数つきロングオプション ・:optional_argument - オプショナル引数つきロングオプション
ロングオプションに引数を与えるには “–bar=引数” のようにオプションと引 数を空白なしに `=' でつなげた形をとる。引数つきロングオプションは argv 上で連続する 2 要素に分かれていてもよい ([ “–bar”, “引数” ])。オプショ ナル引数つきロングオプションは `=' 区切りの 1 要素による指定の場合のみ 引数をとる。
ロングオプションは一意に特定できる限りにおいて省略できる。ただし省略形 に完全一致するロングオプションを優先する。
エラー¶ ↑
エラーすると標準エラー出力にメッセージを出力し、エラーを示すシンボルと エラーを生じたオプション文字(列)からなるリストを返す。エラーしたオプショ ンは argv から削除する。
キーワード引数 use_exception を真にするとエラー時に例外を発生するよう になる。例外は Getopt::GetoptError
をベースクラスとしており、インスタ ンスメソッド option() からエラーしたオプションを得られる。
エラーを示すシンボルと対応する例外クラスは以下の通り:
-
:unknown_option (
Getopt::UnknownOptionError
) 未定義のオプション -
:argument_required (
Getopt::ArgumentRequiredError
) 引数つきオプションに引数が無い -
:argument_given (
Getopt::ArgumentGivenError
) 引数なしロングオプションに引数が指定された -
:ambiguousu_option (
Getopt::AmbiguousOptionError
) ロングオプションの省略形が一意でない。このときエラーメッセージに候補 を示す。:ambiguousu_option のみ返り値の第 2 要素はオプション文字と 候補リストのリストになる。例外を有効としている場合、候補リストはGetopt::AmbiguousOptionError#candidates()
で取得できる。
キーワード引数¶ ↑
-
abbreviation => true 偽にするとロングオプションの省略形が無効になる。
-
allow_empty_optarg => true 偽にすると、引数つきオプションまたはオプショナル引数つきオプションで、 オプションの引数が空文字列だったときにエラー (:argument_required) と する。
-
error_message => true 偽にするとエラーメッセージを出力しなくなる。
-
optional_short => true 偽にするとオプショナル引数つきショートオプションを無効にする。opts 中の “::” を “:” と解釈してただの引数つきオプションとする。
-
parse => false 真にすると、オプション文字でなくオプションに関する情報をまとめたリスト を返すようになる。Getopt.parse()、Getopt.list() が使う。
-
permute => false 真にすると、オプションに出会うまで非オプションを飛ばす GNU の getopt を模した動作になる。argv 中にオプションが無ければ nil を返す。読んだ オプションを削除することは変わらないので、nil が返るまで getopt() を 繰り返すと argv には非オプションの引数のみが残ることになる。
-
program_name => nil エラーメッセージに出すプログラム名文字列を指定する。デフォルトは nil で $0 のベース名を使う。
-
stop_by_double_hyphen => true 偽にすると `–' を特別扱いしなくなり、`-' を普通のショートオプション 文字として使えるようになる。
-
use_exception => false 真ならエラー時に例外を発生するようになる。
要注意なオプション文字¶ ↑
-
`-' ショートオプション文字としても解析停止の `–' を優先する都合上、単独 の表記では通常のショートオプションとして得られないが、`-a-' のように ショートオプションの連結中に表れたときには通常のショートオプションと して得られる。 キーワード引数 stop_by_double_hyphen を偽とすることで、`-' を単なる ショートオプション文字としてのみ使えるようになる。 また本実装では、このコンテキストを捉えるために、連結されたオプション の次回の読み出しが `-' になるとき、argv の先頭に :getopt_short とい うシンボルを置く。
-
`:' ショートオプション文字として使うには、引数つきオプションを示す `:' と区別するため、opts の先頭に置かなければならない。C 言語等の getopt() にオプション文字列先頭の `:' が特別な機能を持つものがあるが、 それとは意味が違う点に注意。
-
`>' や `|' などのシェルのメタ文字 コマンドライン上では `->' や `–foo|bar' のようにエスケープして表 記する必要が生じる。具体的には使用しているシェルに依存する。
例¶ ↑
require “trad-getopt”
longopts = {
"foo" => :no_argument, "bar" => :required_argument, "baz" => :optional_argument,
}
while (op, oparg = getopt(ARGV, “ab:c::”, longopts))
case op when "a", "foo" puts "option #{op}" when "b", "bar" puts "option #{op} with #{oparg.inspect}" when "c", "baz" puts "option #{op} with #{oparg.inspect}" when Symbol # errors exit 1 end
end
puts “argv #{ARGV}”