tutorial

Warum ?`OptionParser`?

Wenn ein Ruby-Programm ausgeführt wird, werden seine Kommandozeilenargumente und -optionen in der Variablen ARGV erfasst. Dieses einfache Programm gibt nur seine ARGV aus.

p ARGV

Ausführung mit Argumenten und Optionen

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

Das ausführende Programm ist für das Parsen und Verarbeiten der Kommandozeilenoptionen zuständig.

OptionParser bietet Methoden zum Parsen und Verarbeiten dieser Optionen.

Mit OptionParser können Sie Optionen so definieren, dass für jede Option

Der Code, der die Option definiert, und der Code, der diese Option verarbeitet, am selben Ort sind.
Die Option kann kein Argument, ein erforderliches Argument oder ein optionales Argument nehmen.
Das Argument kann automatisch in eine angegebene Klasse konvertiert werden.
Das Argument kann auf angegebene Formen beschränkt werden.
Das Argument kann auf angegebene Werte beschränkt werden.

Die Klasse hat auch eine Methode `help`, die automatisch generierten Hilfetext anzeigt.

Inhalt

Zu Beginn
Optionen definieren
Optionsnamen
Optionenargumente
Argumentwerte
- Explizite Argumentwerte
  - Explizite Werte im Array
  - Explizite Werte in der Hash
- Muster für Argumentwerte
Schlüsselwortargument into
Argumentkonverter
Hilfe
Oberste Liste und Basisliste
Methoden zum Definieren von Optionen
Parsen

Zu Beginn

Um OptionParser zu verwenden

Fordern Sie den OptionParser-Code an.
Erstellen Sie ein OptionParser-Objekt.
Definieren Sie eine oder mehrere Optionen.
Parsen Sie die Kommandozeile.

File basic.rb definiert drei Optionen: -x, -y und -z, jeweils mit einer beschreibenden Zeichenkette und einem Block.

# 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!

Aus diesen definierten Optionen baut der Parser automatisch einen Hilfetext

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

Wenn eine Option während des Parsens gefunden wird, wird der für die Option definierte Block mit dem Argumentwert aufgerufen. Eine ungültige Option löst eine Ausnahme aus.

Die Methode `parse!`, die in diesem Tutorial am häufigsten verwendet wird, entfernt die gefundenen Optionen und Argumente aus ARGV und überlässt andere Nicht-Optionsargumente dem Programm zur eigenständigen Verarbeitung. Die Methode gibt das möglicherweise reduzierte ARGV-Array zurück.

Ausführungen

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

Optionen definieren

Eine übliche Methode zum Definieren einer Option in OptionParser ist die Instanzmethode OptionParser#on.

Die Methode kann mit beliebig vielen Argumenten (deren Reihenfolge keine Rolle spielt) aufgerufen werden und kann auch ein optionales nachgestelltes Schlüsselwortargument into haben.

Die übergebenen Argumente bestimmen die Eigenschaften der neuen Option. Diese können umfassen

Einer oder mehrere kurze Optionsnamen.
Einer oder mehrere lange Optionsnamen.
Ob die Option kein Argument, ein optionales Argument oder ein erforderliches Argument nimmt.
Akzeptable Formen für das Argument.
Akzeptable Werte für das Argument.
Ein Proc oder eine Methode, die aufgerufen werden soll, wenn der Parser auf die Option stößt.
String-Beschreibungen für die Option.

Optionsnamen

Sie können einer Option einen oder mehrere Namen von zwei Arten geben

Kurzer (1-Zeichen) Name, beginnend mit einem Bindestrich (-).
Langer (mehrere Zeichen) Name, beginnend mit zwei Bindestrichen (--).

Kurze Optionsnamen

Ein kurzer Optionsname besteht aus einem Bindestrich und einem einzelnen Zeichen.

File short_names.rb definiert eine Option mit einem kurzen Namen, -x, und eine Option mit zwei kurzen Namen (effektiv Aliase) -y und -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!

Ausführungen

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

Mehrere kurze Namen können sich einen Bindestrich "teilen"

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

Lange Optionsnamen

Ein langer Optionsname besteht aus zwei Bindestrichen und einem oder mehreren Zeichen (normalerweise zwei oder mehr Zeichen).

File long_names.rb definiert eine Option mit einem langen Namen, --xxx, und eine Option mit zwei langen Namen (effektiv Aliase) --y1% und --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!

Ausführungen

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

Ein langer Name kann mit positiver und negativer Bedeutung 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]

Optionsnamen mischen

Viele Entwickler mischen gerne kurze und lange Optionsnamen, sodass ein kurzer Name effektiv eine Abkürzung für einen langen Namen ist.

File mixed_names.rb definiert Optionen, die jeweils sowohl einen kurzen als auch einen langen Namen haben.

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

Abkürzungen von Optionsnamen

Standardmäßig sind abgekürzte Optionsnamen auf der Kommandozeile erlaubt. Ein abgekürzter Name ist gültig, wenn er unter den abgekürzten Optionsnamen eindeutig ist.

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!

Ausführungen

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

Sie können Abkürzungen mit der Methode require_exact deaktivieren.

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!

Ausführungen

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

Optionenargumente

Eine Option kann kein Argument, ein erforderliches Argument oder ein optionales Argument nehmen.

Option ohne Argument

Alle obigen Beispiele definieren Optionen ohne Argument.

Option mit erforderlichem Argument

Geben Sie für eine Option ein erforderliches Argument an, indem Sie ein Dummy-Wort zu ihrer Namensdefinition hinzufügen.

File required_argument.rb definiert zwei Optionen; jede hat ein erforderliches Argument, da die Namensdefinition ein folgendes Dummy-Wort hat.

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!

Wenn eine Option gefunden wird, wird das angegebene Argument übergeben.

Ausführungen

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

Das Weglassen eines erforderlichen Arguments löst einen Fehler aus

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

Option mit optionalem Argument

Geben Sie für eine Option ein optionales Argument an, indem Sie ein Dummy-Wort in eckigen Klammern zu ihrer Namensdefinition hinzufügen.

File optional_argument.rb definiert zwei Optionen; jede hat ein optionales Argument, da die Namensdefinition ein folgendes Dummy-Wort in eckigen Klammern hat.

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!

Wenn eine Option mit einem Argument gefunden wird, wird das angegebene Argument übergeben.

Ausführungen

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

Das Weglassen eines optionalen Arguments löst keinen Fehler aus.

Argumentabkürzungen

Geben Sie eine Argumentliste als Array oder Hash an.

require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx=VALUE', %w[ABC def], 'Argument abbreviations') do |value|
  p ['--xxx', value]
end
parser.on('-y', '--yyy=VALUE', {"abc"=>"XYZ", def: "FOO"}, 'Argument abbreviations') do |value|
  p ['--yyy', value]
end
parser.parse!

Wenn ein Argument abgekürzt ist, wird das erweiterte Argument übergeben.

Ausführungen

$ ruby argument_abbreviation.rb --help
Usage: argument_abbreviation [options]
Usage: argument_abbreviation [options]
    -x, --xxx=VALUE                  Argument abbreviations
    -y, --yyy=VALUE                  Argument abbreviations
$ ruby argument_abbreviation.rb --xxx A
["--xxx", "ABC"]
$ ruby argument_abbreviation.rb --xxx c
argument_abbreviation.rb:9:in '<main>': invalid argument: --xxx c (OptionParser::InvalidArgument)
$ ruby argument_abbreviation.rb --yyy a --yyy d
["--yyy", "XYZ"]
["--yyy", "FOO"]

Argumentwerte

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

Explizite Argumentwerte

Sie können Argumentwerte auf eine von zwei Arten angeben

Werte als Array von Zeichenketten angeben.
Werte als Hash angeben.

Explizite Werte im `Array`

Sie können explizite Argumentwerte in einem Array von Zeichenketten angeben. Der Argumentwert muss eine dieser Zeichenketten 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)

Explizite Werte in der `Hash`

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

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]

Muster für Argumentwerte

Sie können zulässige Argumentwerte einschränken, indem Sie einen Regexp angeben, der dem gegebenen Argument entsprechen muss.

File matched_values.rb definiert Optionen mit passenden 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
$ 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)

Schlüsselwortargument `into`

Beim Parsen von Optionen können Sie das Schlüsselwortargument into mit einem Hash-ähnlichen Argument hinzufügen; jede geparste Option wird als Name/Wert-Paar hinzugefügt.

Dies ist nützlich für

Optionen sammeln.
Fehlende Optionen prüfen.
Standardwerte für Optionen bereitstellen.

Optionen sammeln

Verwenden Sie das Schlüsselwortargument into, um Optionen zu sammeln.

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

Ausführungen

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

Beachten Sie in der letzten Ausführung, dass der Argumentwert für die Option --yyy überschrieben wurde.

Fehlende Optionen prüfen

Verwenden Sie die gesammelten Optionen, um fehlende Optionen zu prüfen.

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

Ausführungen

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

Standardwerte für Optionen

Initialisieren Sie das into-Argument, um Standardwerte für Optionen zu definieren.

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

Ausführungen

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

Argumentkonverter

Eine Option kann angeben, dass ihr Argument von der Standard-String in eine Instanz einer anderen Klasse konvertiert werden soll. Es gibt eine Reihe von integrierten Konvertern.

Beispiel: File date.rb definiert eine Option, deren Argument in ein Date-Objekt konvertiert werden soll. Das Argument wird von der Methode Date#parse konvertiert.

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

Ausführungen

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

Sie können auch benutzerdefinierte Konverter definieren. Siehe Argument Converters für integrierte und benutzerdefinierte Konverter.

Hilfe

OptionParser stellt automatisch generierten Hilfetext zur Verfügung.

Der Hilfetext besteht aus

Ein Banner, der die Verwendung zeigt.
Optionen, kurze und lange Namen.
Dummy-Argumentnamen für Optionen.
Optionenbeschreibungen.

Beispielcode

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!

Die Optionsnamen und Dummy-Argumentnamen werden wie oben beschrieben definiert.

Die Optionsbeschreibung besteht aus den Zeichenketten, die nicht selbst Optionsnamen sind; eine Option kann mehr als eine Beschreibungszeichenkette haben. Ausführung

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.

Der Programmname ist im Standardbanner enthalten: Usage: #{program_name} [options]; Sie können den Programmnamen ändern.

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

Ausführung

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

Sie können auch das gesamte Banner ändern.

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

Ausführung

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

Standardmäßig sind die Optionsnamen mit 4 Leerzeichen eingerückt und die Breite des Feldes für Optionsnamen beträgt 32 Leerzeichen.

Sie können diese Werte zusammen mit dem Banner ändern, indem Sie Parameter an OptionParser.new übergeben.

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!

Ausführung

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

Oberste Liste und Basisliste

Ein OptionParser-Objekt verwaltet einen Stapel von OptionParser::List-Objekten, von denen jedes eine Sammlung von null oder mehr Optionen hat. Es ist unwahrscheinlich, dass Sie etwas von diesem Stapel hinzufügen oder entfernen müssen.

Der Stapel enthält

Die oberste Liste, bereitgestellt von OptionParser#top.
Die Basisliste, bereitgestellt von OptionParser#base.

Wenn OptionParser seinen Hilfetext erstellt, gehen die Optionen in der obersten Liste denen in der Basisliste voraus.

Methoden zum Definieren von Optionen

Methoden zur Optionsdefinition ermöglichen es Ihnen, eine Option zu erstellen und sie auch zur obersten Liste hinzuzufügen/voranzustellen oder sie zur Basisliste hinzuzufügen.

Jede der folgenden drei Methoden akzeptiert eine Sequenz von Parameterargumenten und einen Block, erstellt ein Options-Objekt mit der Methode OptionParser#make_switch (siehe unten) und gibt die erstellte Option zurück

Die Methode OptionParser#define fügt die erstellte Option zur obersten Liste hinzu.
Die Methode OptionParser#define_head stellt die erstellte Option vor die oberste Liste.
Die Methode OptionParser#define_tail fügt die erstellte Option zur Basisliste hinzu.

Diese nächsten drei Methoden sind identisch mit den drei oben genannten, mit Ausnahme ihrer Rückgabewerte

Die Methode OptionParser#on ist identisch mit der Methode OptionParser#define, außer dass sie das Parser-Objekt self zurückgibt.
Die Methode OptionParser#on_head ist identisch mit der Methode OptionParser#define_head, außer dass sie das Parser-Objekt self zurückgibt.
Die Methode OptionParser#on_tail ist identisch mit der Methode OptionParser#define_tail, außer dass sie das Parser-Objekt self zurückgibt.

Obwohl Sie sie möglicherweise nie direkt aufrufen müssen, ist hier die Kernmethode zur Definition einer Option

Die Methode OptionParser#make_switch akzeptiert ein Array von Parametern und einen Block. Siehe Parameters for New Options. Diese Methode unterscheidet sich von anderen hier insofern, als sie
- Akzeptiert ein Array von Parametern; andere akzeptieren eine Sequenz von Parameterargumenten.
- Gibt ein Array zurück, das das erstellte Options-Objekt, die Optionsnamen und andere Werte enthält; andere geben entweder das erstellte Options-Objekt oder das Parser-Objekt self zurück.

Parsen

OptionParser hat sechs Instanzmethoden zum Parsen.

Drei haben Namen, die mit einem "Bang" (!) enden

parse!
order!
permute!

Jede dieser Methoden

Akzeptiert ein optionales Array von String-Argumenten argv; wenn es nicht angegeben wird, wird argv dem Wert von OptionParser#default_argv zugewiesen, dessen anfänglicher Wert ARGV ist.
Akzeptiert ein optionales Schlüsselwortargument into (siehe Keyword Argument into).
Gibt argv zurück, möglicherweise mit einigen entfernten Elementen.

Die drei anderen Methoden haben Namen, die nicht mit einem "Bang" enden

parse
order
permute

Jede dieser Methoden

Akzeptiert ein Array von String-Argumenten oder null oder mehr String-Argumente.
Akzeptiert ein optionales Schlüsselwortargument into und seinen Wert into. (siehe Keyword Argument into).
Gibt argv zurück, möglicherweise mit einigen entfernten Elementen.

Methode `parse!`

Methode parse!

Akzeptiert ein optionales Array von String-Argumenten argv; wenn es nicht angegeben wird, wird argv dem Wert von OptionParser#default_argv zugewiesen, dessen anfänglicher Wert ARGV ist.
Akzeptiert ein optionales Schlüsselwortargument into (siehe Keyword Argument into).
Gibt argv zurück, möglicherweise mit einigen entfernten Elementen.

Die Methode verarbeitet die Elemente in argv ab argv[0] bis zum Ende, standardmäßig.

Andernfalls endet die Verarbeitung und die Methode gibt zurück, wenn

Das Terminator-Argument -- gefunden wird; das Terminator-Argument wird vor der Rückgabe entfernt.
Die Umgebungsvariable POSIXLY_CORRECT definiert ist und ein Nicht-Optionsargument gefunden wird; das Nicht-Optionsargument wird nicht entfernt. Beachten Sie, dass der Wert dieser Variablen keine Rolle spielt, da nur ihre Existenz geprüft wird.

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})"

Hilfe

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

Standardverhalten

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

Verarbeitung durch Terminator-Argument beendet

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

Verarbeitung durch Nicht-Option beendet, wenn POSIXLY_CORRECT definiert ist

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

Methode `parse`

Methode parse

Akzeptiert ein Array von String-Argumenten oder null oder mehr String-Argumente.
Akzeptiert ein optionales Schlüsselwortargument into und seinen Wert into. (siehe Keyword Argument into).
Gibt argv zurück, möglicherweise mit einigen entfernten Elementen.

Wenn ein Array ary übergeben wird, bildet die Methode das Array argv als ary.dup. Wenn null oder mehr String-Argumente übergeben werden, werden diese Argumente zu einem Array argv geformt.

Die Methode ruft auf

parse!(argv, into: into)

Beachten Sie, dass die Umgebungsvariable POSIXLY_CORRECT und das Terminator-Argument -- berücksichtigt werden.

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})"

Hilfe

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

Standardverhalten

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

Verarbeitung durch Terminator-Argument beendet

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

Verarbeitung durch Nicht-Option beendet, wenn POSIXLY_CORRECT definiert ist

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

Tutorial

Warum ?`OptionParser`?

Inhalt

Zu Beginn

Optionen definieren

Optionsnamen

Kurze Optionsnamen

Lange Optionsnamen

Optionsnamen mischen

Abkürzungen von Optionsnamen

Optionenargumente

Option ohne Argument

Option mit erforderlichem Argument

Option mit optionalem Argument

Argumentabkürzungen

Argumentwerte

Explizite Argumentwerte

Explizite Werte im `Array`

Explizite Werte in der `Hash`

Muster für Argumentwerte

Schlüsselwortargument `into`

Optionen sammeln

Fehlende Optionen prüfen

Standardwerte für Optionen

Argumentkonverter

Hilfe

Oberste Liste und Basisliste

Methoden zum Definieren von Optionen

Parsen

Methode `parse!`

Methode `parse`

Methode `order!`

Methode `order`

Methode `permute!`

Methode `permute`

Warum ?OptionParser?

Warum ?`OptionParser`?