コマンドラインオプション解析用ライブラリ。
サポートしている機能:
OptionParser::ParseError オプション解析時のエラー
+--------------+
| OptionParser |<>-----+
+--------------+ | +--------+
| ,-| Switch |
on_head -------->+-------------+ / +--------+
accept/reject -->| List |<|>-
| |<|>- +----------+
on ------------->+-------------+ `-| argument |
: : | class |
+-------------+ |==========|
on_tail -------->| | |pattern |
+-------------+ |----------|
OptionParser.accept ->| DefaultList | |converter |
reject |(全インスタン| +----------+
| スで共有) |
+-------------+
各スイッチのクラス。
OptionParser::Switch#parse(arg, val) {semi-error handler}引数をパース、変換してarg、block、変換結果を返す。
@patternにマッチした部分文字列のリスト、 $&, $1, $2 など。
スイッチに直に指定されていた引数の文字列。
スイッチ以降の引数。
block
エラーかも知れないときに例外をyieldする。
OptionParser::Switch#summarize(sdone, ldone, width, max, indent)オプションサマリを作る。
すでにサマリに入っている短形式オプションをキーとするハッシュ。
すでにサマリに入っている長形式オプションをキーとするハッシュ。
左側のオプションリスト部分の幅。 オプションの説明はその右側、width桁目から始まる。
左側の最大幅。 オプションはmax桁以内に詰められる。
各行をインデントするための文字列。
block
各行ごとに渡される(改行は付かない)。
OptionParser::Switch#-@反転したブーリアンスイッチ(@blockに渡される引数が反転される)を作る
単一のオプションリスト、短/長形式のオプション文字列からスイッチへのマッピング、受け付けられる引数タイプからパターンとコンバータへのマッピングを提供する。 サマリもここで提供される。
OptionParser::List#atype引数タイプからパターン/コンバータのペアへのマップ。
OptionParser::List#short短形式のオプションスイッチからスイッチオブジェクトへのマップ。
OptionParser::List#long長形式のオプションスイッチからスイッチオブジェクトへのマップ。
OptionParser::List#list全スイッチとサマリ文字列のリスト。
OptionParser::List#prepend(switch, short_opts, long_opts, nolong_opts)switchをリストの頭に挿入して、短/長/否定形式のオプションに対応させる。
OptionParser::List#append(switch, short_opts, long_opts, nolong_opts)switchをリストの最後に追加して、短/長/否定形式のオプションに対応させる。
挿入するOptionParser::Switchインスタンス。
switchに対応する短形式オプションのリスト。
switchに対応する長形式オプションのリスト。
"no-"のつく否定形式のオプションのリスト。
OptionParser::List#search(id, key) [{block}]keyをidのリストから検索する。
検索するリスト。
検索するキー。
Block
見付かったときにその値で呼び出される。
OptionParser::List#complete(id, opt, *pat, &block)optをidのリストから*patで補完して検索する。
検索するリスト。
検索するキー。
補完に使うパターン。
Block
見付かったときにその値で呼び出される。
OptionParser::List#summarize(*args) {...}サマリテーブルを作る。
一行ごとにblockを呼び出す。
@listの要素はsummarizeできる必要がある。
そのまま各要素の summarize に渡される。
block
各行ごとに渡される(改行は付かない)。
オプションパーサのフロントエンド。
OptionParser::ArgumentStyle取りうる引数のスタイルの種類。 値はそれぞれ:
OptionParser::NO_ARGUMENT
引数を取らないスイッチ。
OptionParser::REQUIRED_ARGUMENT
引数が必須のスイッチ。
直後に引数が=で指定されていなければ、次の文字列を引数とみなす。
空の引数を指定するときは、=だけをつける。
OptionParser::OPTIONAL_ARGUMENT
オプショナルな引数を取るスイッチ。 つまり引数を付けても付けなくてもよい。
引数を指定するときは--switch=argument(長形式)か、
-Xargument(短形式)とする。
短形式では、引数パターンにマッチする部分だけが引数として認識される。
OptionParser::DefaultList'--'のように全OptionParserインスタンスで共有するスイッチや、デフォルトの引数クラスを持つ。
OptionParser.with([banner[, width[, indent]]]) [{...}]新しいインスタンスを作成して、イテレータとして呼ばれているときにはブロックをそのインスタンスのコンテクストで評価してから、返す。
この動作は以前のnewと同じだが、depricatedなメソッド。
cf. OptionParser#initialize
バナーメッセージ。
サマリの幅。
サマリのインデント文字列。
Block
作成したインスタンスのコンテクストで評価される。
OptionParser.new([banner[, width[, indent]]]) [{...}]インスタンスを初期化する。 イテレータとして呼ばれている場合は、自分自身を渡す。
バナーメッセージ。
デフォルトはnil。
サマリの幅。 デフォルトは32
サマリのインデント。 デフォルトは空白4個。
Block
selfが渡される。
OptionParser.terminate([arg])オプションの解析を終了させる。 省略可能なargが与えられていると、コマンドライン引数に戻される。
最初のオプションでない引数として戻される文字列。
OptionParser.accept(t, [pat]) {...}
OptionParser#accept(t, [pat]) {...}指定したクラスのオプション引数を受け付けられるようにする。
引数クラスを指定するオブジェクト、通常はClass。
引数のパターン。
tがmatchを持っていればそれがデフォルト。
Block
引数の文字列を受け取って要求されるクラスに変換する。
OptionParser.reject(t)
OptionParser#reject(t)指定したクラスのオプション引数を受け付けないようにする。
引数クラスを指定するオブジェクト。
OptionParser#banner
OptionParser#banner=(heading)サマリの先頭に出力されるバナー。
OptionParser#summary_width
OptionParser#summary_width=(width)サマリのオプションリスト部分の幅。
Numericである要がある。
OptionParser#summary_indent
OptionParser#summary_indent=(indent)サマリのインデント。
Stringでなければならない(もしくは
Stringを+できるモノ)。
OptionParser#program_name
OptionParser#program_name=(name)エラーメッセージやデフォルトのバナーで出力されるプログラム名。
デフォルトは$0。
OptionParser#topon/on_head、accept/rejectの対象。
OptionParser#baseon_tailの対象。
OptionParser#new新しいListを追加する。
OptionParser#remove最後のListを削除する。
OptionParser#summarize(to = [], width = @summary_width, max = width - 1, indent = @summary_indent)オプションサマリをtoに作る。 toを返す。
出力先。
<<メソッドが必要。
デフォルトは[]。
左側、オプションリスト部の幅。 デフォルトは@summary_width。
左側で使える最大幅。
デフォルトはwidth - 1。
インデント。 デフォルトは@summary_indent。
Block
イテレータとして呼ばれていると、各行ごとに呼び出される。
OptionParser#to_str
OptionParser#to_sオプションサマリ文字列を返す。
OptionParser#to_aオプションサマリを配列として返す。
OptionParser#switchオプション定義。
受け付けられるオプション引数の形式。
OptionParser.acceptや
OptionParser#acceptであらかじめ定義されているか、
Regexpなどのmatchメソッドを持つオブジェクトでなければならない。
これは一度だけ指定できる(もしなければObjectとみなされる)が、さもなければArgumentErrorを起こす。
cf. 引数として受け付けられるクラス.
取り得る引数の値。
handlerを与える別の手段。
それぞれ引数が必須、省略可能、無しの長形式スイッチ。
それぞれ引数が必須、省略可能、無しの短形式スイッチ。
キャラクタクラスにマッチする短形式のスイッチ (正規表現全てが使えるわけではない)。
引数スタイル。
このスイッチの説明。
Block
このスイッチが指定されたときに呼び出されるhandler。
OptionParser#on(*opts) [{...}]
OptionParser#def_option(*opts) [{...}]
OptionParser#on_head(*opts) [{...}]
OptionParser#def_head_option(*opts) [{...}]
OptionParser#on_tail(*opts) [{...}]
OptionParser#def_tail_option(*opts) [{...}]オプションスイッチとハンドラを定義する。
on_head、def_head_optionと
on_tail、def_tail_optionはそれぞれスイッチをサマリの最初と最後におく。
cf. OptionParser#switch.
OptionParser#order(*argv) [{...}]
OptionParser#order!([argv = ARGV]) [{...}]argvを出て来る順番にしたがって解析する。 オプションでない引数があると、イテレータとして呼ばれていればそれを渡して呼び出す。 さもなければ解析を終了する。 解析されずに残ったargvを返す。
order!は配列自身を受け取って、スイッチを破壊的に取り除く。
デフォルトではARGVを解析する。
解析するコマンドライン引数の配列。
Block
オプションでない引数があると呼び出される。
OptionParser#permute(*argv)
OptionParser#permute!([argv = ARGV])argvを並び変えモードで解析して、オプションでない引数のリストを返す。
permute!は配列自身を受け取って、スイッチを破壊的に取り除く。
デフォルトではARGVを解析する。
解析するコマンドライン引数の配列。
OptionParser#parse(*argv)
OptionParser#parse!([argv = ARGV])環境変数POSIXLY_CORRECTがセットされているときは順序通りに、それ以外は並べ変えモードで、argvを解析する。
parse!は配列自身を受け取って、スイッチを破壊的に取り除く。
デフォルトではARGVを解析する。
解析するコマンドライン引数の配列。
任意の文字列、変換されない。 何も指定しないとこれになる。
任意の空でない文字列、変換されない。
Ruby/C的な整数、0で始まれば8進数、0bで始まれば2進数、
0xで始まれば16進数、それ以外は10進数とみなす。
符号も付けられる。
Integerに変換される。
実数形式、Floatに変換される。
汎用の数値、整数形式ならInteger、実数形式なら
Floatに変換される。
10進整数、Integerに変換される。
Ruby/C的な 8/16/2進整数、Integerに変換される。
10進整数/実数形式。
整数形式ならInteger、実数形式なら
Floatに変換される。
ブーリアンスイッチ、存在すれば真、またはno-が前に付いていれば偽。
もしくはyes/no/true/falseで示される値。
TrueClassと似ているが、デフォルトの値はfalse。
","区切り文字列。
OptionParserで発生する例外のベースクラス。
RuntimeError
エラー原因。
OptionParser::ParseError#reasonエラーの理由を返す。
OptionParser::ParseError#inspect可読形式の文字列を返す。
OptionParser::ParseError#message
OptionParser::ParseError#to_s
OptionParser::ParseError#to_strデフォルトの文字列化メソッド、標準的なエラーメッセージ用。
補完が一意に決められないときに発生する。
引数を取らないスイッチに引数が指定されていたときに発生する。
引数が必要なスイッチに引数が無かったときに発生する。
定義されていないスイッチで発生する。
与えられた引数がフォーマットに合わなかったときに発生する。
与えられた引数が一意に決定できなかったときに発生する。
コマンドライン引数の配列に、自分自身をパースする機能を拡張する。
optparse.rbをrequireすると、ARGVが拡張されている。
OptionParser::Arguable#options=OptionParserオブジェクトをセットする。
optがfalseかnilなら、
OptionParser::Arguable#optionsメソッドと
OptionParser::Arguable#options=メソッドが未定義にされる。
つまり、このレシーバ経由でOptionParserオブジェクトにアクセスする方法は無くなる。
OptionParser::Arguable#options [{...}]実際のOptionParserオブジェクト。 設定されていなければ自動的に作られる。
イテレータとして呼ばれると、OptionParserオブジェクトと共に呼び出して、その結果を戻り値とする。
このとき、OptionParser::ParseError例外は補足され、エラーメッセージをSTDERRに表示するだけでnilを返す。
block
設定されているOptionParserのインスタンスとともに呼ばれる。
OptionParser::Arguable#order!
OptionParser::Arguable#permute!
OptionParser::Arguable#parse!selfを破壊的にパースして、selfを返す。 パースされなかった文字列だけを残す。
OptionParserで定義されている、引数として受け付けられるパターンの定数を含んでいる。
今のところDecimalInteger、OctalInteger、DecimalNumeric。
引数として受け付けられるクラス参照。
require 'optparse'
$0 = File.basename($0)
# keywords
CODES = %w[iso-2022-jp shift_jis euc-jp utf8 binary]
CODE_ALIASES = {"jis" => "iso-2022-jp", "sjis" => "shift_jis"}
POSSIBLE_CODES = "(#{(CODES+CODE_ALIASES.keys).join(',')})"
vars = {}
ARGV.options do
|opts|
opts.banner = "Usage: #{$0} [options] argv...\n"
# separater
opts.on_tail
opts.on_tail("common options:")
# no argument, shows at tail
opts.on_tail("--help", "show this message") {puts opts; exit}
# mandatory argument
opts.on("-r", "--require=LIBRARY", String,
"require the LIBRARY, before",
"executing your script") {|vars[:library]|}
# optional argument
opts.on("-i", "--inplace=[EXTENSION]",
"edit ARGV files in place", # multiline description
"(make backup if EXTENSION supplied)") {|vars[:inplace]| vars[:inplace] ||= ''}
opts.on("-N=[NUM]", Integer) {|vars[:number]|}
# additional class
# opts.on("-t", "--time=TIME", Time, "it's the time") {|vars[:time]|}
# limit argument syntax
opts.on("-[0-7]", "-F", "--irs=[OCTAL]", OptionParser::OctalInteger,
"specify record separator", "(\\0, if no argument)") {|vars[:irs]|}
# boolean switch(default true)
vars[:exec] = true
opts.on("-n", "--no-exec", "not really execute") {|vars[:exec]|}
# array
opts.on("-a", "--list[=LIST,LIST]", Array, "list") {|vars[:list]|}
# fixed size array
opts.on("--pair[=car,cdr]", Array, "pair") {|vars[:x], vars[:y]|}
# keyword completion
opts.on("--code=CODE", CODES, CODE_ALIASES, "select coding system", POSSIBLE_CODES) {|vars[:code]|}
# optional argument with keyword completion
opts.on("--type[=TYPE]", [:text, :binary], "select type(text, binary)") {|vars[:type]|}
# boolean switch with optional argument(default false)
opts.on("-v", "--[no-]verbose=[FLAG]", "run verbosely") {|vars[:verbose]|}
# easy way, set local variable
opts.on("-q", "--quit", "quit when ARGV is empty") {|vars[:quit]|}
# adding on the fly
opts.on("--add=SWITCH=[ARG]", "add option on the fly", /\A(\w+)(?:=.+)?\Z/) do
|opt, var|
opts.on("--#{opt}", "added in runtime", &eval("proc {|vars[:#{var}]|}"))
end
opts.on_head("specific optins:")
# no argument
opts.on_tail("--version", "show version") do
puts OptionParser::Version.join('.')
exit
end
opts.parse!
end
if (Fixnum === :-)
class << vars
def inspect
"{" + collect {|k,v| ":#{k.id2name}=>#{v.inspect}"}.join(", ") + "}"
end
end
end
p vars
(puts ARGV.options; exit) if vars[:quit]
ARGV.options = nil # no more parse
puts "ARGV = #{ARGV.join(' ')}" if !ARGV.empty?
#opts.variable.each {|sym| puts "#{sym} = #{opts.send(sym).inspect}"}