教程 - 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 中從 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 未定義）完全相同的結果。