NAME

Quiq::Program - Basisklasse für Programme

BASE CLASSES

SYNOPSIS

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;
...

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.222

AUTHOR

Frank Seitz, http://fseitz.de/

COPYRIGHT

LICENSE

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)