option_params - Dokumentation für Ruby 4.0

Parameter für neue Optionen

Option-erstellende Methoden in OptionParser akzeptieren Argumente, die das Verhalten einer neuen Option bestimmen.

Die Codebeispiele auf dieser Seite verwenden

OptionParser#on, um Optionen zu definieren.
OptionParser#parse!, um die Befehlszeile zu parsen.
Eingebaute Option --help, um definierte Optionen anzuzeigen.

Inhalt

Optionsnamen
Argument-Strings
Argumentwerte
- Explizite Argumentwerte
  - Explizite Werte im Array
  - Explizite Werte im Hash
- Argumentwertmuster
Argumentkonverter
Beschreibungen
Options-Handler

Optionsnamen

Es gibt zwei Arten von Optionsnamen

Kurzer Optionsname, bestehend aus einem einzelnen Bindestrich und einem einzelnen Zeichen.
Langer Optionsname, bestehend aus zwei Bindestrichen und einem oder mehreren Zeichen.

Kurznamen

Einfache Kurznamen

File short_simple.rb definiert zwei Optionen

Eine mit dem Kurznamen -x.
Die andere mit zwei Kurznamen, effektiv Aliase, -1 und -%.

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!

Ausführungen

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

Kurznamen mit erforderlichen Argumenten

Ein Kurzname gefolgt (kein Leerzeichen) von einem Dummy-Wort definiert eine Option, die ein Argument erfordert.

File short_required.rb definiert eine Option -x, die ein Argument erfordert.

require 'optparse'
parser = OptionParser.new
parser.on('-xXXX', 'Short name with required argument') do |value|
  p ['-x', value]
end
parser.parse!

Ausführungen

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

Kurznamen mit optionalen Argumenten

Ein Kurzname gefolgt (mit Leerzeichen) von einem Dummy-Wort in eckigen Klammern definiert eine Option, die ein optionales Argument zulässt.

File short_optional.rb definiert eine Option -x, die ein optionales Argument zulässt.

require 'optparse'
parser = OptionParser.new
parser.on('-x [XXX]', 'Short name with optional argument') do |value|
  p ['-x', value]
end
parser.parse!

Ausführungen

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

Kurznamen aus `Range`

Sie können eine Option mit mehreren Kurznamen aus einem Zeichenbereich definieren. Der Parser übergibt sowohl das tatsächliche zitierte Zeichen als auch den Wert.

File short_range.rb definiert eine Option mit Kurznamen für alle druckbaren Zeichen von ! bis ~

require 'optparse'
parser = OptionParser.new
parser.on('-[!-~]', 'Short names in (very large) range') do |name, value|
  p ['!-~', name, value]
end
parser.parse!

Ausführungen

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

Langnamen

Einfache Langnamen

File long_simple.rb definiert zwei Optionen

Eine mit dem Langnamen -xxx.
Die andere mit zwei Langnamen, effektiv Aliase, --y1% und --z2#.

require ‘optparse’ parser = OptionParser.new parser.on(‘–xxx’, ‘Ein Langname’) do |value|
```
p ['--xxx', value]
```
end parser.on(‘–y1%’, ‘–z2#’, ‘Zwei Langnamen (Aliase)’) do |value|
```
p ['--y1% or --z2#', value]
```
end parser.parse!

Ausführungen

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

Langnamen mit erforderlichen Argumenten

Ein Langname gefolgt (mit Leerzeichen) von einem Dummy-Wort definiert eine Option, die ein Argument erfordert.

File long_required.rb definiert eine Option --xxx, die ein Argument erfordert.

require 'optparse'
parser = OptionParser.new
parser.on('--xxx XXX', 'Long name with required argument') do |value|
  p ['--xxx', value]
end
parser.parse!

Ausführungen

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

Langnamen mit optionalen Argumenten

Ein Langname gefolgt (mit Leerzeichen) von einem Dummy-Wort in eckigen Klammern definiert eine Option, die ein optionales Argument zulässt.

File long_optional.rb definiert eine Option --xxx, die ein optionales Argument zulässt.

require 'optparse'
parser = OptionParser.new
parser.on('--xxx [XXX]', 'Long name with optional argument') do |value|
  p ['--xxx', value]
end
parser.parse!

Ausführungen

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

Langnamen mit Negation

Ein Langname kann mit positiven und negativen Bedeutungen definiert werden.

File long_with_negation.rb definiert eine Option, die beide Bedeutungen hat.

require 'optparse'
parser = OptionParser.new
parser.on('--[no-]binary', 'Long name with negation') do |value|
  p [value, value.class]
end
parser.parse!

Ausführungen

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

Gemischte Namen

Eine Option kann sowohl Kurz- als auch Langnamen haben.

File mixed_names.rb definiert eine Mischung aus Kurz- und Langnamen.

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!

Ausführungen

$ ruby mixed_names.rb --help

Nutzung: mixed_names [optionen]

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

Argument-Schlüsselwörter

Wie oben gesehen, kann ein gegebener Optionsname-String selbst angeben, ob die Option kein Argument, ein erforderliches Argument oder ein optionales Argument hat.

Eine Alternative ist die Verwendung eines separaten Symbolschlüsselworts, das eines der folgenden ist: :NONE (Standard), :REQUIRED, :OPTIONAL.

File argument_keywords.rb definiert eine Option mit einem erforderlichen Argument.

require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx', :REQUIRED, 'Required argument') do |value|
  p ['--xxx', value]
end
parser.parse!

Ausführungen

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

Argument-Strings

Noch eine Möglichkeit, ein erforderliches Argument anzugeben, ist die Definition in einem String, der vom Namen-String getrennt ist.

File argument_strings.rb definiert eine Option mit einem erforderlichen Argument.

require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx', '=XXX', 'Required argument') do |value|
  p ['--xxx', value]
end
parser.parse!

Ausführungen

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

Argumentwerte

Zulässige Argumentwerte können eingeschränkt werden, entweder durch Angabe expliziter Werte oder durch Bereitstellung eines Musters, das der gegebene Wert erfüllen muss.

Explizite Argumentwerte

Sie können Argumentwerte auf zwei Arten angeben

Werte als Array von Strings angeben.
Werte als Hash angeben.

Explizite Werte im `Array`

Sie können explizite Argumentwerte in einem Array von Strings angeben. Der Argumentwert muss einer dieser Strings oder eine eindeutige Abkürzung sein.

File explicit_array_values.rb definiert Optionen mit expliziten Argumentwerten.

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!

Ausführungen

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

Sie können explizite Argumentwerte in einem Hash mit String-Schlüsseln angeben. Der übergebene Wert muss einer dieser Schlüssel oder eine eindeutige Abkürzung sein; der übergebene Wert wird der Wert für diesen Schlüssel sein.

File explicit_hash_values.rb definiert Optionen mit expliziten Argumentwerten.

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!

Ausführungen

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

Argumentwertmuster

Sie können zulässige Argumentwerte einschränken, indem Sie einen Regexp angeben, den der gegebene Argument erfüllen muss, oder einen Range oder ein Array, in dem der konvertierte Wert enthalten sein muss.

File matched_values.rb definiert Optionen mit übereinstimmenden Argumentwerten.

require 'optparse'
parser = OptionParser.new
parser.on('--xxx XXX', /foo/i, 'Matched values') do |value|
  p ['--xxx', value]
end
parser.on('--yyy YYY', Integer, 'Check by range', 1..3) do |value|
  p ['--yyy', value]
end
parser.on('--zzz ZZZ', Integer, 'Check by list', [1, 3, 4]) do |value|
  p ['--zzz', value]
end
parser.parse!

Ausführungen

$ ruby matched_values.rb --help
Usage: matched_values [options]
        --xxx XXX                    Matched values
        --yyy YYY                    Check by range
        --zzz ZZZ                    Check by list
$ 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:12:in '<main>': invalid argument: --xxx bar (OptionParser::InvalidArgument)
$ ruby matched_values.rb --yyy 1
["--yyy", 1]
$ ruby matched_values.rb --yyy 4
matched_values.rb:12:in '<main>': invalid argument: --yyy 4 (OptionParser::InvalidArgument)
$ ruby matched_values.rb --zzz 1
["--zzz", 1]
$ ruby matched_values.rb --zzz 2
matched_values.rb:12:in '<main>': invalid argument: --zzz 2 (OptionParser::InvalidArgument)

Argumentkonverter

Eine Option kann angeben, dass ihr Argument vom Standard String in eine Instanz einer anderen Klasse konvertiert werden soll.

Es gibt eine Reihe von eingebauten Konvertern. Sie können auch benutzerdefinierte Konverter definieren.

Siehe Argument Konverter.

Beschreibungen

Ein Beschreibungs-Parameter ist jeder String-Parameter, der nicht als Optionsname oder Terminator erkannt wird; mit anderen Worten, er beginnt nicht mit einem Bindestrich.

Sie können beliebig viele Beschreibungs-Parameter angeben; jeder wird zu einer Zeile im von der Option --help generierten Text.

File descriptions.rb hat sechs Strings in seinem Array descriptions. Diese werden alle als Parameter an OptionParser#on übergeben, sodass sie alle zeilenweise zur Beschreibung der Option werden.

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!

Ausführungen

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

Options-Handler

Der Handler für eine Option ist eine ausführbare Einheit, die aufgerufen wird, wenn die Option angetroffen wird. Der Handler kann sein

Ein Block (dies ist am häufigsten zu sehen).
Ein Proc.
Eine Methode.

Handler-Blöcke

Ein Options-Handler kann ein Block sein.

File block.rb definiert eine Option, die einen Handler-Block hat.

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!

Ausführungen

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

Handler-Procs

Ein Options-Handler kann ein Proc sein.

File proc.rb definiert eine Option, die einen Handler-Proc hat.

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!

Ausführungen

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

Handler-Methoden

Ein Options-Handler kann eine Methode sein.

File proc.rb definiert eine Option, die eine Handler-Methode hat.

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!

Ausführungen

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