Herbaer::Readargs

`read_args` (`$args`, `$argv`)

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

Parameter `$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 [TYPE]NAME oder 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.

Schlüssel `[cnt]NAME`

Der Wert zu dem Schlüssel ist ein Zähler (nicht-negative ganze Zahl). Jede Option --NAME erhöht den Zähler um eins oder setzt den Wert auf eins, falls er noch nicht definiert ist. Jede Option --no_NAME setzt den Zähler auf den Wert null.

Eine typische Anwendung ist der Schlüssel [cnt]verbose. Der Wert steuert üblicherweise den Umfang der Ausgabe an STDERR.

Schlüssel `[sr]NAME`

Der voreingestellte Wert zu diesem Schlüssel muß ein Unterprogramm referenzieren. Die Option --NAME führt zum Aufruf des Unterprogramms mit den Parametern $args und $argv.

Typische Anwendungen sind die Schlüssel [sr]help (Option --help) und [sr]version (Option --version).

Schlüssel `[rc]NAME`

Das Argument --NAME dient dazu, weitere Daten aus einer Datei zu lesen. Das folgende Argument FILE bestimmt die Datei. Es wird die Funktion read_data_file ("FILE", $args, "[rc]NAME") aufgerufen.

Andere Schlüssel mit einer ARRAY-Referenz als Wert

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 --NAME und die weiteren folgenden Argumente, solange sie nicht mit "--" anfangen, als Zeichenketten an das referenzierte Array angehängt. Das erste Argument nach --NAME wird stets als Wert an das Array angehängt, auch wenn es mit "--" anfängt.

Andere Schlüssel ohne Wert oder mit einfachem Wert

Das Argument, das der Option --NAME folgt, wird als Wert in den HASH eingetragen. Ein existierender Wert wird ersetzt.

Positionsargumente

Das erste Argument, das nicht Wert zu einer Option ist und nicht dem Muster --NAME einer Option entspricht, wird als Positionsargument interpretiert. Wenn der Hash-Schlüssel _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 --NAME 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 [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 ${NAME}. Teilzeichenketten der Form $<{NAME>} werden durch ${NAME} ersetzt.

Wenn $vals -> {"NAME"} nicht definiert ist, wird der Platzhalter entfernt.

Wenn $vals -> {"NAME"} ein ARRAY referenziert, wird der Platzhalter durch eine komma-getrennte Liste der Werte des ARRAY in eckigen Klammern ersetzt.

Andernfalls wird der Platzhalter durch den Wert $vals -> {"NAME"} in Klammern ersetzt.

$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 $HOME/etc und /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.

Dateneinträge

Die Daten-Datei enthält Text in UTF-8-Kodierung. Ein Zeilenanfang der Form KEY = VAL leitet einen Dateneintrag ein. 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]KEY im Hash $args existiert, wird der Wert unter diesem Schlüssel eingetragen, sonst unter dem Schlüssel KEY.

„Nackte” Wörter

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.

Angeführte Zeichenketten

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.

Arrays

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.

Hash

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.

Kommentare

Ein Kommentar beginnt mit dem Zeichen #, das nicht Teil eines nackten Wortes oder einer angeführten Zeichenkette ist, und endet mit dem folgenden Zeilenende.