use Herbaer::Readargs; my $args = { "[cnt]verbose" => 1, "param" => "auto", "name" => [], "option" => undef, "[sr]help" => /help, }; sub help { print_message_with_values ('param ${param}', $args); exit 0; }; read_args ($args);
Das Perl-Modul Herbaer::Readargs
bietet die Funktionen
In der Voreinstellung werden die Funktionen read_args
und print_message_with_values
exportiert.
read_args
($args
, $argv
)$argv
Der Parameter $argv
kann ein Array von Zeichenketten referenzieren. In diesem Fall werden die Einträge des referenzierten Arrays statt der Befehlszeilen-Argumente @ARGV
verarbeitet. Andernfalls wird $argv
als Referenz auf @ARGV
initialisiert.
$args
Der Parameter $args
ist eine HASH-Referenz; wenn nicht, dann endet das Unterprogramm sofort. Die Schlüssel und vorbelegten Werte bestimmen die erlaubten Argumente. Die Funktion trägt die tatsächlichen Werte aus den Aufruf-Argumenten in den HASH ein.
Die Schlüssel des HASH haben die Form [
oder TYPE
]NAME
NAME
. TYPE
bezeichnet den Typ eines Arguments. NAME
steht für eine Folge von Buchstaben, Ziffern oder dem Unterstrich ("_
"). Der Name der Option ergibt sich, indem zwei Minus-Zeichen vorangestellt werden: --
.NAME
[cnt]NAME
Der Wert zu dem Schlüssel ist ein Zähler (nicht-negative ganze Zahl). Jede Option --
erhöht den Zähler um eins oder setzt den Wert auf eins, falls er noch nicht definiert ist. Jede Option NAME
--no_
setzt den Zähler auf den Wert null.NAME
Eine typische Anwendung ist der Schlüssel [cnt]verbose
. Der Wert steuert üblicherweise den Umfang der Ausgabe an STDERR.
[sr]NAME
Der voreingestellte Wert zu diesem Schlüssel muß ein Unterprogramm referenzieren. Die Option --
führt zum Aufruf des Unterprogramms mit den Parametern NAME
$args
und $argv
.
Typische Anwendungen sind die Schlüssel [sr]help
(Option --help
) und [sr]version
(Option --version
).
[rc]NAME
Das Argument --
dient dazu, weitere Daten aus einer Datei zu lesen. Das folgende Argument NAME
FILE
bestimmt die Datei. Es wird die Funktion
aufgerufen.read_data_file
("FILE
", $args, "[rc]
")NAME
Alle anderen Schlüssel werden abhängig davon behandelt, ob der voreingestellte Wert ein ARRAY referenziert oder nicht.
Wenn der voreingestellte Werte eine ARRAY-Referenz ist, werden das erste folgenden Argument nach der Option --
und die weiteren folgenden Argumente, solange sie nicht mit "NAME
--
" anfangen, als Zeichenketten an das referenzierte Array angehängt. Das erste Argument nach --
wird stets als Wert an das Array angehängt, auch wenn es mit "NAME
--
" anfängt.
Das Argument, das der Option --
folgt, wird als Wert in den HASH eingetragen. Ein existierender Wert wird ersetzt.NAME
Das erste Argument, das nicht Wert zu einer Option ist und nicht dem Muster --
einer Option entspricht, wird als Positionsargument interpretiert. Wenn der Hash-Schlüssel NAME
_argv
existiert und sein Wert ein Array referenziert, werden das Argument und alle folgenden Argumente als Zeichenketten an das Array angehängt. Andernfalls wird ein Hash-Eintrag zu dem Schlüssel _argv
neu angelegt mit einer Referenz auf ein leeres Array als Wert. Die Positionsargumente werden an das Array angehängt.
Das Argument --
hat eine spezielle Funktion: es ist selbst kein Positions-Argument, aber alle folgenden Argumente sind Positions-Argumente.
Wenn ein Argument weder Wert einer Option noch Positionsargument ist und dem Muster --
einer Option entspricht, aber der Hash keinen passenden Schlüssel enthält, bricht das Programm mit dem Ende-Code 1 ab. Wenn der Zähler NAME
[cnt]verbose
definiert und nicht Null ist, wird eine Meldung an STDERR ausgegeben.
print_message_with_values
($msg
, $vals
)Ersetzt Platzhalter im Text $msg
und gibt den Text nach STDOUT aus. Diese Funktion erleichtert die Ausgabe einer Hilfe mit Angabe der aktuellen Einstellungen.
$msg
Der Text der Meldung mit Platzhaltern. Die Platzhalter haben die Form ${
. Teilzeichenketten der Form NAME
}$<{
werden durch NAME
>}${
ersetzt.NAME
}
Wenn $vals -> {"
nicht definiert ist, wird der Platzhalter entfernt.NAME
"}
Wenn $vals -> {"
ein ARRAY referenziert, wird der Platzhalter durch eine komma-getrennte Liste der Werte des ARRAY in eckigen Klammern ersetzt.NAME
"}
Andernfalls wird der Platzhalter durch den Wert $vals -> {"
in Klammern ersetzt.NAME
"}
$vals
Eine Referenz auf einen HASH mit den Werten, für die die Platzhalter stehen. In der Regel ist $vals
das Ergebnis der Funktion read_args
.
read_data_file
($file
, $args
, $k
)Trägt Daten aus einer Datei in den Hash $args
ein. Der Rückgabewert ist der Hash $args
.
$file
Wenn $file
ein absoluter Pfad ist, wird die Datei unter diesem Pfad gelesen. Wenn andernfalls $file
nicht mit .rc
endet, wird .rc
an $file
angehängt. Die Datei wird unter dem aktuellen Verzeichnis .
und den Verzeichnissen
und $HOME
/etc/etc
gesucht. Die erste gefundene Datei wird gelesen. Wenn die Datei nicht gefunden wird, endet die Funktion.
$args
$args
referenziert den Hash, in den die gelesenen Daten eingetragen werden. Wenn $args
keine Hash-Referenz ist, wird der Hash neu erzeugt.
Der Wert unter dem Schlüssel [cnt]verbose
bestimmt den Umfang der Meldungen nach STDERR.
$k
Wenn der Wert von $k
definiert ist, wird der Dateipfad der gelesenen Datei unter diesem Schlüssel in den Hash $args
eingetragen. Wenn $file
ein absoluter Dateipfad ist, wird dieser Pfad eingetragen, auch wenn die Datei nicht gelesen werden kann.
Die Daten-Datei enthält Text in UTF-8-Kodierung. Ein Zeilenanfang der Form
leitet einen Dateneintrag ein. KEY
= VAL
KEY
ist eine nicht-leere Folge von Buchstaben, Ziffern, Unterstrichen und Punkten, die vorn und hinten von beliebig vielen Leerzeichen umgeben sein kann. Auch das Gleichheitszeichen kann von beliebig vielen Leerzeichen umgeben sein. VAL
ist der Anfang eines Wertes und beginnt mit einem Nicht-Leerzeichen.
Der Wert, den die mit VAL
beginnende Zeichenkette darstellt, kann ein „nacktes” Wort, eine angeführte Zeichenkette, ein Array oder ein Hash sein. Die Darstellung des Wertes kann mehrere Zeilen umfassen. In der Zeile, in der der Wert endet, kann noch ein Kommentar folgen.
Wenn der Schlüssel [cnt]
im Hash KEY
$args
existiert, wird der Wert unter diesem Schlüssel eingetragen, sonst unter dem Schlüssel
.KEY
Ein „nacktes” Wort beginnt mit einem Nicht-Leerzeichen und endet vor dem ersten folgenden Leerzeichen, der ersten folgenden geschweiften oder eckigen Klammer, dem ersten folgenden Komma oder Gleichheitszeichen oder natürlich dem Ende der Datei.
Eine angeführte Zeichenkette wird mit dem Zeichen "
eingeleitet. In den folgenden Zeichen steht die Zeichenfolge \\
für das einzelne Zeichen \
, die Zeichenfolge \"
für das einzelne Zeichen "
, jedes andere Zeichen als "
steht für sich selbst. Der Wert der angeführten Zeichenkette endet vor dem nächsten "ungeschützten" Anführungszeichen "
. Das schließende Anführungszeichen gehört zur Darstellung des Wertes.
Die Darstellung eines Arrays beginnt mit dem Zeichen [
und endet mit dem Zeichen ]
. Die Werte des Array können von Leerzeichen und beliebig vielen Kommata und Kommentaren umgeben sein. Ein „nacktes” Wort als Wert eines Arrays kann daher effektiv nicht mit einem Komma oder dem Zeichen #
beginnen.
Ein Wert eines Arrays kann selbst ein Array oder ein Hash sein.
Die Darstellung eines Hash beginnt mit dem Zeichen {
und endet mit dem Zeichen }
. Die Einträge haben die Form
. KEY
=> VALUE
KEY
steht für ein „nacktes” Wort oder eine angeführte Zeichenkette als Schlüssel, VALUE
für einen beliebigen Wert („nacktes” Wort, angeführte Zeichenette, Array oder Hash), unter dem Schlüssel KEY
.
KEY
und VALUE
können von Kommentaren umgeben sein. Ein nacktes Wort als Schlüssel oder Wert kann daher nicht mit dem Zeichen #
beginnen. Statt der beiden Zeichen =>
kann auch ein einzelnes Gleichheitszeichen stehen.
Die Einträge eines Hash (Schlüssel-Wert-Paare) können von Leerzeichen, beliebig vielen Kommata und Kommentaren umgeben sein. Ein nacktes Wort als Schlüssel kann daher auch nicht mit einem Komma beginnen.
Ein Kommentar beginnt mit dem Zeichen #
, das nicht Teil eines nackten Wortes oder einer angeführten Zeichenkette ist, und endet mit dem folgenden Zeilenende.
Die Datei muss unter dem relativen Pfad
gefunden weren. INC
/Herbaer/Readargs.pmINC
steht für einen Eintrag in der Liste @INC
. Auf meinem System ist der Pfad der Datei /usr/local/share/perl/5.10.1/Herbaer/Readargs.pm
.