class OptionParser (Ruby 3.0 リファレンスマニュアル)

要約

コマンドラインのオプションを取り扱うためのクラスです。

オプションが指定された時に呼ばれるブロックを OptionParser#on メソッドで登録していきます。つまり、OptionParser を使う場合、基本的には

OptionParser オブジェクト opt を生成する。
オプションを取り扱うブロックを opt に登録する。
opt.parse(ARGV) でコマンドラインを実際に parse する。

というような流れになります。

require "optparse"
ProgramConfig = Hash.new
opts = OptionParser.new
opts.on("-a"){|v| ProgramConfig[:a] = true } # オプション「-a」がコマンドラインで指定されていた場合の動作。
opts.parse!(ARGV)                            # 実際にコマンドラインの parse を行う。

デフォルトで利用可能なオプション

以下はデフォルトで利用可能なオプションです。オプションサマリには出てきません。

--help

オプションサマリを表示してから exit します。

--version

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][edit]

オプションの引数を文字列から 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 を参照して下さい。

[PARAM] klass:: クラスオブジェクトを与えます。
[PARAM] pat:: match メソッドを持ったオブジェクト(Regexp オブジェクトなど)を与えます。

getopts(argv, *opts) -> Hash[permalink][rdoc][edit]

getopts(*opts) -> Hash

引数をパースした結果を、Hash として返します。(self.new.getopts と同じです)

[PARAM] argv:: パースしたい配列を指定します。
[PARAM] opts:: 引数を文字列で指定します。
[EXCEPTION] OptionParser::ParseError:: パースに失敗した場合、発生します。実際は OptionParser::ParseError のサブクラスになります。

[SEE_ALSO] OptionParser#getopts

new(banner = nil, width = 32, indent = ' ' * 4) -> OptionParser[permalink][rdoc][edit]

new(banner = nil, width = 32, indent = ' ' * 4) {|opt| ...} -> OptionParser

OptionParser オブジェクトを生成して返します。

ブロックが与えられた場合、生成した OptionParser オブジェクトを引数としてブロックを評価します。つまり、以下のような書き方が可能です。

require 'optparse'
OptionParser.new do |opt|

  opt.on('-a') {|v| p v }
  opt.on('-b') {|v| p v }

  opt.parse!(ARGV)
end

[PARAM] banner:: ヘルプ(サマリ)の最初の部分に表示される、アプリケーションの説明などを文字列で与えます。
[PARAM] width:: サマリの幅を整数で与えます。
[PARAM] indent:: サマリのインデントを文字列で与えます。

reject(klass) -> ()[permalink][rdoc][edit]

OptionParser.accept メソッドで登録したブロックを削除します。

[PARAM] klass:: 削除したいクラスオブジェクトを指定します。

例

require "optparse"
require "time"

def parse(option_parser)
  option_parser.on("-t", "--time [TIME]", Time) do |time|
    p time.class
  end
  option_parser.parse(ARGV)
end

OptionParser.accept(Time) do |s,|
  begin
    Time.parse(s) if s
  rescue
    raise OptionParser::InvalidArgument, s
  end
end

opts1 = OptionParser.new
parse(opts1) # => Time
OptionParser.reject(Time)
opts2 = OptionParser.new
parse(opts2) # => unsupported argument type: Time (ArgumentError)

インスタンスメソッド

accept(klass, pat = /.*/) {|str| ...} -> ()[permalink][rdoc][edit]

OptionParser.accept と同様ですが、登録したブロックはレシーバーに限定されます。

[PARAM] klass:: クラスオブジェクトを与えます。
[PARAM] pat:: match メソッドを持ったオブジェクト(Regexp オブジェクトなど)を与えます。

例

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][edit]

サマリの最初に表示される文字列を返します。

[RETURN]: サマリの最初に表示される文字列を返します。

例

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][edit]

サマリの最初に表示される文字列を指定します。

[PARAM] heading:: サマリの最初に表示される文字列を指定します。

例

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][edit]

自身がデフォルトでパースする引数を文字列の配列で返します。

[PARAM] argv:: デフォルトでパースする文字列の配列を返します。

例

require "optparse"

opts = OptionParser.new

# --hoo param1 --bar param2 をパラメーターに指定して実行
opts.default_argv # => ["--foo", "param1", "--bar", "param2"]

default_argv=(argv)[permalink][rdoc][edit]

自身がデフォルトでパースする引数を文字列の配列で指定します。

OptionParser#parse の引数が指定されなかったときに使われます。

[PARAM] argv:: デフォルトでパースしたい文字列の配列を指定します。

例

require "optparse"

config = {}
opts = OptionParser.new
opts.on("-r", "--require LIBRARY"){|lib| config[:lib] = lib }

# パラメーター指定なしで実行
opts.default_argv # => []
opts.parse!
p config          # => {}

opts.default_argv = ["--require", "lib1"] # => ["--require", "lib"]
opts.default_argv # => ["--require", "param1"]
opts.parse!
p config          # => {:lib=>"lib1"}

environment(env) -> [String][permalink][rdoc][edit]

環境変数 env に対して Shellwords.#shellwords を呼んで配列にしてから parse を行ないます。

[PARAM] env:: 環境変数名を文字列で与えます。
[EXCEPTION] OptionParser::ParseError:: パースに失敗した場合、発生します。実際は OptionParser::ParseError のサブクラスになります。

例

require "optparse"

config = {}
opts = OptionParser.new
opts.on("-r", "--require LIBRARY"){|lib| config[:lib] = lib }

# HOGE_OPT は hoge というプログラム名に対応した名前です
ENV['HOGE_OPT'] = %q{--require lib1 'remain data'}
p opts.environment('HOGE_OPT') # => ["remain data"]
p config                           # => {:lib=>"lib1"}

getopts(argv, *opts) -> Hash[permalink][rdoc][edit]

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

[PARAM] argv:: パースしたい配列を指定します。
[PARAM] opts:: 引数を文字列で指定します。
[EXCEPTION] OptionParser::ParseError:: パースに失敗した場合、発生します。実際は OptionParser::ParseError のサブクラスになります。

help -> String[permalink][rdoc][edit]

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][edit]

指定された filename を読み込んで各行をまとめたものに対して OptionParser#parse を行ないます。

パースが成功した場合に true を返します。ファイルが存在しなかった場合に false を返します。

[PARAM] filename:: 各行をパースしたいファイルの名前を文字列で指定します。指定されないか nil である場合、~/.options/ にプログラムのサフィックスを付けた '~/.options/コマンド名' というファイルをパースします。

例

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][edit]

on(long, desc = "") {|v| ... } -> self

on(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| ... }

[PARAM] short:

ショートオプションを表す文字列を指定します。そのオプションが引数をとらない場合は、

  on("-x"){|boolean| ...}

となります。コマンドラインにオプションが存在した場合 true を引数としてブロックを評価します。ショートオプションが引数をとる場合は、

  on("-x MANDATORY"){|val| ...}

となります。"MANDATORY" の部分は任意の文字列で構いません。オプションの引数が必須でない場合は [ ] をつけて、

  on("-x [OPTIONAL]"){|val| ...}

となります。

[PARAM] long:

ロングオプションを表す文字列を指定します。ショートオプションの時と同様に、

  on("--long"){|boolean| ...}
  on("--long MANDATORY"){|val| ...}
  on("--long [OPTIONAL]"){|val| ...}

と指定できます。

[PARAM] desc:

オプションの説明を文字列で与えます。サマリに表示されます。

on(short, pat = /.*/, desc = "") {|v| ...} -> self[permalink][rdoc][edit]

on(long, pat = /.*/, desc = "") {|v| ...} -> self

on(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

[PARAM] short:: ショートオプションを表す文字列を指定します。
[PARAM] long:: ロングオプションを表す文字列を指定します。
[PARAM] pat:: オプションの引数に許すパターンを表す正規表現で指定します。
[PARAM] desc:: オプションの説明を文字列で与えます。サマリに表示されます。

on(short, klass = String, desc = "") {|v| ...} -> self[permalink][rdoc][edit]

on(long, klass = String, desc = "") {|v| ...} -> self

on(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

[PARAM] short:: ショートオプションを表す文字列を指定します。
[PARAM] long:: ロングオプションを表す文字列を指定します。
[PARAM] klass:: オプションの引数のクラスを指定します。
[PARAM] desc:: オプションの説明を文字列で与えます。サマリに表示されます。
[EXCEPTION] ArgumentError:: 登録されていないクラスが klass に指定された場合に発生します。

デフォルトで利用可能な引数クラス

Object: オプションの引数は変換されません。
String: オプションの引数は変換されません。ただし、空文字列を指定すると OptionParser::InvalidArgument が発生します。
Integer: Integer オブジェクトに変換されます。"0b1"、"07"、"99"、"0xff" といった 2進数、8進数、10進数、16進数の整数のフォーマットを指定できます。
Float: Float オブジェクトに変換されます。"1.0" や "0.5e0" のようなフォーマットを指定できます。
Numeric: 整数の場合は Integer オブジェクトに、実数の場合は Float オブジェクトに変換されます。
OptionParser::DecimalInteger: Integer オブジェクトに変換されます。10進数の整数の整数のフォーマットのみを指定できます。
OptionParser::OctalInteger: Integer オブジェクトに変換されます。"0b1"、"07"、"0xff" といった 2進数、 8進数、16進数の整数のフォーマットを指定できます。
OptionParser::DecimalNumeric: 整数の場合は Integer オブジェクトに、実数の場合は Float オブジェクトに変換されます。10進数のフォーマットを指定できます。
TrueClass: true か false に変換されます。"yes" や "no"、"true" や "false"、"+" や "-" を指定できます。オプションの引数を省略した場合は true になります。また、"no-" をオプションの先頭に付けた場合は値が反転します。
FalseClass: true か false に変換されます。TrueClass との違いはオプションの引数を省略した場合に false になります。
Array: 文字列の配列に変換されます。"," ごとに 1つの要素になります。

on(short, *rest) {|v| ...} -> self[permalink][rdoc][edit]

on(long, *rest) {|v| ...} -> self

on(short, long, *rest) {|v| ...} -> self

オプションを取り扱うためのブロックを自身に登録します。ブロックはコマンドラインのパース時に、オプションが指定されていれば呼ばれます。

コマンドに与えられた引数が配列やハッシュに含まれない場合、例外 OptionParser::InvalidArgument が OptionParser#parse 実行時に発生します。

[PARAM] short:: ショートオプションを表す文字列を指定します。
[PARAM] long:: ロングオプションを表す文字列を指定します。
[PARAM] rest:: 可能な引数を列挙した配列やハッシュを与えます。文字列を与えた場合は、サマリに表示されるオプションの説明と見なします。

例:

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][edit]

オプションを取り扱うためのブロックを自身の持つリストの最初に登録します。

[PARAM] arg:: OptionParser#on と同様です。
[PARAM] block:: OptionParser#on と同様です。

例

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][edit]

オプションを取り扱うためのブロックを自身の持つリストの最後に登録します。

--version や --help の説明をサマリの最後に表示したい時に便利です。

[PARAM] arg:: OptionParser#on と同様です。
[PARAM] block:: OptionParser#on と同様です。

例

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, into: nil) -> [String][permalink][rdoc][edit]

order(argv, into: nil) {|s| ...} -> [String]

order(*args, into: nil) -> [String]

order(*args, into: nil) {|s| ...} -> [String]

与えられた argv を順番にパースします。オプションではないコマンドの引数(下の例で言うと somefile)に出会うと、パースを中断します。 argv からオプションを取り除いたものを返します。

ブロックが与えられている場合は、パースを中断せずに引数をブロックに渡してブロックを評価し、パースを継続します。argv を返します。

下の例で言うと、コマンドの引数 somefile よりも後ろにオプションを置くことができません。-b もコマンドのオプションではない引数として扱われてしまいます。

[PARAM] argv:: パースしたい引数を文字列の配列で指定します。
[PARAM] args:: パースしたい引数を順に文字列として与えます。
[PARAM] into:: オプションを格納するハッシュを指定します。指定したハッシュにはオプションの名前をキーとして、OptionParser#onに渡されたブロックの値が格納されます。キーの名前はロングオプションが定義されていればロングオプションの値を、ショートオプションのみの場合はショートオプションの値から、先頭の "-" を除いてシンボル化した値が使用されます。
[EXCEPTION] OptionParser::ParseError:: パースに失敗した場合、発生します。実際は OptionParser::ParseError のサブクラスになります。

例:

$ 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, into: nil) -> [String][permalink][rdoc][edit]

order!(argv = self.default_argv, into: nil) {|s| ...} -> [String]

与えられた argv を順番に破壊的にパースします。 argv からオプションがすべて取り除かれます。 argv を返します。

オプションではないコマンドの引数(下の例で言うと somefile)に出会うと、パースを中断します。ブロックが与えられている場合は、パースを中断せずに引数をブロックに渡してブロックを評価し、パースを継続します。argv を返します。

下の例で言うと、コマンドの引数 somefile よりも後ろにオプションを置くことができません。 -b もコマンドのオプションではない引数として扱われてしまいます。

[PARAM] argv:: パースしたい引数を文字列の配列で指定します。
[PARAM] into:: オプションを格納するハッシュを指定します。指定したハッシュにはオプションの名前をキーとして、OptionParser#onに渡されたブロックの値が格納されます。キーの名前はロングオプションが定義されていればロングオプションの値を、ショートオプションのみの場合はショートオプションの値から、先頭の "-" を除いてシンボル化した値が使用されます。
[EXCEPTION] OptionParser::ParseError:: パースに失敗した場合、発生します。実際は OptionParser::ParseError のサブクラスになります。

例:

$ 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, into: nil) -> [String][permalink][rdoc][edit]

parse(*args, into: nil) -> [String]

与えられた argv をパースします。 argv からオプションを取り除いたものを返します。

OptionParser#permute と同様に振舞います。しかし、環境変数に POSIXLY_CORRECT が設定されている場合は、 OptionParser#order と同様に振舞います。

[PARAM] argv:: パースしたい引数を文字列の配列で指定します。
[PARAM] args:: パースしたい引数を順に文字列として与えます。
[PARAM] into:: オプションを格納するハッシュを指定します。指定したハッシュにはオプションの名前をキーとして、OptionParser#onに渡されたブロックの値が格納されます。キーの名前はロングオプションが定義されていればロングオプションの値を、ショートオプションのみの場合はショートオプションの値から、先頭の "-" を除いてシンボル化した値が使用されます。
[EXCEPTION] OptionParser::ParseError:: パースに失敗した場合、発生します。実際は OptionParser::ParseError のサブクラスになります。

例

require "optparse"

opts = OptionParser.new do |opts|
  opts.on_head("-i", "--init")
  opts.on("-u", "--update")
  opts.on_tail("-h", "--help")
end

ARGV             # => ["-i", "-u", "-h", "test"]
opts.parse(ARGV) # => ["test"]

parse!(argv = self.default_argv, into: nil) -> [String][permalink][rdoc][edit]

与えられた argv をパースします。

OptionParser#permute! と同様に argv を破壊的にパースします。環境変数に POSIXLY_CORRECT が設定されている場合は、 OptionParser#order! と同様に振舞います。

[PARAM] argv:: パースしたい引数を文字列の配列で指定します。
[PARAM] into:: オプションを格納するハッシュを指定します。指定したハッシュにはオプションの名前をキーとして、OptionParser#onに渡されたブロックの値が格納されます。キーの名前はロングオプションが定義されていればロングオプションの値を、ショートオプションのみの場合はショートオプションの値から、先頭の "-" を除いてシンボル化した値が使用されます。
[EXCEPTION] OptionParser::ParseError:: パースに失敗した場合、発生します。実際は OptionParser::ParseError のサブクラスになります。

例

require "optparse"

opts = OptionParser.new do |opts|
  opts.on_head("-i", "--init")
  opts.on("-u", "--update")
  opts.on_tail("-h", "--help")
end

ARGV              # => ["-i", "-u", "-h", "test"]
opts.parse(ARGV)  # => ["test"]
ARGV              # => ["-i", "-u", "-h", "test"]
opts.parse!(ARGV) # => ["test"]
ARGV              # => ["test"]

permute(argv, into: nil) -> [String][permalink][rdoc][edit]

permute(*args, into: nil) -> [String]

与えられた argv をパースします。オプションではないコマンドの引数(下の例で言うと somefile)があってもパースを中断しません。 argv からオプションを取り除いたものを返します。

下の例で言うと、order と違いコマンドの引数 somefile よりも後ろにオプションを置くことができます。

[PARAM] argv:: パースしたい引数を文字列の配列で指定します。
[PARAM] args:: パースしたい引数を順に文字列として与えます。
[PARAM] into:: オプションを格納するハッシュを指定します。指定したハッシュにはオプションの名前をキーとして、OptionParser#onに渡されたブロックの値が格納されます。キーの名前はロングオプションが定義されていればロングオプションの値を、ショートオプションのみの場合はショートオプションの値から、先頭の "-" を除いてシンボル化した値が使用されます。
[EXCEPTION] OptionParser::ParseError:: パースに失敗した場合、発生します。実際は OptionParser::ParseError のサブクラスになります。

例:

$ 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, into: nil) -> [String][permalink][rdoc][edit]

与えられた argv を破壊的にパースします。argv からオプションがすべて取り除かれます。オプションではないコマンドの引数(下の例で言うと somefile)があってもパースを中断しません。 argv を返します。

下の例で言うと、order と違いコマンドの引数 somefile よりも後ろにオプションを置くことができます。

[PARAM] argv:: パースしたい引数を文字列の配列で指定します。
[PARAM] into:: オプションを格納するハッシュを指定します。指定したハッシュにはオプションの名前をキーとして、OptionParser#onに渡されたブロックの値が格納されます。キーの名前はロングオプションが定義されていればロングオプションの値を、ショートオプションのみの場合はショートオプションの値から、先頭の "-" を除いてシンボル化した値が使用されます。
[EXCEPTION] OptionParser::ParseError:: パースに失敗した場合、発生します。実際は OptionParser::ParseError のサブクラスになります。

例:

$ 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][edit]

プログラムの名前を文字列で返します。

デフォルトは $0 が使われます。

[RETURN]: プログラムの名前を文字列で返します。

例

require "optparse"

OptionParser.new do |opts|
  p $0                 # => /path/to/filename.rb
  p opts.program_name  # => filename
end

program_name=(name)[permalink][rdoc][edit]

プログラムの名前を文字列で指定します。

[PARAM] name:: プログラムの名前を文字列で指定します。

例

require "optparse"

OptionParser.new do |opts|
  $0                         # => /path/to/filename.rb
  opts.program_name          # => filename
  opts.program_name = 'test' # => "test"
  opts.program_name          # => "test"
end

reject(klass) -> ()[permalink][rdoc][edit]

OptionParser#accept で登録したクラスとブロックを自身から削除します。

[PARAM] klass:: 自身から削除したいクラスを指定します。

例

require "optparse"
require "time"

def parse(option_parser)
  option_parser.on("-t", "--time [TIME]", Time) do |time|
    p time.class
  end
  option_parser.parse(ARGV)
end

opts = OptionParser.new
opts.accept(Time) do |s,|
  begin
    Time.parse(s) if s
  rescue
    raise OptionParser::InvalidArgument, s
  end
end

parse(opts) # => Time
opts.reject(Time)
parse(opts) # => unsupported argument type: Time (ArgumentError)

release -> String[permalink][rdoc][edit]

プログラムのリリースを文字列で返します。

例

require "optparse"

OptionParser.new do |opts|
  opts.release # => nil
  opts.release = "2019-05-01"
  opts.release # => "2019-05-01"
end

release=(rel)[permalink][rdoc][edit]

プログラムのリリースを文字列で指定します。

[PARAM] rel:: プログラムのリリースを文字列で指定します。

[SEE_ALSO] OptionParser#ver

separator(sep) -> ()[permalink][rdoc][edit]

サマリにオプションを区切るための文字列 sep を挿入します。オプションにいくつかの種類がある場合に、サマリがわかりやすくなります。

サマリには on メソッドを呼んだ順にオプションが表示されるので、区切りを挿入したいところでこのメソッドを呼びます。

[PARAM] sep:: サマリの区切りを文字列で指定します。

例:

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][edit]

summarize(to = [], width = self.summary_width, max = width - 1, indent= self.summary_indent) {|line| ... } -> ()

サマリを指定された to へと加えていきます。

ブロックが与えられた場合、サマリの各行を引数としてブロックを評価します。この場合、ブロックの中で明示的に to へと加えていかない限り、 to にサマリが加えられることはありません。

[PARAM] to:: サマリを出力するオブジェクトを指定します。to には << メソッドが定義されいる必要があります。
[PARAM] width:: サマリの幅を整数で指定します。
[PARAM] max:: サマリの最大幅を整数で指定します。
[PARAM] indent:: サマリのインデントを文字列で指定します。

例

require "optparse"

opts = OptionParser.new do |opts|
  opts.on_head("-i", "--init")
  opts.on("-u", "--update")
  opts.on_tail("-h", "--help")
end

opts.summarize
# => ["    -i, --init\n", "    -u, --update\n", "    -h, --help\n"]
opts.summarize(["description\n"], 10, 8, "  ")
# => ["description\n", "  -i\n", "      --init\n", "  -u\n", "      --update\n", "  -h\n", "      --help\n"]

summary_indent -> String[permalink][rdoc][edit]

サマリを表示する時のインデントを文字列で返します。

[RETURN]: サマリを表示する時のインデントを文字列で返します。

例

require "optparse"

opts = OptionParser.new do |opts|
  opts.on_head("-i", "--init")
  opts.on("-u", "--update")
  opts.on_tail("-h", "--help")
end

opts.summary_indent         # => "    "
opts.summarize
# => ["    -i, --init\n", "    -u, --update\n", "    -h, --help\n"]
opts.summary_indent = "  "
opts.summary_indent         # => "  "
opts.summarize
# => ["  -i, --init\n", "  -u, --update\n", "  -h, --help\n"]

summary_indent=(indent)[permalink][rdoc][edit]

サマリを表示する時のインデントを文字列で指定します。

[PARAM] indent:: サマリを表示する時に使われるインデントを文字列で指定します。

例

require "optparse"

opts = OptionParser.new do |opts|
  opts.on_head("-i", "--init")
  opts.on("-u", "--update")
  opts.on_tail("-h", "--help")
end

opts.summary_indent         # => "    "
opts.summarize
# => ["    -i, --init\n", "    -u, --update\n", "    -h, --help\n"]
opts.summary_indent = "  "  # => "  "
opts.summary_indent         # => "  "
opts.summarize
# => ["  -i, --init\n", "  -u, --update\n", "  -h, --help\n"]

summary_width -> Integer[permalink][rdoc][edit]

サマリを表示するときの幅を整数で返します。

[RETURN]: サマリを表示するときの幅を整数で返します。

例

require "optparse"

opts = OptionParser.new do |opts|
  opts.on_head("-i", "--init")
  opts.on("-u", "--update")
  opts.on_tail("-h", "--help")
end

opts.summary_width     # => 32
opts.summarize
# => ["    -i, --init\n", "    -u, --update\n", "    -h, --help\n"]
opts.summary_width = 8
opts.summary_width     # =>8
opts.summarize
# => ["    -i\n", "        --init\n", "    -u\n", "        --update\n", "    -h\n", "        --help\n"]

summary_width=(width)[permalink][rdoc][edit]

サマリを表示するときの幅を整数で指定します。

[PARAM] width:: サマリを表示するときの幅を整数で指定します。

例

require "optparse"

opts = OptionParser.new do |opts|
  opts.on_head("-i", "--init")
  opts.on("-u", "--update")
  opts.on_tail("-h", "--help")
end

opts.summary_width     # => 32
opts.summarize
# => ["    -i, --init\n", "    -u, --update\n", "    -h, --help\n"]
opts.summary_width = 8 # => 8
opts.summary_width     # => 8
opts.summarize
# => ["    -i\n", "        --init\n", "    -u\n", "        --update\n", "    -h\n", "        --help\n"]

to_a -> [String][permalink][rdoc][edit]

サマリの各行を要素とした配列を返します。

例

require "optparse"

opts = OptionParser.new do |opts|
  opts.on_head("-i", "--init")
  opts.on("-u", "--update")
  opts.on_tail("-h", "--help")
end

opts.to_a # => ["Usage: test [options]", "    -i, --init\n", "    -u, --update\n", "    -h, --help\n"]

ver -> String[permalink][rdoc][edit]

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][edit]

プログラムのバージョンを文字列で返します。

[RETURN]: プログラムのバージョンを文字列で返します。

[SEE_ALSO] OptionParser#ver

version=(ver)[permalink][rdoc][edit]

プログラムのバージョンを文字列で指定します。

[PARAM] ver:: プログラムのバージョンを文字列で指定します。

[SEE_ALSO] OptionParser#ver

要約

デフォルトで利用可能なオプション

目次

特異メソッド

インスタンスメソッド

デフォルトで利用可能な引数クラス