use Getopt::Long; $result = GetOptions (...optionsbeschreibungen...);
GetOptions(). Diese Funktion orientiert sich an der POSIX-Syntax für Kommandozeilen-Optionen mit GNU-Erweiterungen. Generell bedeutet das, daß die Optionen lange Namen anstelle einzelner Buchstaben verwenden und daß die Optionen durch zwei Bindestriche ("--") eingeleitet werden. Das Bündeln von Kommandozeilen-Optionen, wie es bei dem auf einem Buchstaben basierenden, traditionellen Ansatz üblich war, wird zwar unterstützt, ist standardmäßig aber nicht aktiv. Beispielsweise kann man dem UNIX-Befehl "ps" die "Option"
-vax
in der Kommandozeile übergeben, was für die Kombination der Einzeloptionen -v, -a und -x steht. Mit der neuen Syntax wäre --vax eine einzelne Option, die wahrscheinlich eine Computerarchitektur andeutet.
Kommandozeilen-Optionen können genutzt werden, um Werte einzustellen. Diese Werte können auf zwei verschiedene Arten angegeben werden:
--size 24 --size=24
GetOptions wird mit einer Liste von Optionsbeschreibungen aufgerufen, von denen jede aus zwei Elementen besteht: dem Options-Bezeichner ("option specifier") und der Optionsverknüpfung ("option linkage"). Der Options-Bezeichner definiert den Namen der Option und kann optional den Wert festlegen, den die Option annehmen kann. Die Optionsverknüpfung ist üblicherweise eine Referenz auf eine Variable, die gesetzt wird, wenn die Option verwendet wird. Zum Beispiel akzeptiert der folgende Aufruf von GetOptions
GetOptions("size=i" => \$offset);
eine Kommandozeilen-Option namens "size", die einen Integerwert besitzen muß. Mit der Kommandozeile "--size 24" wird die Variable $offset auf den Wert 24 gesetzt.
Alternativ dazu kann das erste GetOptions-Argument eine Referenz auf einen HASH sein, der die Verknüpfung der Optionen beschreibt. Es ist auch möglich, ein Objekt zu verwenden, wenn dessen Klasse auf einem HASH basiert. Der folgende Aufruf ist mit dem obigen Beispiel identisch:
%optctl = ("size" => \$offset);
GetOptions(\%optctl, "size=i");
Verknüpfungen können mit einer oder auch mit beiden oben beschriebenen Methoden angegeben werden. Die in der Argumentliste definierten Verknüpfungen haben dabei Vorrang vor den im HASH angegebenen Verknüpfungen.
Die Kommandozeilen-Optionen werden aus dem Array @ARGV entnommen. Nach Beendigung von GetOptions enthält @ARGV den Rest (d.h. die sogenannten "non-options" oder "Nicht-Optionen")
der Kommandozeile. Jeder Options-Bezeichner legt den Namen der Option fest, auf den optional ein Argument-Bezeichner folgen kann.
Optionen ohne Argumente besitzen keinen Argument-Bezeichner. Die Optionsvariable wird auf 1 gesetzt, wenn die Option verwendet wird.
Für die anderen Optionen sind die Werte für Argument-Bezeichner wie folgt:
Der Bezeichner + wird ignoriert, wenn es sich beim Optionsziel nicht um einen SKALAR handelt.
Zwei für sich stehende Bindestriche (--) signalisieren das Ende der Optionsliste.
%optctl = (); GetOptions (\%optctl, "size=i");
der Zuweisung
$optctl{"size"} = 24;
Bei Array-Optionen wird eine Referenz auf das Array verwendet:
%optctl = (); GetOptions (\%optctl, "sizes=i@");
Mit der Kommandozeile "-sizes 24 -sizes 48" entspricht das der Zuweisung
$optctl{"sizes"} = [24, 48];
Bei Hash-Optionen (Optionen, deren Argumente die Form "name=wert" haben) wird eine Referenz auf einen Hash verwendet:
%optctl = (); GetOptions (\%optctl, "define=s%");
Mit der Kommandozeile "--define foo=hallo --define bar=welt" entspricht das der Zuweisung
$optctl{"define"} = {foo=>'hallo', bar=>'welt')
Wird keine explizite Verknüpfung angegeben und wird keine Referenz auf einen HASH übergeben, legt GetOptions den Wert in einer globalen Variablen ab, die nach der Option benannt wird und der ein "opt_" vorangestellt wird. Um eine verwendbare Perl-Variable zu erzeugen, werden Zeichen, die nicht Teil der Variablensyntax sind, in Unterstriche umgewandelt. Beispielsweise setzt "--fpp-struct-return" die Variable $opt_fpp_struct_return. Beachten Sie, daß diese Variable im Namensraum des aufrufenden Programms liegt, nicht notwendigerweise in main. Beispielsweise entspricht
GetOptions ("size=i", "sizes=i@");
mit der Kommandozeile "-size 10 -sizes 24 -sizes 48" den folgenden Zuweisungen:
$opt_size = 10; @opt_sizes = (24, 48);
Ein für sich stehender Bindestrich (-) wird als Option betrachtet, der zugehörige Perl-Bezeichner lautet $opt_ .
Der Verknüpfungs-Bezeichner kann eine Referenz auf einen Skalar, eine Referenz auf ein Array, eine Referenz auf einen Hash oder eine Referenz auf eine Unterroutine sein.
Beachten Sie, daß es - wenn Ihr Code mit dem empfohlenen Pragma use strict 'vars' ausgeführt wird - hilfreich sein kann, diese Paketvariablen über use vars zu deklarieren, etwa so:
use vars qw/ $opt_size @opt_sizes $opt_bar /;
Wird ein REF SCALAR angegeben, wird der neue Wert in der referenzierten Variablen abgelegt. Tritt die Option wiederholt auf, wird der vorherige Wert überschrieben.
Wird ein REF ARRAY angegeben, wird der neue Wert an das referenzierte Array angehängt ("gepusht").
Wird ein REF HASH angegeben, muß der Optionswert die Form "schlüssel" oder "schlüssel=wert" besitzen. (Lassen Sie den "=wert"-Teil weg, wird der Wert 1 angenommen.) In diesem Fall wird dem Element des referenzierten Hashes mit dem Schlüssel "schlüssel" der Wert "wert" zugewiesen.
Wird ein REF CODE angegeben, erfolgt der Aufruf der referenzierten Unterroutine mit zwei Argumenten: dem Optionsnamen und dem Optionswert. Der Optionsname ist dabei immer der richtige Name, kein Alias und keine Abkürzung.
Optionsnamen können, abhängig von der Konfigurations-Option auto_abbrev, abgekürzt werden, wobei die Eindeutigkeit entsprechend zu beachten ist.
Beachten Sie auch die Beispiele.
Bei mit "--" eingeleiteten Optionen kann ein Argument angehängt sein, das durch ein "=" getrennt ist, z.B. "--foo=bar".
die() signalisiert und terminieren das aufrufende Programm, wenn Getopt::Long::GetOptions() nicht in eval { ... } eingebettet wurde bzw. wenn die() nicht mit Hilfe von $SIG{__DIE__} abgefangen wurde.
Der Rückgabewert 1 (wahr) zeigt die erfolgreiche Ausführung an.
Der Rückgabewert 0 (falsch) zeigt an, daß die Funktion einen oder mehrere Fehler bei der Verarbeitung der Optionen erkannt hat. Diese Fehler werden mit warn() signalisiert und können mit $SIG{__WARN__} abgefangen werden.
Fehler, die eigentlich nicht auftreten können, werden mit Carp::croak() signalisiert.
Wird ein "@"-Zeichen an den Argument-Bezeichner angehängt, wird die Option als Array betrachtet. Wert(e) werden nicht gesetzt, sondern in das Array @opt_name "gepusht". Bei einer expliziten Verknüpfung muß hier eine Referenz auf ein ARRAY verwendet werden.
Wird ein "%"-Zeichen an den Argument-Bezeichner angehängt, wird die Option als Hash betrachtet. Wert(e) der Form "name=wert" werden abgelegt, indem das Element mit dem Schlüssel "name" des Hashes %opt_name auf den entsprechenden "wert" gesetzt wird. (Fehlt der "=wert"-Teil, wird das Element standardmäßig auf 1 gesetzt.) Bei einer expliziten Verknüpfung muß hier eine Referenz auf einen HASH verwendet werden.
Ist die Konfigurations-Option getopt_compat gesetzt (siehe hierzu den Abschnitt "KONFIGURATIONS-OPTIONEN"), können mit "+" oder "-" beginnende Optionen auch ihre Argumente enthalten, z.B. "+foo=bar". Diese Möglichkeit dient der Kompatibilität mit älteren Implementierungen der GNU-"getopt"-Routine.
Besteht das erste Argument für GetOptions aus einem String, der nur nicht-alphanumerische Zeichen enthält, wird er verwendet, um die Zeichen festzulegen, mit denen Optionen eingeleitet werden. Alles, was mit einem dieser Zeichen beginnt, wird als Option betrachtet. Die Verwendung eines solchen Einleitungsarguments ist veraltet.
Der Bequemlichkeit halber dürfen Options-Bezeichner mit - oder -- beginnen, d.h., die folgende Schreibweise ist möglich:
GetOptions qw(-foo=s --bar=i --ar=s);
-eins -zwei -> $opt_eins = '', -zwei ist nächste Option -eins -2 -> $opt_eins = -2
Sehen wir uns auch mal die Bezeichner "foo=s" und "bar:s" an:
-bar -xxx -> $opt_bar = '', '-xxx' ist nächste Option -foo -bar -> $opt_foo = '-bar' -foo -- -> $opt_foo = '--'
Beim GNU- bzw. POSIX-Format können Optionsnamen und -werte kombiniert werden:
+foo=blech -> $opt_foo = 'blech' --bar= -> $opt_bar = '' --bar=-- -> $opt_bar = '--'
Ein Beispiel für die Verwendung von Variablenreferenzen:
$ret = GetOptions ('foo=s', \$foo, 'bar=i', 'ar=s', \@ar);
Mit den Kommandozeilen-Optionen "-foo blech -bar 24 -ar xx -ar yy" führt dies zu:
$foo = 'blech'
$opt_bar = 24
@ar = ('xx','yy')
Ein Beispiel für die Verwendung des Options-Bezeichners <>:
@ARGV = qw(-foo 1 bar -foo 2 blech);
GetOptions("foo=i", \$myfoo, "<>", \&mysub);
Ergebnisse:
mysub("bar") wird aufgerufen (mit $myfoo auf 1 gesetzt)
mysub("blech") wird aufgerufen (mit $myfoo auf 2 gesetzt)
Vergleichen Sie das mit:
@ARGV = qw(-foo 1 bar -foo 2 blech);
GetOptions("foo=i", \$myfoo);
Hierbei bleiben die Nicht-Optionen in @ARGV:
$myfoo -> 2 @ARGV -> qw(bar blech)
Vorangegangene Versionen von Getopt::Long haben zu Konfigurationszwecken auf Variablen zurückgegriffen. Obwohl die Nutzung dieser Variablen immer noch funktioniert, wird die Verwendung der neuen config-Routine stark gefördert. Ganz nebenbei gesagt, ist diese auch wesentlich einfacher.
Die folgenden Optionen sind verfügbar:
Siehe auch permute als das Gegenstück zu require_order.
Ist permute gesetzt, dann ist
-foo arg1 -bar arg2 arg3
identisch mit
-foo -bar arg1 arg2 arg3
Wird eine Callback-Routine für Nicht-Optionen festgelegt, ist @ARGV nach der erfolgreichen Rückkehr aus GetOptions leer, weil alle Optionen verarbeitet wurden. Die Ausnahme bildet hierbei die Verwendung von --:
-foo arg1 -bar arg2 -- arg3
In diesem Beispiel wird die Callback-Routine für arg1 und arg2 aufgerufen und dann abgebrochen, was arg2 in @ARGV hinterläßt.
Ist require_order gesetzt, wird die Verarbeitung abgebrochen, sobald die erste Nicht-Option erkannt wird.
-foo arg1 -bar arg2 arg3
entspricht also
-foo -- arg1 -bar arg2 arg3
ps -vax --vax
gleichbedeutend mit
ps -v -a -x --vax
vorausgesetzt natürlich, daß "vax", "v", "a" und "x" als gültige Optionen definiert wurden.
Gebündelte Optionen können auch einen Wert enthalten. Bei Strings bildet der Rest der Bündelung den Wert, Integer- und Fließkommawerte können aber auch vorkommen:
scale -h24w80
entspricht also
scale -h 24 -w 80
Hinweis: Das Zurücksetzen von bundling setzt auch bundling_override zurück.
Hinweis: Das Zurücksetzen von bundling_override setzt auch bundling zurück.
Hinweis: Die Verwendung der Optionsbündelung kann sehr leicht zu unerwarteten Ergebnissen führen, besonders wenn lange Optionen und Bündelungen gemischt werden.
Hinweis: Das Zurücksetzen von ignore_case setzt auch ignore_case_always zurück.
Hinweis: Das Zurücksetzen von ignore_case_always setzt auch ignore_case zurück.
@ARGV durchgereicht, statt als Fehler markiert zu werden. Das macht die Entwicklung von Wrapper-Skripten möglich, die nur einen Teil der vom Benutzer übergebenen Optionen verarbeiten und die restlichen Optionen an andere Programme übergeben.
Das kann sehr verwirrend sein, insbesondere wenn permute ebenfalls gesetzt ist.
(--|-|\+), es sei denn, die Umgebungsvariable POSIXLY_CORRECT ist gesetzt. In diesem Fall wird (--|-) verwendet.
major.minor. Dies kann beispielsweise verwendet werden, um die Version vom Exporter prüfen zu lassen.
use Getopt::Long 3.00;
Die einzelnen Komponenten können Sie mit $Getopt::Long::major_version und $Getopt::Long::minor_version untersuchen.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
If you do not have a copy of the GNU General Public License write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.