新选项参数¶ ↑

OptionParser 中创建选项的方法接受确定新选项行为的参数

• OptionParser#on

• OptionParser#on_head

• OptionParser#on_tail

• OptionParser#define

• OptionParser#define_head

• OptionParser#define_tail

• OptionParser#make_switch

本页的代码示例使用

• OptionParser#on，来定义选项。

• OptionParser#parse!，来解析命令行。

• 内置选项 --help，来显示已定义的选项。

内容

• 选项名称

  • 短名称

    • 简单短名称

    • 带必需参数的短名称

    • 带可选参数的短名称

    • 来自范围的短名称

  • 长名称

    • 简单长名称

    • 带必需参数的长名称

    • 带可选参数的长名称

    • 带否定语的长名称

  • 混合名称

• 参数样式

• 参数值

  • 显式参数值

    • 数组中的显式值

    • 哈希中的显式值

  • 参数值模式

• 参数转换器

• 描述

• 选项处理程序

  • 处理程序块

  • 处理程序 Proc

  • 处理程序方法

选项名称¶ ↑

选项名称有两种

• 短选项名称，由一个连字符和一个字符组成。

• 长选项名称，由两个连字符和一个或多个字符组成。

短名称¶ ↑

简单短名称¶ ↑

File short_simple.rb 定义了两个选项

• 一个短名称为 -x。

• 另一个有两个短名称，实际上是别名，-1 和 -%。

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 定义了两个选项

• 一个带有长名称 -xxx。

• 另一个带有两个长名称，实际上是别名，--y1% 和 --z2#。

  require ‘optparse’ parser = OptionParser.new parser.on(‘–xxx’, ‘一个长名称’) do |value|

  p ['--xxx', value]
  

  end parser.on(‘–y1%’, ‘–z2#’, ‘两个长名称（别名）’) do |value|

  p ['--y1% or --z2#', value]
  

  end parser.parse!

执行

$ 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"]

参数值¶ ↑

可以通过指定显式值或提供给定值必须匹配的模式来限制允许的参数值。

显式参数值¶ ↑

您可以通过以下两种方式之一指定参数值

• 将值指定为字符串数组。

• 将值指定为哈希表。

数组中的显式值 Array¶ ↑

您可以在字符串数组中指定显式参数值。参数值必须是这些字符串之一，或是不含歧义的缩写。

File 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)

哈希中的显式值 Hash¶ ↑

您可以在具有字符串键的哈希中指定显式参数值。传递的值必须是这些键之一，或是不含歧义的缩写；产生的值将是该键的值。

File 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]

参数值模式¶ ↑

您可以通过指定给定参数必须匹配的 Regexp 来限制允许的参数值。

File 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)

参数转换器¶ ↑

选项可以指定其参数将从默认的 String 转换为另一个类的实例。

有一些内置的转换器。您也可以定义自定义转换器。

参见 参数转换器.

描述¶ ↑

描述参数是任何不被识别为 选项名称 或 终止符 的字符串参数；换句话说，它不以连字符开头。

您可以给出任意数量的描述参数；每个参数都成为选项 --help 生成的文本中的一行。

File 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]

选项处理程序¶ ↑

选项的处理程序是一个可执行文件，当遇到选项时将调用它。处理程序可以是

• 一个块（这最常被看到）。

• 一个 proc。

• 一个方法。

处理程序块¶ ↑

选项处理程序可以是一个块。

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¶ ↑

选项处理程序可以是 Proc。

File proc.rb 定义了一个具有处理程序 proc 的选项。

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"]