NAME
Quiq::Program - Basisklasse für Programme
BASE CLASSES
SYNOPSIS
Programm:
Programm-Klasse:
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
;
...
METHODS
Programmsteuerung
run() - Führe Programm-Klassen aus
Synopsis
$prg
= Quiq::Program->run(
$programClass
,
@options
);
Options
Siehe Methode new()
exit() - Terminiere das Programm
Synopsis
$prg
->
exit
;
$prg
->
exit
(
$exitCode
);
Description
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.
Getter/Setter
exitCode() - Liefere/Setze Exitcode
Synopsis
$exitCode
=
$prg
->exitCode;
$exitCode
=
$prg
->exitCode(
$exitCode
);
name() - Name des Programms
Synopsis
$name
=
$this
->name;
Description
Liefere den Namen des Programms. Der Programmname ist die letzte Pfadkomponente von $0.
Programmcode
main() - Hauptprogramm
Synopsis
$prg
->main;
catch() - Fange und behandle unbehandelte Exception
Synopsis
$prg
->
catch
(
$exception
);
Description
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.
finish() - Abschließender Code vor Programmende
Synopsis
$prg
->finish;
Umgebung
env() - Liefere/Setze Environment-Hash
Synopsis
$envH
=
$this
->env;
$envH
=
$this
->env(\
%env
);
argv() - Liefere/Setze Argument-Array
Synopsis
$argA
|
@args
=
$this
->argv;
$argA
|
@args
=
$this
->argv(\
@argv
);
stdin() - Liefere/Setze STDIN Filehandle
Synopsis
$fh
=
$this
->stdin;
$fh
=
$this
->stdin(
$fh
);
stdout() - Liefere/Setze STDOUT Filehandle
Synopsis
$fh
=
$this
->stdout;
$fh
=
$this
->stdout(
$fh
);
stderr() - Liefere/Setze STDERR Filehandle
Synopsis
$fh
=
$this
->stderr;
$fh
=
$this
->stderr(
$fh
);
Character Encoding
encoding() - Standard-Encoding
Synopsis
$encoding
=
$prg
->encoding;
Description
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.
decode() - Dekodiere Zeichenkette gemäß Standard-Encoding
Synopsis
$str
=
$prg
->decode(
$str
);
encode() - Enkodiere Zeichenkette gemäß Standard-Encoding
Synopsis
$str
=
$prg
->encode(
$str
);
Parameter
parameters() - Argumente und Optionen des Programmaufrufs
Synopsis
[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
);
Arguments
- $sloppy
-
Wirf keine Exception, wenn unerwartete Parameter (also Optionen und Arumente) in @ARGV enthalten sind. Diese Parameter bleiben in @ARGV stehen.
- $minArgs
-
Mindestanzahl an Argumenten.
- $maxArgs
-
Maximale Anzahl an Argumenten.
- @optVal
-
Liste der Optionen und ihrer Defaultwerte.
Returns
- $opt
-
Hash-Objekt mit den Optionen.
- $argA
-
Referenz auf Array mit mindestens $minArgs und höchstens $maxArgs Argumenten.
Description
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.
Zusicherungen
assert() - Prüfe Werte
Synopsis
$prg
->assert(
sub
{...});
Description
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.
Example
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'
,
);
});
Optionen
options() - Verarbeite Programmoptionen (DEPRECATED)
Synopsis
(
$error
,
$optH
,
$argA
) =
$prg
->options(
@keyVal
);
Description
FIXME: Veraltete Methode. Alle Stellen, wo die Methode options() genutzt wird, auf parameters() portieren.
opt() - Liefere Optionsobjekt oder Optionswerte
Synopsis
$val
=
$prg
->opt(
$key
);
# [1]
@vals
=
$prg
->opt(
@keys
);
# [2]
$optH
=
$prg
->opt;
# [3]
Verzeichnisse
projectDir() - Projektverzeichnis
Synopsis
$dir
=
$prg
->projectDir(
$depth
);
Description
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.
Example
Wurde das Programm myprog unter dem Pfad
/opt/myapp/bin/myprog
installiert, dann liefert $prg->projectDir(1) den Pfad
/opt/myapp
als Projektverzeichnis.
Zeit
elapsed() - Vergangene Zeit in Sekunden
Synopsis
$sec
=
$prg
->elapsed;
Returns
Sekunden (Float)
Description
Ermittele die vergangene Zeit in Sekunden und liefere diese zurück.
Logging
log() - Schreibe Meldung nach STDERR
Synopsis
$prg
->
log
(
$fmt
,
@args
);
$prg
->
log
(
$level
,
$fmt
,
@args
);
Description
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.
Caveats
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
);
}
Hilfe
help() - Gib Hilfetext aus und beende Programm
Synopsis
$self
->help;
$self
->help(
$exitCode
);
$self
->help(
$exitCode
,
$msg
);
Description
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).
Instantiierung
new() - Instantiiere Programm-Objekt
Synopsis
$prg
=
$class
->new(
@options
);
Options
- -argv=>\@arr (Default: \@ARGV)
-
Setze Programm-Argumente auf @arr.
- -env=>\%hash (Default: \%ENV)
-
Setze Programm-Environment auf %hash.
- -stdin=>$fh (Default: \*STDIN)
-
Setze STDIN des Programms auf $fh.
- -stdout=>$fh (Default: \*STDOUT)
-
Setze STDOUT des Programms auf $fh.
- -stderr=>$fh (Default: \*STDERR)
-
Setze STDERR des Programms auf $fh.
VERSION
1.223
AUTHOR
Frank Seitz, http://fseitz.de/
COPYRIGHT
Copyright (C) 2024 Frank Seitz
LICENSE
This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.