新選項的參數

OptionParser 中的選項建立方法接受決定新選項行為的參數

此頁面的程式碼範例使用

內容

選項名稱

有兩種選項名稱

短名稱

簡單的短名稱

File short_simple.rb 定義兩個選項

require 'optparse'
parser = OptionParser.new
parser.on('-x', 'One short name') do |value|
  p ['-x', value]
end
parser.on('-1', '-%', 'Two short names (aliases)') do |value|
  p ['-1 or -%', value]
end
parser.parse!

執行

$ ruby short_simple.rb --help
Usage: short_simple [options]
    -x                               One short name
    -1, -%                           Two short names (aliases)
$ ruby short_simple.rb -x
["-x", true]
$ ruby short_simple.rb -1 -x -%
["-1 or -%", true]
["-x", true]
["-1 or -%", true]
有必要參數的短名稱

一個短名稱後接(沒有空白)一個虛擬字詞,定義一個需要參數的選項。

File short_required.rb 定義一個需要參數的選項 -x

require 'optparse'
parser = OptionParser.new
parser.on('-xXXX', 'Short name with required argument') do |value|
  p ['-x', value]
end
parser.parse!

執行

$ ruby short_required.rb --help
Usage: short_required [options]
    -xXXX                            Short name with required argument
$ ruby short_required.rb -x
short_required.rb:6:in `<main>': missing argument: -x (OptionParser::MissingArgument)
$ ruby short_required.rb -x FOO
["-x", "FOO"]
有可選參數的短名稱

一個短名稱後接(有空白)一個方括號中的虛擬字詞,定義一個允許可選參數的選項。

File short_optional.rb 定義一個允許可選參數的選項 -x

require 'optparse'
parser = OptionParser.new
parser.on('-x [XXX]', 'Short name with optional argument') do |value|
  p ['-x', value]
end
parser.parse!

執行

$ ruby short_optional.rb --help
Usage: short_optional [options]
    -x [XXX]                         Short name with optional argument
$ ruby short_optional.rb -x
["-x", nil]
$ ruby short_optional.rb -x FOO
["-x", "FOO"]
來自 Range 的短名稱

您可以定義一個選項,其多個短名稱取自字元範圍。剖析器會產生實際引用的字元和值。

File short_range.rb 定義一個選項,其短名稱為 !~ 的所有可列印字元

require 'optparse'
parser = OptionParser.new
parser.on('-[!-~]', 'Short names in (very large) range') do |name, value|
  p ['!-~', name, value]
end
parser.parse!

執行

$ ruby short_range.rb --help
Usage: short_range [options]
    -[!-~]                           Short names in (very large) range
$ ruby short_range.rb -!
["!-~", "!", nil]
$ ruby short_range.rb -!
["!-~", "!", nil]
$ ruby short_range.rb -A
["!-~", "A", nil]
$ ruby short_range.rb -z
["!-~", "z", nil]

長名稱

簡單的長名稱

File long_simple.rb 定義兩個選項

執行

$ ruby long_simple.rb --help
Usage: long_simple [options]
        --xxx                        One long name
        --y1%, --z2#                 Two long names (aliases)
$ ruby long_simple.rb --xxx
["--xxx", true]
$ ruby long_simple.rb --y1% --xxx --z2#
["--y1% or --z2#", true]
["--xxx", true]
["--y1% or --z2#", true]
具有必要引數的長名稱

長名稱後接(空格)一個虛擬字元,定義一個需要引數的選項。

File long_required.rb 定義一個選項 --xxx,需要一個引數。

require 'optparse'
parser = OptionParser.new
parser.on('--xxx XXX', 'Long name with required argument') do |value|
  p ['--xxx', value]
end
parser.parse!

執行

$ ruby long_required.rb --help
Usage: long_required [options]
        --xxx XXX                    Long name with required argument
$ ruby long_required.rb --xxx
long_required.rb:6:in `<main>': missing argument: --xxx (OptionParser::MissingArgument)
$ ruby long_required.rb --xxx FOO
["--xxx", "FOO"]
具有可選引數的長名稱

長名稱後接(空格)一個方括號中的虛擬字元,定義一個允許可選引數的選項。

File long_optional.rb 定義一個選項 --xxx,允許一個可選引數。

require 'optparse'
parser = OptionParser.new
parser.on('--xxx [XXX]', 'Long name with optional argument') do |value|
  p ['--xxx', value]
end
parser.parse!

執行

$ ruby long_optional.rb --help
Usage: long_optional [options]
        --xxx [XXX]                  Long name with optional argument
$ ruby long_optional.rb --xxx
["--xxx", nil]
$ ruby long_optional.rb --xxx FOO
["--xxx", "FOO"]
具有否定功能的長名稱

長名稱可以同時定義正向和負向意義。

File long_with_negation.rb 定義一個具有正負意義的選項。

require 'optparse'
parser = OptionParser.new
parser.on('--[no-]binary', 'Long name with negation') do |value|
  p [value, value.class]
end
parser.parse!

執行

$ ruby long_with_negation.rb --help
Usage: long_with_negation [options]
        --[no-]binary                Long name with negation
$ ruby long_with_negation.rb --binary
[true, TrueClass]
$ ruby long_with_negation.rb --no-binary
[false, FalseClass]

混合名稱

一個選項可以同時具有短名稱和長名稱。

File mixed_names.rb 定義一個混合的短名稱和長名稱。

require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx', 'Short and long, no argument') do |value|
  p ['--xxx', value]
end
parser.on('-yYYY', '--yyy', 'Short and long, required argument') do |value|
  p ['--yyy', value]
end
parser.on('-z [ZZZ]', '--zzz', 'Short and long, optional argument') do |value|
  p ['--zzz', value]
end
parser.parse!

執行

$ ruby mixed_names.rb --help

用法:mixed_names [選項]

  -x, --xxx                        Short and long, no argument
  -y, --yyyYYY                     Short and long, required argument
  -z, --zzz [ZZZ]                  Short and long, optional argument
$ ruby mixed_names.rb -x
["--xxx", true]
$ ruby mixed_names.rb --xxx
["--xxx", true]
$ ruby mixed_names.rb -y
mixed_names.rb:12:in `<main>': missing argument: -y (OptionParser::MissingArgument)
$ ruby mixed_names.rb -y FOO
["--yyy", "FOO"]
$ ruby mixed_names.rb --yyy
mixed_names.rb:12:in `<main>': missing argument: --yyy (OptionParser::MissingArgument)
$ ruby mixed_names.rb --yyy BAR
["--yyy", "BAR"]
$ ruby mixed_names.rb -z
["--zzz", nil]
$ ruby mixed_names.rb -z BAZ
["--zzz", "BAZ"]
$ ruby mixed_names.rb --zzz
["--zzz", nil]
$ ruby mixed_names.rb --zzz BAT
["--zzz", "BAT"]

引數關鍵字

如上所述,給定的選項名稱字串本身可以指示選項是否沒有引數、需要引數或允許可選引數。

另一種方法是使用一個單獨的符號關鍵字,它是 :NONE(預設值)、:REQUIRED:OPTIONAL 之一。

File argument_keywords.rb 定義一個需要引數的選項。

require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx', :REQUIRED, 'Required argument') do |value|
  p ['--xxx', value]
end
parser.parse!

執行

$ ruby argument_keywords.rb --help
Usage: argument_keywords [options]
    -x, --xxx                        Required argument
$ ruby argument_styles.rb --xxx
argument_styles.rb:6:in `<main>': missing argument: --xxx (OptionParser::MissingArgument)
$ ruby argument_styles.rb --xxx FOO
["--xxx", "FOO"]

引數字串

指定必要引數的另一種方法是在與名稱字串分開的字串中定義它。

File argument_strings.rb 定義一個需要引數的選項。

require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx', '=XXX', 'Required argument') do |value|
  p ['--xxx', value]
end
parser.parse!

執行

$ ruby argument_strings.rb --help
Usage: argument_strings [options]
    -x, --xxx=XXX                    Required argument
$ ruby argument_strings.rb --xxx
argument_strings.rb:9:in `<main>': missing argument: --xxx (OptionParser::MissingArgument)
$ ruby argument_strings.rb --xxx FOO
["--xxx", "FOO"]

引數值

允許的引數值可以透過指定明確值或提供給定值必須符合的模式來限制。

明確的引數值

您可以用兩種方式指定引數值

陣列 中的明確值

您可以在字串陣列中指定明確的引數值。引數值必須是那些字串之一,或是一個明確的縮寫。

檔案 explicit_array_values.rb 定義具有明確引數值的選項。

require 'optparse'
parser = OptionParser.new
parser.on('-xXXX', ['foo', 'bar'], 'Values for required argument' ) do |value|
  p ['-x', value]
end
parser.on('-y [YYY]', ['baz', 'bat'], 'Values for optional argument') do |value|
  p ['-y', value]
end
parser.parse!

執行

$ ruby explicit_array_values.rb --help
Usage: explicit_array_values [options]
    -xXXX                            Values for required argument
    -y [YYY]                         Values for optional argument
$ ruby explicit_array_values.rb -x
explicit_array_values.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument)
$ ruby explicit_array_values.rb -x foo
["-x", "foo"]
$ ruby explicit_array_values.rb -x f
["-x", "foo"]
$ ruby explicit_array_values.rb -x bar
["-x", "bar"]
$ ruby explicit_array_values.rb -y ba
explicit_array_values.rb:9:in `<main>': ambiguous argument: -y ba (OptionParser::AmbiguousArgument)
$ ruby explicit_array_values.rb -x baz
explicit_array_values.rb:9:in `<main>': invalid argument: -x baz (OptionParser::InvalidArgument)
雜湊 中的明確值

您可以在具有字串金鑰的雜湊中指定明確的引數值。傳遞的值必須是那些金鑰之一,或是一個明確的縮寫;產生的值將會是該金鑰的值。

檔案 explicit_hash_values.rb 定義具有明確引數值的選項。

require 'optparse'
parser = OptionParser.new
parser.on('-xXXX', {foo: 0, bar: 1}, 'Values for required argument' ) do |value|
  p ['-x', value]
end
parser.on('-y [YYY]', {baz: 2, bat: 3}, 'Values for optional argument') do |value|
  p ['-y', value]
end
parser.parse!

執行

$ ruby explicit_hash_values.rb --help
Usage: explicit_hash_values [options]
    -xXXX                            Values for required argument
    -y [YYY]                         Values for optional argument
$ ruby explicit_hash_values.rb -x
explicit_hash_values.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument)
$ ruby explicit_hash_values.rb -x foo
["-x", 0]
$ ruby explicit_hash_values.rb -x f
["-x", 0]
$ ruby explicit_hash_values.rb -x bar
["-x", 1]
$ ruby explicit_hash_values.rb -x baz
explicit_hash_values.rb:9:in `<main>': invalid argument: -x baz (OptionParser::InvalidArgument)
$ ruby explicit_hash_values.rb -y
["-y", nil]
$ ruby explicit_hash_values.rb -y baz
["-y", 2]
$ ruby explicit_hash_values.rb -y bat
["-y", 3]
$ ruby explicit_hash_values.rb -y ba
explicit_hash_values.rb:9:in `<main>': ambiguous argument: -y ba (OptionParser::AmbiguousArgument)
$ ruby explicit_hash_values.rb -y bam
["-y", nil]

引數值模式

您可以透過指定一個給定引數必須符合的 正規表示法 來限制允許的引數值。

檔案 matched_values.rb 定義具有符合的引數值的選項。

require 'optparse'
parser = OptionParser.new
parser.on('--xxx XXX', /foo/i, 'Matched values') do |value|
  p ['--xxx', value]
end
parser.parse!

執行

$ ruby matched_values.rb --help
Usage: matched_values [options]
        --xxx XXX                    Matched values
$ ruby matched_values.rb --xxx foo
["--xxx", "foo"]
$ ruby matched_values.rb --xxx FOO
["--xxx", "FOO"]
$ ruby matched_values.rb --xxx bar
matched_values.rb:6:in `<main>': invalid argument: --xxx bar (OptionParser::InvalidArgument)

引數轉換器

一個選項可以指定其引數要從預設的 字串 轉換為另一個類別的執行個體。

有許多內建的轉換器。您也可以定義自訂轉換器。

請參閱 引數轉換器

說明

說明參數是任何未被辨認為 選項名稱終止符 的字串參數;換句話說,它不會以連字號開頭。

您可以提供任意數量的說明參數;每個參數都會成為選項 --help 所產生的文字中的一行。

檔案 descriptions.rb 在其陣列 descriptions 中有六個字串。這些字串都作為參數傳遞給 OptionParser#on,因此它們全部逐行成為選項的說明。

require 'optparse'
parser = OptionParser.new
description = <<-EOT
Lorem ipsum dolor sit amet, consectetuer
adipiscing elit. Aenean commodo ligula eget.
Aenean massa. Cum sociis natoque penatibus
et magnis dis parturient montes, nascetur
ridiculus mus. Donec quam felis, ultricies
nec, pellentesque eu, pretium quis, sem.
EOT
descriptions = description.split($/)
parser.on('--xxx', *descriptions) do |value|
  p ['--xxx', value]
end
parser.parse!

執行

$ ruby descriptions.rb --help
Usage: descriptions [options]
        --xxx                        Lorem ipsum dolor sit amet, consectetuer
                                     adipiscing elit. Aenean commodo ligula eget.
                                     Aenean massa. Cum sociis natoque penatibus
                                     et magnis dis parturient montes, nascetur
                                     ridiculus mus. Donec quam felis, ultricies
                                     nec, pellentesque eu, pretium quis, sem.
$ ruby descriptions.rb --xxx
["--xxx", true]

選項處理常式

選項的處理常式是一個在遇到選項時將被呼叫的可執行檔。處理常式可能是

處理區塊

選項處理器可以是區塊。

File block.rb 定義具有處理器區塊的選項。

require 'optparse'
parser = OptionParser.new
parser.on('--xxx', 'Option with no argument') do |value|
  p ['Handler block for -xxx called with value:', value]
end
parser.on('--yyy YYY', 'Option with required argument') do |value|
  p ['Handler block for -yyy called with value:', value]
end
parser.parse!

執行

$ ruby block.rb --help
Usage: block [options]
        --xxx                        Option with no argument
        --yyy YYY                    Option with required argument
$ ruby block.rb --xxx
["Handler block for -xxx called with value:", true]
$ ruby block.rb --yyy FOO
["Handler block for -yyy called with value:", "FOO"]

處理程序

選項處理器可以是 Proc

File proc.rb 定義具有處理器程序的選項。

require 'optparse'
parser = OptionParser.new
parser.on(
  '--xxx',
  'Option with no argument',
  ->(value) {p ['Handler proc for -xxx called with value:', value]}
)
parser.on(
  '--yyy YYY',
  'Option with required argument',
  ->(value) {p ['Handler proc for -yyy called with value:', value]}
)
parser.parse!

執行

$ ruby proc.rb --help
Usage: proc [options]
        --xxx                        Option with no argument
        --yyy YYY                    Option with required argument
$ ruby proc.rb --xxx
["Handler proc for -xxx called with value:", true]
$ ruby proc.rb --yyy FOO
["Handler proc for -yyy called with value:", "FOO"]

處理方法

選項處理器可以是 Method

File proc.rb 定義具有處理器方法的選項。

require 'optparse'
parser = OptionParser.new
def xxx_handler(value)
  p ['Handler method for -xxx called with value:', value]
end
parser.on('--xxx', 'Option with no argument', method(:xxx_handler))
def yyy_handler(value)
  p ['Handler method for -yyy called with value:', value]
end
parser.on('--yyy YYY', 'Option with required argument', method(:yyy_handler))
parser.parse!

執行

$ ruby method.rb --help
Usage: method [options]
        --xxx                        Option with no argument
        --yyy YYY                    Option with required argument
$ ruby method.rb --xxx
["Handler method for -xxx called with value:", true]
$ ruby method.rb --yyy FOO
["Handler method for -yyy called with value:", "FOO"]