Unix-Validierungstools - Beschreibung SysVTools.pm

JT::CLI::SysVTools - Objektorientiertes Modul zum Aufbau von Command Line Interfaces analog zu den entsprechenden Unix-Eingabevalidierungstools.

  use JT::CLI::SysVTools;

  my $ck = JT::CLI::SysVTools->new($progType, $poPath, \%options);
  die unless defined $ck && ref $ck;
  my $rc = $ck->run($toolType, \@args);

Diese Dokumentation beschreibt JT::CLI::SysVTools in der Version 0.33.

Dieses Modul wurde als objektorientiertes Interface zum Abbilden der Unix-Validierungstools wie ckitem oder ckyorn implementiert. Es wird im sysvtools.pl-Programm genutzt, die Methoden können aber aus jedem Perl-Programm heraus genutzt werden.

Das Modul bietet einen einfachen Mechanismus zum Anzeigen einer Eingabeaufforderung und zum Abfragen und Validieren der Eingabe für unterschiedlichste Eingabe-Typen. Es definiert Fehler- und Hilfemeldungen und bietet einen Satz von Optionen zur Formatierung der Anzeige und zum Validieren der Eingabe.

Es werden keine Terminal-spezifischen Eigenschaften benutzt. Das Modul sollte also auch bei Verbindungen via Telnet oder SSH problemlos arbeiten. Zur Steuerung der Anzeige werden ausschließlich Tasten auf der normalen alphanumerischen Tastatur benutzt, die einzige "nicht alphanumerische" Taste ist CTRL-d (Stoppen der Anzeige in ckitem).

new($progType, $poPath, \%opts)

Erzeugt ein neues Objekt. Der progType-Parameter definiert den Typ des zu erzeugenden Eingabevalidierungstools. Die folgenden Typen werden unterstützt:

ckcont

Dies ist eine Erweiterung der unter Unix verfügbaren Tools. Es zeigt einfach eine Meldung an und wartet auf ein RETURN. Ich habe das vermisst, weil ich diese Art von "Drücken Sie <RETURN> um fortzufahren" immer dann benutze, wenn ich dem Anwender die Möglichkeit geben will, die Ausgabe oder Fehlermeldung eines Programms in Ruhe zu lesen, bevor er wieder in das Hauptmenü zurückkehrt.

ckdate

Die Eingabe muss ein Datum im definierten oder Default-Format sein.

ckgid

Die Eingabe muss ein existierender Gruppenname sein.

ckint

Die Eingabe muss ein Integer sein, optional passend zu einer vorgegebenen Basis (Default: 10). Die Ausgabe erfolgt immer zur Basis 10.

ckitem

Dieses Tool zeigt ein Menü an und prüft die Eingabe. Standardmäßig wird die Liste der Menüpunkte so formatiert, dass sie sortiert und mit einer Nummer versehen ist. Die Liste wird in Blöcken von 10 Punkten je Seite angezeigt. Das Standardverhalten kann durch Optionen übersteuert werden.

Wenn die Liste mehr als 10 Punkte umfasst, dann kann der Anwender per RETURN seitenweise vorwärts blättern. Mit CTRL-d wird die Anzeige gestoppt und die Eingabeaufforderung wird angezeigt. Die Eingabe von ?? bewirkt eine erneute Anzeige der Menüpunkte vom Beginn an.

ckkeywd

Die Eingabe muss eines der vorgegebenen Schlüsselwörter sein.

ckpath

Die Eingabe muss ein Pfadname sein, der den in den Optionen festgelegten Kriterien entspricht. Wenn keine Option definiert ist, dann muss die Eingabe eine reguläre Datei sein, die noch nicht existiert.

ckrange

Die Eingabe muss ein Integer sein, optional passend zu einer vorgegebenen Basis (Default: 10). Die Ausgabe erfolgt immer zur Basis 10. Die Eingabe wird gegen die vorgegebenen Minimal- und Maximalwerte geprüft. Wenn nur ein Grenzwert vorgegeben ist, dann wird auch nur gegen diesen geprüft.

ckstr

Die Eingabe muss eine Zeichenkette sein, die zum definierten regulären Ausdruck passt und nicht länger als die definierte Maximallänge ist. Wenn kein regulärer Ausdruck definiert ist, darf die Zeichenkette maximal so lang wie die definierte Länge sein und darf keine führenden, inneren oder abschließenden Leerzeichen oder Tabulatoren enthalten. Wenn keine Maximallänge vorgegeben ist, dann wird diese auch nicht geprüft.

cktime

Die Eingabe muss eine Tageszeit im definierten oder Defaultformat sein.

ckuid

Die Eingabe muss ein existierender Benutzername sein.

ckyorn

Die Eingabe muss "ja" oder "nein" sein.

Der poPath-Parameter ist der Pfad zu den .mo-Message-Katalogen. Ich habe noch keine Beschreibung gefunden, wo diese Dateien liegen sollten, damit man den extra bindtextdomain-Aufruf umgehen kann. Wenn Ihr dieses Modul mit dem make install-Target installiert habt, dann könnt Ihr den Parameter weglassen, der Installationspfad wird dann per Default benutzt.

Der opts-Parameter ist eine Hash-Referenz mit den allgemeinen und Tool-spezifischen Optionen, die den Programmablauf sowie die Validierung der Eingaben bestimmen.

Die folgenden Optionen sind Tool-übergreifend gültig:

  noQuit    => 0         # Abbruch ist keine erlaubte Eingabe (0|1)
  width     => 70        # Zeilenbreite für alle Meldungen (0..n)
  default   => ''        # der Default, wenn die Eingabe leer ist
  help      => ''        # Hilfemeldung
  error     => ''        # Fehlermeldung
  prompt    => ''        # Eingabeaufforderung
  killPID   => -1        # die Prozess-ID, an die bei 'Abbruch' ein Signal geschickt wird
  sigPID    => SIGTERM   # das zu sendende Signal

Die Fehler- und Hilfemeldungen sowie die Eingabeaufforderung werden per Default aus den Message-Katalogen gelesen. Ihr könnt diese Meldungen mit den o. g. Optionen übersteuern. Wenn am Anfang oder am Ende des definierten Textes eine Tilde (~) steht, dann wird an dieser Stelle der Standardtext eingefügt.

Die folgenden Optionen sind Tool-spezifisch:

  # ckcont
    message    => ''         # Meldung, die vor dem Eingabeprompt angezeigt wird
  # ckdate
    dFormat    => '%m/%d/%y' # das Datumformat, gegen das die Eingabe geprüft wird
  # ckgid
    listGroups => 0          # Zeige eine Gruppenliste bei Fehler oder Hilfe an (0|1)
  # ckint
    base       => 10         # Basis der Eingabe (2..36)
  # ckitem
    invisible  => []         # Liste der unsichtbaren Menüpunkte
    label      => ''         # Menü-Überschrift
    choices    => 1          # max. Anzahl der auszuwählenden Menüpunkte (1..n)
    noSort     => 0          # Menüpunkte nicht sortieren (0|1)
    onlyOne    => 0          # nur ein Token zurückliefern (0|1)
    noNumbers  => 0          # keine Ziffern vor den Menüpunkten (0|1)
    itemList   => []         # die Liste der Menüpunkte
  # ckkeywd
    keyWords   => []         # die Liste der erlaubten Schlüsselwörter
  # ckpath
    rel_abs    => ''         # 'relative' oder 'absolute'
    fileType   => ''         # Dateityp ('b', 'c', 'f' or 'y')
    fIsOld     => 0          # Datei muss existieren (0|1)
    fIsNew     => 0          # Datei darf nicht existieren (0|1)
    fCanCreate => 0          # Datei muss anzulegen sein (0|1)
    fNoEmpty   => 0          # Datei muss > 0 Bytes sein (0|1)
    filePerms  => ''         # Berechtigungen ('rwx')
  # ckrange
    base       => 10         # Basis der Eingabe (2..36)
    lower      => LONG_MIN   # Eingabeminimum
    upper      => LONG_MAX   # Eingabemaximum
  # ckstr
    sLength    => 0          # Maximallänge der Eingabe
    regex      => []         # Liste der Patterns, gegen die die Eingabe geprüft wird
  # cktime
    tFormat    => '%H:%M'    # das Zeitformat, gegen das die Eingabe geprüft wird
  # ckuid
    listUsers  => 0          # Zeige eine Benutzerliste bei Fehler oder Hilfe an  (0|1)

Die Optionen sind detaillierter in sysvtools.pl beschrieben.

run($toolType, \@args[, $silent)

Ablauf des Tools; liefert einen Returncode abhängig vom Validierungsergebnis zurück. Die folgenden Returncodes sind möglich:

0

Die Eingabe war korrekt. Der Wert der Eingabe wird auf STDOUT ausgegeben, wenn der silent-Parameter leer oder ungleich 1 ist.

2

Ungültiger Eingabewert für den val-Typ.

3

Abbruch durch Benutzer; die Eingabe wird auf STDOUT ausgegeben, wenn der silent-Parameter leer oder ungleich 1 ist.

Der toolType-Parameter definiert den Typ des auszuführenden Tools. Folgende Typen sind möglich:

ck

Zeigt die Eingabeaufforderung an und erwartet eine Benutzereingabe. Die Eingabe wird entsprechend den definierten Optionen validiert. Wenn die Eingabe fehlerhaft ist, wird die Fehlermeldung und dann wieder die Eingabeaufforderung angezeigt. Der Benutzer kann '?' für die Anzeige der Hilfemeldung eingeben, danach wird wieder die Eingabeaufforderung angezeigt.

Für den Programmtyp item wird zuerst - wenn definiert - eine Überschrift und dann die Liste der Menüpunkte angezeigt. Wenn diese Liste mehr als 10 Einträge umfasst, kann der Benutzer mit RETURN weiterblättern oder die Listenanzeige mit CTRL-d stoppen und zur Eingabeaufforderung wechseln.

val

Validiert den übergebenen Eingabewert; es erfolgt keine Anzeige.

err

Zeigt die Fehlermeldung an.

help

Zeigt den Hilfetext an.

Der optionale Parameter silent definiert, ob der eingegebene Wert auf STDOUT angezeigt wird.

showMessage($msgType)

Zeigt die mit dem Parameter msgType angeforderte Meldung an. Die Typen 'error', 'help' und 'prompt' werden in allen Tools unterstützt. Für den Programmtyp item sind 3 zusätzliche Meldungstypen verfügbar: 'error_num', für eine ungültige Nummer eines Menüpunktes, 'error_str' für die Eingabe eines nicht vorhandenen Menüpunktes und 'error_uniq', wenn die Eingabe nicht eindeutig einem Menüpunkt zugeordnet werden konnte.

showList()

Diese Methode ist nur für den Programmtyp item zulässig. Zeigt die Menüliste an und steuert das Navigieren innerhalb der Liste.

value()

Liefert die Benutzereingabe zurück, wenn sie erfolgreich validiert wurde oder wenn der Benutzer 'a' (Abbruch) eingegeben hat. In allen anderen Fällen wird ein leerer String zurückgegeben.

validateInput($input)

Validiert den im Parameter input angegebenen Wert gegen die definierten Validierungsoptionen. Abhängig vom Validierungsergebnis und Programmtyp wird einer der folgenden Returncodes zurückgegeben:

0

Die Eingabe war korrekt. Der Wert der Eingabe ist über die Methode value() verfügbar.

1

Validierungsfehler.

2

Leere Eingabe, aber default verfügbar. Der konfigurierte Defaultwert ist über die Methode value() verfügbar.

3

Leere Eingabe, kein default verfügbar.

4

Abbruch durch Benutzer; Die Eingabe ist über die Methode value() verfügbar. Wenn die noQuit-Option auf 'wahr' (1) gesetzt ist, dann ist dieser Returncode nicht möglich. In diesem Fall wird ein Validierungsfehler zurückgeliefert.

5

Hilfe wurde angefordert (der Benutzer hat '?' eingegeben).

6

Das Menü soll neu angezeigt werden (Benutzereingabe war '??'); nur für ckitem.

7

Eine numerische Eingabe passte auf keinen der vorhandenen Menüpunkte; nur für ckitem.

8

Eine alphanumerische Eingabe passte auf keinen der vorhandenen Menüpunkte; nur für ckitem.

9

Eine alphanumerische Eingabe identifizierte keinen Menüpunkt eindeutig; nur für ckitem.

BUGS

Es gibt einige Unterschiede zum Verhalten der Originale, diese sind auf meiner TODO-Seite beschrieben. Wenn Ihr einen Fehler findet, dann schickt mir bitte eine detaillierte Fehlermeldung.