instance method OptionParser#on

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

ショートオプションとロングオプションを同時に登録することもできます。

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("-xSTRING"){|val| ...} # スペース無しで任意の文字列を入れても同様

オプションの引数が必須でない場合は [ ] をつけて、

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

となります。

[PARAM] long:

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

  on("--long"){|boolean| ...}  # オプションが引数をとらない場合。boolean には true が渡されます。
  on("--long MANDATORY"){|val| ...} # オプションが引数をとる場合。" MANDATORY" の部分は任意の文字列で構いません
  on("--long=MANDATORY"){|val| ...} # 空白のかわりに = を使って指定することもできます
  # on("--longSTRING"){|val| ...} # ロングオプションでは、ショートオプションの場合と違って空白が必ず必要です。このようにすると --longSTRING という名前の引数をとらないオプションになります。
  on("--long [OPTIONAL]"){|val| ...}  # 引数が必須でないオプション

と指定できます。

[PARAM] desc:

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

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

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:

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

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

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つの要素になります。

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

コマンドに与えられた引数が配列やハッシュに含まれない場合、例外 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"