option_params - Ruby 3.3 文档

新选项的参数¶ ↑

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

本页上的代码示例使用

OptionParser#on 来定义选项。
OptionParser#parse! 来解析命令行。
内置选项 --help 来显示已定义的选项。

内容

选项名称
参数样式
参数值
- 显式参数值
  - 数组中的显式值
  - 哈希中的显式值
- 参数值模式
参数转换器
说明
选项处理程序

选项名称¶ ↑

有两种选项名称

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

短名称¶ ↑

简单短名称¶ ↑

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]

选项处理程序¶ ↑

选项的处理程序是一个可执行文件，在遇到该选项时将被调用。处理程序可能是

一个块（这是最常见的）。
一个过程。
一个方法。

处理程序块¶ ↑

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

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