教程 - RDoc 文档 - Ruby 编程语言

教程¶ ↑

为什么使用 `OptionParser`？¶ ↑

当 Ruby 程序执行时，它会将命令行参数和选项捕获到变量 ARGV 中。这个简单的程序只是打印它的 ARGV

p ARGV

执行，带参数和选项

$ ruby argv.rb foo --bar --baz bat bam
["foo", "--bar", "--baz", "bat", "bam"]

执行程序负责解析和处理命令行选项。

OptionParser 提供了用于解析和处理这些选项的方法。

使用 OptionParser，您可以定义选项，以便每个选项

定义选项的代码和处理该选项的代码位于同一位置。
选项可以不带参数、带必需参数或带可选参数。
参数可以自动转换为指定的类。
参数可以限制为指定的形式。
参数可以限制为指定的值。

该类还具有方法 help，它显示自动生成的帮助文本。

内容¶ ↑

开始
定义选项
选项名称
选项参数
参数值
- 显式参数值
  - 数组中的显式值
  - 哈希表中的显式值
- 参数值模式
关键字参数到
参数转换器
帮助
顶部列表和基本列表
定义选项的方法
解析

入门¶ ↑

要使用 OptionParser

需要 OptionParser 代码。
创建一个 OptionParser 对象。
定义一个或多个选项。
解析命令行。

File basic.rb 定义了三个选项，-x、-y 和 -z，每个选项都有一个描述性字符串，每个选项都有一个代码块。

# Require the OptionParser code.
require 'optparse'
# Create an OptionParser object.
parser = OptionParser.new
# Define one or more options.
parser.on('-x', 'Whether to X') do |value|
  p ['x', value]
end
parser.on('-y', 'Whether to Y') do |value|
  p ['y', value]
end
parser.on('-z', 'Whether to Z') do |value|
  p ['z', value]
end
# Parse the command line and return pared-down ARGV.
p parser.parse!

从这些定义的选项中，解析器自动构建帮助文本

$ ruby basic.rb --help
Usage: basic [options]
    -x                               Whether to X
    -y                               Whether to Y
    -z                               Whether to Z

在解析过程中找到选项时，将调用为该选项定义的代码块，并传入参数值。无效选项将引发异常。

Method parse!，在本教程中使用最频繁，它从 ARGV 中删除它找到的选项和参数，将其他非选项参数留给程序自行处理。该方法返回可能已缩减的 ARGV 数组。

执行

$ ruby basic.rb -x -z
["x", true]
["z", true]
[]
$ ruby basic.rb -z -y -x
["z", true]
["y", true]
["x", true]
[]
$ ruby basic.rb -x input_file.txt output_file.txt
["x", true]
["input_file.txt", "output_file.txt"]
$ ruby basic.rb -a
basic.rb:16:in `<main>': invalid option: -a (OptionParser::InvalidOption)

定义选项¶ ↑

在 OptionParser 中定义选项的常用方法是使用实例方法 OptionParser#on。

该方法可以接受任意数量的参数（顺序无关），并且还可以带有一个可选的尾部关键字参数 into。

给定的参数决定了新选项的特性。这些特性可能包括

一个或多个短选项名称。
一个或多个长选项名称。
选项是否不带参数、带可选参数或带必填参数。
参数的形式。
参数的值。
解析器遇到选项时要调用的 proc 或方法。
String 选项描述。

选项名称¶ ↑

您可以为选项指定一个或多个两种类型的名称

短（1 个字符）名称，以一个连字符 (-) 开头。
长（多个字符）名称，以两个连字符 (--) 开头。

短选项名称¶ ↑

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

File short_names.rb 定义了一个带短名称 -x 的选项，以及一个带两个短名称（实际上是别名）-y 和 -z 的选项。

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

执行

$ ruby short_names.rb --help
Usage: short_names [options]
    -x                               Short name
    -1, -%                           Two short names
$ ruby short_names.rb -x
["x", true]
$ ruby short_names.rb -1
["-1 or -%", true]
$ ruby short_names.rb -%
["-1 or -%", true]

多个短名称可以“共享”一个连字符

$ ruby short_names.rb -x1%
["x", true]
["-1 or -%", true]
["-1 or -%", true]

长选项名称¶ ↑

长选项名称由两个连字符和一个或多个字符（通常是两个或多个字符）组成。

File long_names.rb 定义了一个带长名称 --xxx 的选项，以及一个带两个长名称（实际上是别名）--y1% 和 --z2# 的选项。

require 'optparse'
parser = OptionParser.new
parser.on('--xxx', 'Long name') do |value|
  p ['-xxx', value]
end
parser.on('--y1%', '--z2#', "Two long names") do |value|
  p ['--y1% or --z2#', value]
end
parser.parse!

执行

$ ruby long_names.rb --help
Usage: long_names [options]
        --xxx                        Long name
        --y1%, --z2#                 Two long names
$ ruby long_names.rb --xxx
["-xxx", true]
$ ruby long_names.rb --y1%
["--y1% or --z2#", true]
$ ruby long_names.rb --z2#
["--y1% or --z2#", true]

长名称可以定义为正向和负向两种形式。

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
Usage: mixed_names [options]
    -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"]

选项名称缩写¶ ↑

默认情况下，命令行上允许使用缩写的选项名称。如果缩写名称在所有缩写选项名称中是唯一的，则该缩写名称有效。

require 'optparse'
parser = OptionParser.new
parser.on('-n', '--dry-run',) do |value|
  p ['--dry-run', value]
end
parser.on('-d', '--draft',) do |value|
  p ['--draft', value]
end
parser.parse!

执行

$ ruby name_abbrev.rb --help
Usage: name_abbrev [options]
    -n, --dry-run
    -d, --draft
$ ruby name_abbrev.rb -n
["--dry-run", true]
$ ruby name_abbrev.rb --dry-run
["--dry-run", true]
$ ruby name_abbrev.rb -d
["--draft", true]
$ ruby name_abbrev.rb --draft
["--draft", true]
$ ruby name_abbrev.rb --d
name_abbrev.rb:9:in `<main>': ambiguous option: --d (OptionParser::AmbiguousOption)
$ ruby name_abbrev.rb --dr
name_abbrev.rb:9:in `<main>': ambiguous option: --dr (OptionParser::AmbiguousOption)
$ ruby name_abbrev.rb --dry
["--dry-run", true]
$ ruby name_abbrev.rb --dra
["--draft", true]

您可以使用 require_exact 方法禁用缩写。

require 'optparse'
parser = OptionParser.new
parser.on('-n', '--dry-run',) do |value|
  p ['--dry-run', value]
end
parser.on('-d', '--draft',) do |value|
  p ['--draft', value]
end
parser.require_exact = true
parser.parse!

执行

$ ruby no_abbreviation.rb --dry-ru
no_abbreviation.rb:10:in `<main>': invalid option: --dry-ru (OptionParser::InvalidOption)
$ ruby no_abbreviation.rb --dry-run
["--dry-run", true]

选项参数¶ ↑

选项可以不带参数、带必填参数或带可选参数。

无参数选项¶ ↑

以上所有示例都定义了无参数选项。

带必填参数的选项¶ ↑

通过在选项名称定义中添加一个虚拟词来指定必填参数。

File required_argument.rb 定义了两个选项；每个选项都有一个必填参数，因为名称定义后面有一个虚拟词。

require 'optparse'
parser = OptionParser.new
parser.on('-x XXX', '--xxx', 'Required argument via short name') do |value|
  p ['--xxx', value]
end
parser.on('-y', '--y YYY', 'Required argument via long name') do |value|
  p ['--yyy', value]
end
parser.parse!

找到选项时，会生成给定的参数。

执行

$ ruby required_argument.rb --help
Usage: required_argument [options]
    -x, --xxx XXX                    Required argument via short name
    -y, --y YYY                      Required argument via long name
$ ruby required_argument.rb -x AAA
["--xxx", "AAA"]
$ ruby required_argument.rb -y BBB
["--yyy", "BBB"]

省略必填参数会引发错误。

$ ruby required_argument.rb -x
required_argument.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument)

带可选参数的选项¶ ↑

通过在选项名称定义中添加一个用方括号括起来的虚拟词来指定可选参数。

File optional_argument.rb 定义了两个选项；每个选项都有一个可选参数，因为名称定义后面有一个用方括号括起来的虚拟词。

require 'optparse'
parser = OptionParser.new
parser.on('-x [XXX]', '--xxx', 'Optional argument via short  name') do |value|
  p ['--xxx', value]
end
parser.on('-y', '--yyy [YYY]', 'Optional argument via long name') do |value|
  p ['--yyy', value]
end
parser.parse!

找到带参数的选项时，会生成给定的参数。

执行

$ ruby optional_argument.rb --help
Usage: optional_argument [options]
    -x, --xxx [XXX]                  Optional argument via short  name
    -y, --yyy [YYY]                  Optional argument via long name
$ ruby optional_argument.rb -x AAA
["--xxx", "AAA"]
$ ruby optional_argument.rb -y BBB
["--yyy", "BBB"]

省略可选参数不会引发错误。

参数值¶ ↑

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

显式参数值¶ ↑

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

在字符串数组中指定值。
在哈希中指定值。

在 `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)

关键字参数 `into`¶ ↑

在解析选项时，您可以添加关键字选项 into，并使用类似哈希的论据；每个解析的选项将被添加为名称/值对。

这对于以下情况很有用：

收集选项。
检查缺少的选项。
为选项提供默认值。

收集选项¶ ↑

使用关键字参数 into 来收集选项。

require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx', 'Short and long, no argument')
parser.on('-yYYY', '--yyy', 'Short and long, required argument')
parser.on('-z [ZZZ]', '--zzz', 'Short and long, optional argument')
options = {}
parser.parse!(into: options)
p options

执行

$ ruby collected_options.rb --help
Usage: into [options]
    -x, --xxx                        Short and long, no argument
    -y, --yyyYYY                     Short and long, required argument
    -z, --zzz [ZZZ]                  Short and long, optional argument
$ ruby collected_options.rb --xxx
{:xxx=>true}
$ ruby collected_options.rb --xxx --yyy FOO
{:xxx=>true, :yyy=>"FOO"}
$ ruby collected_options.rb --xxx --yyy FOO --zzz Bar
{:xxx=>true, :yyy=>"FOO", :zzz=>"Bar"}
$ ruby collected_options.rb --xxx --yyy FOO --yyy BAR
{:xxx=>true, :yyy=>"BAR"}

请注意，在最后一次执行中，选项 --yyy 的参数值被覆盖了。

检查缺少的选项¶ ↑

使用收集的选项来检查缺少的选项。

require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx', 'Short and long, no argument')
parser.on('-yYYY', '--yyy', 'Short and long, required argument')
parser.on('-z [ZZZ]', '--zzz', 'Short and long, optional argument')
options = {}
parser.parse!(into: options)
required_options = [:xxx, :zzz]
missing_options = required_options - options.keys
unless missing_options.empty?
  fail "Missing required options: #{missing_options}"
end

执行

$ ruby missing_options.rb --help
Usage: missing_options [options]
    -x, --xxx                        Short and long, no argument
    -y, --yyyYYY                     Short and long, required argument
    -z, --zzz [ZZZ]                  Short and long, optional argument
$ ruby missing_options.rb --yyy FOO
missing_options.rb:11:in `<main>': Missing required options: [:xxx, :zzz] (RuntimeError)

选项的默认值¶ ↑

初始化 into 参数以定义选项的默认值。

require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx', 'Short and long, no argument')
parser.on('-yYYY', '--yyy', 'Short and long, required argument')
parser.on('-z [ZZZ]', '--zzz', 'Short and long, optional argument')
options = {yyy: 'AAA', zzz: 'BBB'}
parser.parse!(into: options)
p options

执行

$ ruby default_values.rb --help
Usage: default_values [options]
    -x, --xxx                        Short and long, no argument
    -y, --yyyYYY                     Short and long, required argument
    -z, --zzz [ZZZ]                  Short and long, optional argument
$ ruby default_values.rb --yyy FOO
{:yyy=>"FOO", :zzz=>"BBB"}

参数转换器¶ ↑

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

示例：File date.rb 定义了一个选项，其参数将被转换为 Date 对象。参数通过方法 Date#parse 进行转换。

require 'optparse/date'
parser = OptionParser.new
parser.on('--date=DATE', Date) do |value|
  p [value, value.class]
end
parser.parse!

执行

$ ruby date.rb --date 2001-02-03
[#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
$ ruby date.rb --date 20010203
[#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
$ ruby date.rb --date "3rd Feb 2001"
[#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]

您也可以定义自定义转换器。有关内置和自定义转换器的详细信息，请参阅参数转换器。

帮助¶ ↑

OptionParser 提供了自动生成的帮助文本。

帮助文本包括：

横幅，显示用法。
选项的短名称和长名称。
选项的虚拟参数名称。
选项的描述。

示例代码

require 'optparse'
parser = OptionParser.new
parser.on(
  '-x', '--xxx',
  'Adipiscing elit. Aenean commodo ligula eget.',
  'Aenean massa. Cum sociis natoque penatibus',
  )
parser.on(
  '-y', '--yyy YYY',
  'Lorem ipsum dolor sit amet, consectetuer.'
)
parser.on(
  '-z', '--zzz [ZZZ]',
  'Et magnis dis parturient montes, nascetur',
  'ridiculus mus. Donec quam felis, ultricies',
  'nec, pellentesque eu, pretium quis, sem.',
  )
parser.parse!

选项名称和虚拟参数名称的定义如上所述。

选项描述由不是选项名称本身的字符串组成；一个选项可以有多个描述字符串。执行

Usage: help [options]
    -x, --xxx                        Adipiscing elit. Aenean commodo ligula eget.
                                     Aenean massa. Cum sociis natoque penatibus
    -y, --yyy YYY                    Lorem ipsum dolor sit amet, consectetuer.
    -z, --zzz [ZZZ]                  Et magnis dis parturient montes, nascetur
                                     ridiculus mus. Donec quam felis, ultricies
                                     nec, pellentesque eu, pretium quis, sem.

程序名称包含在默认横幅中：Usage: #{program_name} [options]；您可以更改程序名称。

require 'optparse'
parser = OptionParser.new
parser.program_name = 'help_program_name.rb'
parser.parse!

执行

$ ruby help_program_name.rb --help
Usage: help_program_name.rb [options]

您也可以更改整个横幅。

require 'optparse'
parser = OptionParser.new
parser.banner = "Usage: ruby help_banner.rb"
parser.parse!

执行

$ ruby help_banner.rb --help
Usage: ruby help_banner.rb

默认情况下，选项名称缩进 4 个空格，选项名称字段的宽度为 32 个空格。

您可以通过将参数传递给 OptionParser.new 来更改这些值以及横幅。

require 'optparse'
parser = OptionParser.new(
  'ruby help_format.rb [options]', # Banner
  20,                               # Width of options field
  ' ' * 2                               # Indentation
)
parser.on(
  '-x', '--xxx',
  'Adipiscing elit. Aenean commodo ligula eget.',
  'Aenean massa. Cum sociis natoque penatibus',
  )
parser.on(
  '-y', '--yyy YYY',
  'Lorem ipsum dolor sit amet, consectetuer.'
)
parser.on(
  '-z', '--zzz [ZZZ]',
  'Et magnis dis parturient montes, nascetur',
  'ridiculus mus. Donec quam felis, ultricies',
  'nec, pellentesque eu, pretium quis, sem.',
  )
parser.parse!

执行

$ ruby help_format.rb --help
ruby help_format.rb [options]
  -x, --xxx            Adipiscing elit. Aenean commodo ligula eget.
                       Aenean massa. Cum sociis natoque penatibus
  -y, --yyy YYY        Lorem ipsum dolor sit amet, consectetuer.
  -z, --zzz [ZZZ]      Et magnis dis parturient montes, nascetur
                       ridiculus mus. Donec quam felis, ultricies
                       nec, pellentesque eu, pretium quis, sem.

顶部列表和基本列表¶ ↑

一个 OptionParser 对象维护一个 OptionParser::List 对象的堆栈，每个对象都包含零个或多个选项的集合。您不太可能需要添加或删除该堆栈。

堆栈包括

由 OptionParser#top 给出的顶部列表。
由 OptionParser#base 给出的基本列表。

当 OptionParser 构建其帮助文本时，顶部列表中的选项位于基本列表中的选项之前。

定义选项的方法¶ ↑

定义选项的方法允许您创建选项，并将选项追加/预先追加到顶部列表或追加到基本列表。

接下来的三个方法中的每一个都接受一系列参数参数和一个块，使用方法 OptionParser#make_switch 创建一个选项对象（见下文），并返回创建的选项

方法 OptionParser#define 将创建的选项追加到顶部列表。
方法 OptionParser#define_head 将创建的选项预先追加到顶部列表。
方法 OptionParser#define_tail 将创建的选项追加到基本列表。

接下来的三个方法与上面的三个方法相同，除了它们的返回值

方法 OptionParser#on 与方法 OptionParser#define 相同，只是它返回解析器对象 self。
方法 OptionParser#on_head 与方法 OptionParser#define_head 相同，只是它返回解析器对象 self。
方法 OptionParser#on_tail 与方法 OptionParser#define_tail 相同，只是它返回解析器对象 self。

虽然您可能永远不需要直接调用它，但这是定义选项的核心方法

方法 OptionParser#make_switch 接受一个参数数组和一个块。见新选项的参数。此方法与这里其他方法不同，因为它
- 接受一个参数数组；其他方法接受一个参数参数序列。
- 返回一个包含创建的选项对象、选项名称和其他值的数组；其他方法返回创建的选项对象或解析器对象 self。

解析¶ ↑

OptionParser 有六个用于解析的实例方法。

三个方法的名称以“bang”（!）结尾

parse!
order!
permute!

这些方法中的每一个

接受一个可选的字符串数组参数 argv；如果没有给出，argv 默认为 OptionParser#default_argv 的值，其初始值为 ARGV。
接受一个可选的关键字参数 into（参见关键字参数 into）。
返回 argv，可能删除了一些元素。

另外三种方法的名称不以“bang”结尾

parse
order
permute

这些方法中的每一个

接受一个字符串数组参数或零个或多个字符串参数。
接受一个可选的关键字参数 into 及其值 into。（参见关键字参数 into）。
返回 argv，可能删除了一些元素。

方法 `parse!`¶ ↑

方法 parse!

接受一个可选的字符串数组参数 argv；如果没有给出，argv 默认为 OptionParser#default_argv 的值，其初始值为 ARGV。
接受一个可选的关键字参数 into（参见关键字参数 into）。
返回 argv，可能删除了一些元素。

该方法处理 argv 中从 argv[0] 开始的元素，默认情况下，处理到最后。

否则，处理结束，方法返回时

找到终止符参数 --；终止符参数在返回之前被删除。
定义了环境变量 POSIXLY_CORRECT 并且找到了非选项参数；非选项参数不会被删除。请注意，该变量的值并不重要，因为只检查其是否存在。

File parse_bang.rb

require 'optparse'
parser = OptionParser.new
parser.on('--xxx') do |value|
  p ['--xxx', value]
end
parser.on('--yyy YYY') do |value|
  p ['--yyy', value]
end
parser.on('--zzz [ZZZ]') do |value|
  p ['--zzz', value]
end
ret = parser.parse!
puts "Returned: #{ret} (#{ret.class})"

帮助

$ ruby parse_bang.rb --help
Usage: parse_bang [options]
        --xxx
        --yyy YYY
        --zzz [ZZZ]

默认行为

$ ruby parse_bang.rb input_file.txt output_file.txt --xxx --yyy FOO --zzz BAR
["--xxx", true]
["--yyy", "FOO"]
["--zzz", "BAR"]
Returned: ["input_file.txt", "output_file.txt"] (Array)

由终止符参数结束的处理

$ ruby parse_bang.rb input_file.txt output_file.txt --xxx --yyy FOO -- --zzz BAR
["--xxx", true]
["--yyy", "FOO"]
Returned: ["input_file.txt", "output_file.txt", "--zzz", "BAR"] (Array)

当定义了 POSIXLY_CORRECT 时，由非选项参数结束的处理

$ POSIXLY_CORRECT=true ruby parse_bang.rb --xxx input_file.txt output_file.txt -yyy FOO
["--xxx", true]
Returned: ["input_file.txt", "output_file.txt", "-yyy", "FOO"] (Array)

方法 `parse`¶ ↑

方法 parse

接受一个字符串数组参数或零个或多个字符串参数。
接受一个可选的关键字参数 into 及其值 into。（参见关键字参数 into）。
返回 argv，可能删除了一些元素。

如果给定一个数组 ary，该方法将数组 argv 形成为 ary.dup。如果给定零个或多个字符串参数，这些参数将被形成为数组 argv。

该方法调用

parse!(argv, into: into)

请注意，环境变量 POSIXLY_CORRECT 和终止符参数 -- 会被遵守。

File parse.rb

require 'optparse'
parser = OptionParser.new
parser.on('--xxx') do |value|
  p ['--xxx', value]
end
parser.on('--yyy YYY') do |value|
  p ['--yyy', value]
end
parser.on('--zzz [ZZZ]') do |value|
  p ['--zzz', value]
end
ret = parser.parse(ARGV)
puts "Returned: #{ret} (#{ret.class})"

帮助

$ ruby parse.rb --help
Usage: parse [options]
        --xxx
        --yyy YYY
        --zzz [ZZZ]

默认行为

$ ruby parse.rb input_file.txt output_file.txt --xxx --yyy FOO --zzz BAR
["--xxx", true]
["--yyy", "FOO"]
["--zzz", "BAR"]
Returned: ["input_file.txt", "output_file.txt"] (Array)

由终止符参数结束的处理

$ ruby parse.rb input_file.txt output_file.txt --xxx --yyy FOO -- --zzz BAR
["--xxx", true]
["--yyy", "FOO"]
Returned: ["input_file.txt", "output_file.txt", "--zzz", "BAR"] (Array)

当定义了 POSIXLY_CORRECT 时，由非选项参数结束的处理

$ POSIXLY_CORRECT=true ruby parse.rb --xxx input_file.txt output_file.txt -yyy FOO
["--xxx", true]
Returned: ["input_file.txt", "output_file.txt", "-yyy", "FOO"] (Array)

方法 `order!`¶ ↑

调用方法 OptionParser#order! 与调用方法 OptionParser#parse! 并定义环境变量 POSIXLY_CORRECT 的结果完全相同。

方法 `order`¶ ↑

调用方法 OptionParser#order 与调用方法 OptionParser#parse 并定义环境变量 POSIXLY_CORRECT 的结果完全相同。

方法 `permute!`¶ ↑

调用方法 OptionParser#permute! 与调用方法 OptionParser#parse! 并且没有定义环境变量 POSIXLY_CORRECT 的结果完全相同。

方法 `permute`¶ ↑

调用方法 OptionParser#permute 的结果与调用方法 OptionParser#parse 时环境变量 POSIXLY_CORRECT 未定义的结果完全相同。