Ruby 2.3.0 リファレンスマニュアル > ライブラリ一覧 > optparseライブラリ > OptionParserクラス
クラスの継承リスト: OptionParser < Object < Kernel < BasicObject
コマンドラインのオプションを取り扱うためのクラスです。
オプションが指定された時に呼ばれるブロックを OptionParser#on メソッドで登録していきます。 つまり、OptionParser を使う場合、基本的には
というような流れになります。
require "optparse"
ProgramConfig = Hash.new
opts = OptionParser.new
opts.on("-a"){|v| ProgramConfig[:a] = true } # オプション「-a」がコマンドラインで指定されていた場合の動作。
opts.parse!(ARGV) # 実際にコマンドラインの parse を行う。
以下はデフォルトで利用可能なオプションです。オプションサマリには 出てきません。
オプションサマリを表示してから exit します。
OptionParser#ver を表示してから exit します。 OptionParser#ver が定義されていない場合は、そのようにエラーメッセージを出力して abort します。 オプション「--version」に「,」で区切られたクラス名かモジュール名を引数として与えた場合は、そのクラスおよびモジュールで定義されている定数「Version」および「Release」を表示して、終了します。
$ ruby t.rb --version=OptionParser,URI,OpenSSL t: OptionParser version 12203 (2007-04-20) t: URI version 0.9.11 t: OpenSSL version 1.0.0
accept(klass, pat = /.*/) {|str| ...} -> ()[permalink][rdoc]オプションの引数を文字列から Ruby のオブジェクトに変換するための ブロックを登録します。すべての OptionParser インスタンスに共通です。
ブロックには、文字列として与えられるオプションの引数から klass のインスタンスを生成して返すものを指定します。
OptionParser#on で klass を指定した場合、 コマンドラインのオプションに与えられた引数は、この accept で登録したブロックで klass のインスタンスに変換されてから、OptionParser#on メソッドで登録したブロックに渡されます。
require "optparse"
require "time"
OptionParser.accept(Time) do |s,|
begin
Time.parse(s) if s
rescue
raise OptionParser::InvalidArgument, s
end
end
opts = OptionParser.new
opts.on("-t", "--time [TIME]", Time) do |time|
p time.class #=> Time
end
opts.parse!(ARGV)
いくつかのクラスに対しては変換用のブロックがデフォルトで登録されて います。OptionParser#on を参照して下さい。
getopts(argv, *opts) -> Hash[permalink][rdoc]getopts(*opts) -> Hash引数をパースした結果を、Hash として返します。(self.new.getopts と同じです)
[SEE_ALSO] OptionParser#getopts
new(banner = nil, width = 32, indent = ' ' * 4) -> OptionParser[permalink][rdoc]new(banner = nil, width = 32, indent = ' ' * 4) {|opt| ...} -> OptionParserOptionParser オブジェクトを生成して返します。
ブロックが与えられた場合、生成した OptionParser オブジェクトを引数としてブロックを評 価します。つまり、以下のような書き方が可能です。
require 'optparse'
OptionParser.new do |opt|
opt.on('-a') {|v| p v }
opt.on('-b') {|v| p v }
opt.parse!(ARGV)
end
reject(klass) -> ()[permalink][rdoc]OptionParser.accept メソッドで登録したブロックを削除します。
accept(klass, pat = /.*/) {|str| ...} -> ()[permalink][rdoc]OptionParser.accept と同様ですが、 登録したブロックはレシーバーに限定されます。
例
require "optparse"
require "time"
opts = OptionParser.new
opts.accept(Time) do |s,|
begin
Time.parse(s) if s
rescue
raise OptionParser::InvalidArgument, s
end
end
opts.on("-t", "--time [TIME]", Time) do |time|
p time.class # => Time
end
opts.parse!(ARGV)
banner -> String[permalink][rdoc]サマリの最初に表示される文字列を返します。
例
require "optparse"
options = {}
opts = OptionParser.new do |opts|
opts.banner = "Usage: example.rb [options]"
opts.on("-v", "--[no-]verbose", "Run verbosely") do |v|
options[:verbose] = v
end
end
p opts.banner # => "Usage: example.rb [options]"
banner=(heading)[permalink][rdoc]サマリの最初に表示される文字列を指定します。
例
require "optparse"
options = {}
opts = OptionParser.new do |opts|
opts.banner = "Usage: example.rb [options]" # => "Usage: example.rb [options]"
opts.on("-v", "--[no-]verbose", "Run verbosely") do |v|
options[:verbose] = v
end
end
opts.banner # => "Usage: example.rb [options]"
default_argv -> [String][permalink][rdoc]自身がデフォルトでパースする引数を文字列の配列で返します。
default_argv=(argv)[permalink][rdoc]自身がデフォルトでパースする引数を文字列の配列で指定します。
OptionParser#parse の引数が指定されなかったときに使われます。
environment(env) -> [String][permalink][rdoc]環境変数 env に対して Shellwords.#shellwords を呼 んで配列にしてから parse を行ないます。
getopts(argv, *opts) -> Hash[permalink][rdoc]getopts(*opts) -> Hash引数をパースした結果を、Hash として返します。
配列 argv を与えた場合、argv をパースします。そうでない場合は、 default_argv をパースします。
opt = OptionParser.new params = opt.getopts(ARGV, "ab:", "foo", "bar:") # params["a"] = true # -a # params["b"] = "1" # -b1 # params["foo"] = true # --foo # params["bar"] = "x" # --bar x
help -> String[permalink][rdoc]to_s -> Stringサマリの文字列を返します。
例
require "optparse"
options = {}
opts = OptionParser.new do |opts|
opts.banner = "Usage: example.rb [options]"
opts.on("-v", "--[no-]verbose", "Run verbosely") do |v|
options[:verbose] = v
end
end
puts opts.help
# => Usage: example.rb [options]
# -v, --[no-]verbose Run verbosely
load(filename = nil) -> bool[permalink][rdoc]指定された filename を読み込んで各行をまとめたものに対して OptionParser#parse を行ないます。
パースが成功した場合に true を返します。 ファイルが存在しなかった場合に false を返します。
例
require "optparse"
IO.write("options.txt", %w(-a --b).join("\n"))
options = { a: false, b: false }
OptionParser.new do |opt|
opt.on('-a') { |v| options[:a] = v }
opt.on('--b') {|v| options[:b] = v }
opt.load("options.txt") # => true
opt.load("not_exist.txt") # => false
end
p options # => {:a=>true, :b=>true}
on(short, desc = "") {|v| ... } -> self[permalink][rdoc]on(long, desc = "") {|v| ... } -> selfon(short, long, desc = "") {|v| ... } -> selfオプションを取り扱うためのブロックを自身に登録します。 ブロックはコマンドラインのパース時に、オプションが指定されていれば呼ばれます。
ショートオプションとロングオプションを同時に登録することもできます。
opts.on("-r", "--require LIBRARY"){|lib| ...}
これは以下と同値です。
opts.on("-r LIBRARY"){|lib| ...}
opts.on("--require LIBRARY"){|lib| ...}
複数の異なるオプションに同じブロックを一度に登録することもできます。
opt.on('-v', '-vv'){|boolean| ...}
opt.on('--require X', '--need', '--dependon'){|x| ... }
on("-x"){|boolean| ...}
となります。コマンドラインにオプションが存在した場合 true を引数と
してブロックを評価します。
ショートオプションが引数をとる場合は、
on("-x MANDATORY"){|val| ...}
となります。"MANDATORY" の部分は任意の文字列で構いません。
オプションの引数が必須でない場合は [ ] をつけて、
on("-x [OPTIONAL]"){|val| ...}
となります。
on("--long"){|boolean| ...}
on("--long MANDATORY"){|val| ...}
on("--long [OPTIONAL]"){|val| ...}
と指定できます。
on(short, pat = /.*/, desc = "") {|v| ...} -> self[permalink][rdoc]on(long, pat = /.*/, desc = "") {|v| ...} -> selfon(short, long, pat = /.*/, desc = "") {|v| ...} -> selfオプションを取り扱うためのブロックを自身に登録します。 ブロックはコマンドラインのパース時に、オプションが指定されていれば呼ばれます。
pat にはオプションの引数に許すパターンを表す正規表現で与えます。 コマンドに与えられた引数がパターンにマッチしない場合、 例外 OptionParser::InvalidArgument が parse 実行時に投げられます。
opts.on("--username VALUE", /[a-zA-Z0-9_]+/){|name| ...}
# ruby command --username=ruby_user
# ruby command --username=ruby.user #=> Error
on(short, klass = String, desc = "") {|v| ...} -> self[permalink][rdoc]on(long, klass = String, desc = "") {|v| ...} -> selfon(short, long, klass = String, desc = "") {|v| ...} -> selfオプションを取り扱うためのブロックを自身に登録します。 ブロックはコマンドラインのパース時に、オプションが指定されていれば呼ばれます。
klass にはクラスを与えます。どのようなクラスを受け付けるかは、 以下の「デフォルトで利用可能な引数クラス」を参照して下さい。 OptionParser.accept や OptionParser#accept によって、受け付け るクラスを増やすことができます。登録されていないクラスが指定された 場合、例外 ArgumentError を投げます。 また、登録されたクラスであっても引数が変換できないものである場合、例外 OptionParser::InvalidArgument を投げます。
オプションの引数は accept で登録したブロックで klass のインスタンス に変換されてから、ブロックに渡されます。
opts.on("-w", "--width N", Integer){|w|
p w.class #=> Integer
}
# ruby command --width=32
opts.on("-o", "--overwrite VALUE", TrueClass){|boolean| ...}
# ruby command --overwrite yes
オプションの引数は変換されません。
オプションの引数は変換されません。ただし、空文字列を指定すると OptionParser::InvalidArgument が発生します。
Integer オブジェクトに変換されます。"0b1"、"07"、"99"、"0xff" といった 2進数、8進数、10進数、16進数の整数のフォーマットを指定できます。
Float オブジェクトに変換されます。"1.0" や "0.5e0" のようなフォーマッ トを指定できます。
整数の場合は Integer オブジェクトに、実数の場合は Float オブジェクトに 変換されます。
Integer オブジェクトに変換されます。10進数の整数の整数のフォーマットの みを指定できます。
Integer オブジェクトに変換されます。"0b1"、"07"、"0xff" といった 2進数、 8進数、16進数の整数のフォーマットを指定できます。
整数の場合は Integer オブジェクトに、実数の場合は Float オブジェクトに 変換されます。10進数のフォーマットを指定できます。
true か false に変換されます。"yes" や "no"、"true" や "false"、"+" や "-" を指定できます。オプションの引数を省略した場合は true になります。 また、"no-" をオプションの先頭に付けた場合は値が反転します。
true か false に変換されます。TrueClass との違いはオプションの引数を省 略した場合に false になります。
文字列の配列に変換されます。"," ごとに 1つの要素になります。
on(short, *rest) {|v| ...} -> self[permalink][rdoc]on(long, *rest) {|v| ...} -> selfon(short, long, *rest) {|v| ...} -> selfオプションを取り扱うためのブロックを自身に登録します。 ブロックはコマンドラインのパース時に、オプションが指定されていれば呼ばれます。
コマンドに与えられた引数が配列やハッシュに含まれない場合、例外 OptionParser::InvalidArgument が OptionParser#parse 実行時 に発生します。
例:
opts.on("--protocol VALUE", [:http, :ftp, :https]){|w|
p w
}
# ruby command --protocol=http #=> :http
opts.on("-c", "--charset VALUE", {"jis" => "iso-2022-jp", "sjis" => "shift_jis"}){|w|
p w
}
# ruby command --charset=jis #=> "iso-2022-jp"
on_head(*arg, &block) -> self[permalink][rdoc]オプションを取り扱うためのブロックを自身の持つリストの最初に登録します。
例
require "optparse"
opts = OptionParser.new do |opts|
opts.on_head("-i", "--init")
opts.on("-u", "--update")
opts.on_tail("-h", "--help")
end
puts opts.help
# => Usage: test [options]
# -i, --init
# -u, --update
# -h, --help
[SEE_ALSO] OptionParser#on, OptionParser#on_tail
on_tail(*arg, &block) -> self[permalink][rdoc]オプションを取り扱うためのブロックを自身の持つリストの最後に登録します。
--version や --help の説明をサマリの最後に表示したい時に便利です。
例
require "optparse"
opts = OptionParser.new do |opts|
opts.on_head("-i", "--init")
opts.on("-u", "--update")
opts.on_tail("-h", "--help")
end
puts opts.help
# => Usage: test [options]
# -i, --init
# -u, --update
# -h, --help
例
require "optparse"
opts = OptionParser.new
opts.on_tail("-h", "--help", "Show this message") do
puts opts
exit
end
opts.on_tail("--version", "Show version") do
puts OptionParser::Version.join('.')
exit
end
[SEE_ALSO] OptionParser#on, OptionParser#on_head
order(argv) -> [String][permalink][rdoc]order(argv) {|s| ...} -> [String]order(*args) -> [String]order(*args) {|s| ...} -> [String]与えられた argv を順番にパースします。 オプションではないコマンドの引数(下の例で言うと somefile)に出会うと、パースを中断します。 argv からオプションを取り除いたものを返します。
ブロックが与えられている場合は、パースを中断せずに引数をブロックに渡してブロックを評価し、 パースを継続します。argv を返します。
下の例で言うと、コマンドの引数 somefile よりも後ろにオプションを置くことができま せん。-b もコマンドのオプションではない引数として扱われてしまいます。
例:
$ cat opt.rb
require 'optparse'
opt = OptionParser.new
opt.on('-a [VAL]') {|v| p :a }
opt.on('-b') {|v| p :b }
opt.order(ARGV)
p ARGV
$ ruby opt2.rb -a foo somefile -b
:a
["-a", "foo", "somefile", "-b"]
order!(argv = self.default_argv) -> [String][permalink][rdoc]order!(argv = self.default_argv) {|s| ...} -> [String]与えられた argv を順番に破壊的にパースします。 argv からオプションがすべて取り除かれます。 argv を返します。
オプションではないコマンドの引数(下の例で言うと somefile)に出会うと、パースを中断します。 ブロックが与えられている場合は、パースを中断せずに 引数をブロックに渡してブロックを評価し、パースを継続します。argv を返します。
下の例で言うと、コマンドの引数 somefile よりも後ろにオプションを置くことができません。 -b もコマンドのオプションではない引数として扱われてしまいます。
例:
$ cat opt.rb
require 'optparse'
opt = OptionParser.new
opt.on('-a [VAL]') {|v| p :a }
opt.on('-b') {|v| p :b }
opt.order!(ARGV)
p ARGV
$ ruby opt2.rb -a foo somefile -b
:a
["somefile", "-b"]
parse(argv) -> [String][permalink][rdoc]parse(*args) -> [String]与えられた argv をパースします。 argv からオプションを取り除いたものを返します。
OptionParser#permute と同様に振舞います。しかし、 環境変数に POSIXLY_CORRECT が設定されている場合は、 OptionParser#order と同様に振舞います。
parse!(argv = self.default_argv) -> [String][permalink][rdoc]与えられた argv をパースします。
OptionParser#permute! と同様に argv を破壊的にパースします。 環境変数に POSIXLY_CORRECT が設定されている場合は、 OptionParser#order! と同様に振舞います。
permute(argv) -> [String][permalink][rdoc]permute(*args) -> [String]与えられた argv をパースします。 オプションではないコマンドの引数(下の例で言うと somefile)があってもパースを中断しません。 argv からオプションを取り除いたものを返します。
下の例で言うと、order と違いコマンドの引数 somefile よりも後ろにオプションを置くことが できます。
例:
$ cat opt.rb
require 'optparse'
opt = OptionParser.new
opt.on('-a [VAL]') {|v| p :a }
opt.on('-b ') {|v| p :b }
opt.permute!(ARGV)
p ARGV
$ ruby opt2.rb -a foo somefile -b
:a
:b
["somefile"]
permute!(argv = self.default_argv) -> [String][permalink][rdoc]与えられた argv を破壊的にパースします。argv からオプションがすべて取り除かれます オプションではないコマンドの引数(下の例で言うと somefile)があってもパースを中断しません。 argv を返します。
下の例で言うと、order と違いコマンドの引数 somefile よりも後ろにオプションを置くことが できます。
例:
$ cat opt.rb
require 'optparse'
opt = OptionParser.new
opt.on('-a [VAL]') {|v| p :a }
opt.on('-b ') {|v| p :b }
opt.permute!(ARGV)
p ARGV
$ ruby opt2.rb -a foo somefile -b
:a
:b
["somefile"]
program_name -> String[permalink][rdoc]プログラムの名前を文字列で返します。
デフォルトは $0 が使われます。
program_name=(name)[permalink][rdoc]プログラムの名前を文字列で指定します。
reject(klass) -> ()[permalink][rdoc]OptionParser#accept で登録したクラスとブロックを 自身から削除します。
release -> String[permalink][rdoc]プログラムのリリースを文字列で返します。
release=(rel)[permalink][rdoc]プログラムのリリースを文字列で指定します。
[SEE_ALSO] [[OptionParser#ver]]
separator(sep) -> ()[permalink][rdoc]サマリにオプションを区切るための文字列 sep を挿入します。 オプションにいくつかの種類がある場合に、サマリがわかりやすくなります。
サマリには on メソッドを呼んだ順にオプションが表示されるので、区切りを挿入したい ところでこのメソッドを呼びます。
例:
require 'optparse'
opts = OptionParser.new
opts.banner = "Usage: example.rb [options]"
opts.separator ""
opts.separator "Specific options:"
opts.on("-r", "--require LIBRARY") do |lib|
options.library << lib
end
opts.separator ""
opts.separator "Common options:"
opts.on_tail("-h", "--help", "Show this message") do
puts opts
exit
end
summarize(to = [], width = self.summary_width, max = width - 1, indent= self.summary_indent) -> ()[permalink][rdoc]summarize(to = [], width = self.summary_width, max = width - 1, indent= self.summary_indent) {|line| ... } -> ()サマリを指定された to へと加えていきます。
ブロックが与えられた場合、サマリの各行を引数としてブロックを評価します。 この場合、ブロックの中で明示的に to へと加えていかない限り、 to にサマリが加えられることはありません。
summary_indent -> String[permalink][rdoc]サマリを表示する時のインデントを文字列で返します。
summary_indent=(indent)[permalink][rdoc]サマリを表示する時のインデントを文字列で指定します。
summary_width -> Integer[permalink][rdoc]サマリを表示するときの幅を整数で返します。
summary_width=(width)[permalink][rdoc]サマリを表示するときの幅を整数で指定します。
to_a -> [String][permalink][rdoc]サマリの各行を要素とした配列を返します。
ver -> String[permalink][rdoc]program_name、version と release から生成したバージョンを表す文字列を返します。
例
require "optparse"
OptionParser.new do |opts|
opts.banner = "Usage: example.rb [options]"
opts.program_name = "Optparse Example"
opts.version = [0, 1]
opts.release = "2019-05-01"
opts.on_tail("--version", "Show version") do
puts opts.ver # => "Optparse Example 0.1 (2019-05-01)"
exit
end
opts.parse!(ARGV)
end
version -> String[permalink][rdoc]プログラムのバージョンを文字列で返します。
[SEE_ALSO] [[OptionParser#ver]]
version=(ver)[permalink][rdoc]プログラムのバージョンを文字列で指定します。
[SEE_ALSO] [[OptionParser#ver]]