Quiq::Program - Basisklasse für Programme
Quiq::Process
Quiq::Hash
Programm:
#!/usr/bin/env perl use Quiq::Program; exit Quiq::Program->run('MyProg')->exitCode; # eof
Programm-Klasse:
package MyProg; use base 'Quiq::Program'; sub main { my $self = shift; ... return; } # eof
Optionen und Argumente:
my ($error,$opt,$argA) = $self->options( ... -help => 0, ); if ($error) { $self->help(10,"ERROR: $error"); } elsif ($opt->help) { $self->help; } elsif (@$argA != 1) { $self->help(11,'ERROR: Falsche Anzahl Argumente'); } my $myArg = shift @$argA; ...
$prg = Quiq::Program->run($programClass,@options);
Siehe Methode new()
$prg->exit; $prg->exit($exitCode);
Terminiere das Programm mit Exitcode $exitCode. Ist kein Exitcode angegeben, terminiere mit dem Exitcode der auf dem Programmobjekt gesetzt ist. Die Methode kehrt nicht zurück. Nach ihrem Aufruf wird die Methode finish() ausgeführt.
$exitCode = $prg->exitCode; $exitCode = $prg->exitCode($exitCode);
$name = $this->name;
Liefere den Namen des Programms. Der Programmname ist die letzte Pfadkomponente von $0.
$prg->main;
$prg->catch($exception);
Exception-Handler, der unbehandelte Exceptions der Anwendung fängt. Kann von der Programmklasse bei Bedarf überschrieben werden. Das Default-Verhalten ist, dass der Exception-Text auf STDERR ausgegeben und der Exitcode auf 99 gesetzt wird.
Das Programm terminiert nicht sofort, sondern die Methode finish() wird noch ausgeführt.
$prg->finish;
$envH = $this->env; $envH = $this->env(\%env);
$argA|@args = $this->argv; $argA|@args = $this->argv(\@argv);
$fh = $this->stdin; $fh = $this->stdin($fh);
$fh = $this->stdout; $fh = $this->stdout($fh);
$fh = $this->stderr; $fh = $this->stderr($fh);
$encoding = $prg->encoding;
Liefere das Standard-Encoding, das in der Systemumgebung eingestellt ist. Im Konstruktor werden STDIN, STDOUT und STDERR auf dieses Encoding eingestellt, d.h. Eingaben und Ausgaben automatisch gemäß dieses Encodings gewandelt.
$str = $prg->decode($str);
$str = $prg->encode($str);
[1] ($argA,$opt) = $prg->parameters($sloppy,$minArgs,$maxArgs,@optVal); [2] $opt = $prg->parameters($sloppy,0,0,@optVal); [3] $argA = $prg->parameters($sloppy,$minArgs,$maxArgs,@optVal);
Wirf keine Exception, wenn unerwartete Parameter (also Optionen und Arumente) in @ARGV enthalten sind. Diese Parameter bleiben in @ARGV stehen.
Mindestanzahl an Argumenten.
Maximale Anzahl an Argumenten.
Liste der Optionen und ihrer Defaultwerte.
Hash-Objekt mit den Optionen.
Referenz auf Array mit mindestens $minArgs und höchstens $maxArgs Argumenten.
Liefere die Argumente und Optionen des Programmaufs. Werden weniger als $minArgs oder mehr als $maxArgs Argumente oder nicht deklarierte Optionen übergeben, wird eine Exception geworfen. Ist $sloppy gesetzt, wird im Falle überzähliger Parameter keine Exception geworfen. Die überzähligen Parameter bleiben in @ARGV erhalten.
Im Skalarkontext wird nur $opt geliefert, wenn keine Argumente erwartet werden ($minArgs und $maxArgs sind 0), andernfalls $argA. Letzteres ist nützlich, wenn -help die einzige Option ist.
-help
$prg->assert(sub {...});
Prüfe Werte durch Methoden der Klasse Quiq::Assert. Ist eine Zusicherung verletzt, wird die betreffende Exception in die Ausgabe der Programm-Hilfeseite umgesetzt. Die Subroutine erhält als Argument ein instantiiertes Quiq::Assert-Objekt.
Prüfe die Werte der Variablen $system und $user gegen eine Menge möglicher Werte: $self->assert(sub { my $a = shift; $a->isEnumValue($system,['test','prod'], -name=>'SYSTEM', ); $a->isEnumValue($user,[qw/etlt etls etlr etlp/], -name=>'USER', ); });
($error,$optH,$argA) = $prg->options(@keyVal);
FIXME: Veraltete Methode. Alle Stellen, wo die Methode options() genutzt wird, auf parameters() portieren.
$val = $prg->opt($key); # [1] @vals = $prg->opt(@keys); # [2] $optH = $prg->opt; # [3]
$dir = $prg->projectDir($depth);
Liefere den Verzeichnispfad, der $depth Stufen oberhalb des Verzeichnisses endet, in dem das Programm installiert ist.
Der Installationspfad wird anhand von $0 ermittelt. Wurde das Programm mit einem relativen Pfad aufgerufen, wird dieser zu einem absoluten Pfad komplettiert.
Wurde das Programm myprog unter dem Pfad
/opt/myapp/bin/myprog
installiert, dann liefert $prg->projectDir(1) den Pfad
/opt/myapp
als Projektverzeichnis.
$sec = $prg->elapsed;
Sekunden (Float)
Ermittele die vergangene Zeit in Sekunden und liefere diese zurück.
$prg->log($fmt,@args); $prg->log($level,$fmt,@args);
Schreibe eine Logmeldung nach STDERR, wenn $level größer oder gleich dem eingestellten Loglevel ($prg->logLevel) ist. Ist $level nicht angegeben, wird 1 angenommen.
Die Logmeldung wird per
printf STDERR $fmt,@args;
erzeugt. Endet $fmt nicht mit einem Newline, wird es hinzugefügt.
Per Default ist der LogLevel 0. Er wird mit
$prg->logLevel($n); # $n > 0
eingestellt.
Ist $fmt eine Zahl, muss der Level $level explizit angegeben werden.
Die Argumente der Methode werden immer ausgewertet, auch wenn kein Logging erfolgt. Ist damit ein größerer Aufwand verbunden, kann es sinnvoll sein, eine Bedingung zu formulieren:
if ($level >= $prg->logLevel) { # $msg mit großem Aufwand erzeugen $prg->log($level,$msg); }
$self->help; $self->help($exitCode); $self->help($exitCode,$msg);
Der Hilfetext wird aus der POD-Dokumentation des Programms generiert.
Ist $exitCode == 0, wird der Hilfetext auf STDOUT ausgegeben. Ist $exitCode != 0, wird der Hilfetext auf STDERR ausgegeben.
Ist $msg angegeben, wird die Hilfeseite oben und unten um Text $msg ergänzt (jeweils mit Leerzeile abgetrennt).
Ist $exitCode == 0 und STDOUT mit einem Terminal verbunden, wird der Hilfetext im Pager dargestellt (Environment-Variable $PAGER oder less).
$prg = $class->new(@options);
Setze Programm-Argumente auf @arr.
Setze Programm-Environment auf %hash.
Setze STDIN des Programms auf $fh.
Setze STDOUT des Programms auf $fh.
Setze STDERR des Programms auf $fh.
1.196
Frank Seitz, http://fseitz.de/
Copyright (C) 2021 Frank Seitz
This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Quiq, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Quiq
CPAN shell
perl -MCPAN -e shell install Quiq
For more information on module installation, please visit the detailed CPAN module installation guide.