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

教程¶ ↑

为什么使用 `OptionParser`？¶ ↑

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

p ARGV

执行，带有参数和选项

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

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

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

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

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

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

内容¶ ↑

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

首先¶ ↑

要使用 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。

给定的参数确定新选项的特征。这些可能包括

一个或多个短选项名称。
一个或多个长选项名称。
选项是否不带参数、带可选参数或带必需参数。
参数的可接受形式。
参数的可接受值。
当解析器遇到选项时要调用的过程或方法。
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.

程序名称包含在默认横幅中：用法：#{program_name} [选项]；您可以更改程序名称。

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 有六个用于解析的实例方法。

三个名称以“感叹号”（!）结尾

parse!
order!
permute!

这些方法中的每一个

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

其他三个方法的名称不以“感叹号”结尾

parse
order
permute

这些方法中的每一个

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

方法`parse!`¶ ↑

方法 parse!

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

该方法从argv[0]开始处理argv中的元素，默认情况下，在末尾结束。

否则，当

找到终止符参数--时，处理结束；返回前会删除终止符参数。
环境变量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。