NAME
Quiq::Perl - Erweiterte und abgesicherte Perl-Operationen
BASE CLASS
DESCRIPTION
Die Klasse implementiert grundlegende Perl-Operationen, die Erweiterungen darstellen und/oder durch Exception-Behandlung abgesichert sind.
METHODS
I/O
autoFlush() - Aktiviere/Deaktiviere Pufferung auf Dateihandle
Synopsis
$this->autoFlush($fh);
$this->autoFlush($fh,$bool);Description
Schalte Pufferung auf Dateihandle ein oder aus.
Der Aufruf ist äquivalent zu
$oldFh = select $fh;
$| = $bool;
select $oldFh;See Also
perldoc -f select
Example
Quiq::Perl->autoFlush(*STDOUT);binmode() - Aktiviere Binärmodus oder setze Layer
Synopsis
$class->binmode($fh);
$class->binmode($fh,$layer);Description
Schalte Filehandle $fh in Binärmodus oder setze Layer $layer. Die Methode ist eine Überdeckung der Perl-Funktion binmode und prüft deren Returnwert. Im Fehlerfall wirft die Methode eine Exception.
See Also
perldoc -f binmode
Example
Quiq::Perl->binmode(*STDOUT,':encoding(utf-8)');print() - Schreibe auf Dateihandle
Synopsis
Quiq::Perl->print($fh,@data);Description
Schreibe Daten @data auf Dateihandle $fh. Die Methode ist eine Überdeckung der Perl-Funktion print und prüft deren Returnwert. Im Fehlerfall wirft die Methode eine Exception.
See Also
perldoc -f print
Example
Quiq::Perl->print($fh,"Hello world\n");use() - Lade Klasse per use
Synopsis
$class->use($class,$sloppy);Description
Lade Klasse $class per use. Im Fehlerfall wirft die Methdoe eine Exception. Ist $sloppy wahr, wird keine Exception geworfen, sondern ein boolscher Wert: 1 für erfolgreiche Ausführung, 0 für fehlgeschlagen. Die globale Variable $@ gibt den Grund an.
See Also
Sonstige Operationen
perlDoFile() - Überdeckung für do()
Synopsis
@arr|$val = Quiq::Perl->perlDoFile($file);Description
Überdeckung für die Perl-Funktion do() in der Variante do($file). Die Funktion liefert den Wert des letzten ausgewerteten Ausdrucks bei Ausführung der Datei $file. Im Fehlerfall wirft die Funktion eine Exception.
Genaue Funktionsbeschreibung siehe Perl-Dokumentation.
Example
Laden einer Konfigurationsdatei:
%cfg = Quiq::Perl->perlDoFile($file);Inhalt Konfigurationsdatei:
use strict;
host => 'localhost',
datenbank => 'entw1',
benutzer => ['sys','system']Sigil
sigilToType() - Wandele Sigil in Datentyp-Bezeichner
Synopsis
$type = $this->sigilToType($sigil);Description
Wandele $sigil ('$', '@' oder '%') in Datentyp-Bezeichner ('SCALAR', 'ARRAY' oder 'HASH') und liefere diesen zurück.
Symboltabellen
stash() - Referenz auf Symboltabelle eines Package
Synopsis
$refH = $this->stash($package);Description
Liefere eine Referenz auf den "Symbol Table Hash" (Stash) des Package $package. Der Hash enthält für jede globale Variable und jedes Unterpackage einen Eintrag. Existiert der Stash nicht (und damit auch nicht das Package), liefere undef.
Packages/Klassen
packages() - Liste der existierenden Packages
Synopsis
@arr|$arr = $this->packages;
@arr|$arr = $this->packages($package);Description
Liefere die Liste der existierenden Packages, die im Stash des Package $package und darunter enthalten sind, einschließlich Package $package selbst. Im Skalarkontext liefere eine Referenz auf die Liste. Wird die Methode ohne Argument aufgerufen wird Package 'main' angenommen.
Anmerkung
Packages entstehen zur Laufzeit. Die Liste der Packages wird nicht gecacht, sondern mit jedem Aufruf neu ermittelt.
Example
Liste aller Packages, die das Programm aktuell geladen hat:
@arr = Quiq::Perl->packages;Liste in sortierter Form
@arr = Quiq::Perl->packages->sort;Liste, eingeschränkt auf Packages, deren Name einen Regex erfüllt:
@arr = Quiq::Perl->packages->select(qr/patch\d+/);Liste aller Packages unterhalb und einschließlich Package X:
@arr = Quiq::Perl->packages('X');
createClass() - Erzeuge Klasse
Synopsis
$class->createClass($newClass,@baseClasses);Description
Erzeuge Klasse $newClass, falls sie noch nicht existiert, und definiere die Klassen @baseClasses als deren Basisklassen. Die Methode liefert keinen Wert zurück.
Die Basisklassen werden per "use base" geladen.
classExists() - Prüfe Existenz von Klasse/Package
Synopsis
$bool = $class->classExists($class);Alias
packageExists()
Description
Prüfe, ob die Perl-Klasse bzw. das Package $class in-memory existiert, also von Perl bereits geladen wurde. Liefere wahr, wenn Klasse existiert, andernfalls falsch.
Example
Quiq::Perl->classExists('Quiq::Object');
==>
1loadClass() - Lade Klasse, falls nicht existent
Synopsis
$class->loadClass($class);Description
Lade Klasse $class. Im Unterschied zu Methode use() wird die Moduldatei nur zu laden versucht, wenn es den Namensraum (Package) der Klasse noch nicht gibt.
Example
Quiq::Perl->loadClass('My::Application');baseClasses() - Liefere Liste aller Basisklassen (einschl. UNIVERSAL)
Synopsis
@arr | $arr = $this->baseClasses($class);Description
Liefere die Liste der *aller* Basisklassen der Klasse $class, einschließlich UNIVERSAL und deren Basisklassen.
Example
Gegeben folgende Vererbungshierarchie:
Pkg6 Pkg7
\ /
UNIVERSAL
Pkg1
|
Pkg2
/ \
Pkg3 Pkg4
\ /
Pkg5Der Aufruf Quiq::Perl->baseClasses('Pkg5') liefert ein Array mit den Elementen
Pkg3 Pkg2 Pkg1 Pkg4 UNIVERSAL Pkg6 Pkg7Die Klassen Pkg2 und Pkg1 werden nicht wiederholt.
baseClassesISA() - Liefere Liste der ISA-Basisklassen
Synopsis
@arr | $arr = $this->baseClassesISA($class);Description
Liefere die Liste der Basisklassen der Klasse $class. Jede Basisklasse kommt in der Liste genau einmal vor.
Example
Gegeben folgende Vererbungshierarchie:
Pkg1
|
Pkg2
/ \
Pkg3 Pkg4
\ /
Pkg5Der Aufruf Quiq::Perl->baseClassesISA('Pkg5') liefert ein Array mit den Elementen
Pkg3 Pkg2 Pkg1 Pkg4Die Klassen Pkg2 und Pkg1 werden nicht wiederholt.
hierarchyISA() - Liefere ISA-Hierarchie
Synopsis
@arr | $arr = $this->hierarchyISA($class);Description
Liefere die ISA-Hierarchie der Klasse $class. Kommt eine Basisklasse in der Hierarchie mehrfach vor, erscheint sie mehrfach in der Liste.
Example
Gegeben folgende Vererbungshierarchie:
Pkg1
|
Pkg2
/ \\
Pkg3 Pkg4
\ /
Pkg5Der Aufruf Quiq::Perl->hierarchyISA('Pkg5') liefert ein Array mit den Elementen
Pkg3 Pkg2 Pkg1 Pkg4 Pkg2 Pkg1Die Basisklassen Pkg2 und Pkg1 erscheinen zweimal.
subClasses() - Liefere Liste aller Subklassen
Synopsis
@arr | $arr = $this->subClasses($class);Description
Liefere die Liste der Subklassen der Klasse $class.
Example
Gegeben folgende Vererbungshierarchie:
Pkg1
|
Pkg2
/ \
Pkg3 Pkg4
\ /
Pkg5Der Aufruf Quiq::Perl->subClasses('Pkg1') liefert ein Array mit den Elementen:
Pkg2 Pkg3 Pkg4 Pkg5Die Reihenfolge der Elemente ist nicht definiert.
Liste in sortierter Form
@arr = Quiq::Perl->subClasses('Pkg1')->sort;Liste, eingeschränkt auf Klassen, deren Name einen Regex erfüllt:
@arr = Quiq::Perl->subClasses('Pkg1')->select(qr/[45]/);
nextMethod() - Finde nächste Methoden-Instanz
Synopsis
($nextClass,$nextMeth) = $this->nextMethod($class,$name,$startClass);classNameToPath() - Übersetze Klassenname in Klassenpfad
Synopsis
$classPath = $class->classNameToPath($className);Description
Übersetze den Klassennamen $className in den entsprechenden Klassenpfad (ohne Dateiendung) und liefere diesen zurück.
Example
'A::B::C' => 'A/B/C'classPathToName() - Übersetze Klassenpfad in Klassenname
Synopsis
$className = $class->classPathToName($classPath);Description
Übersetze Klassenpfad $classPath (ist eine Endung vorhanden, wird sie entfernt) in den entsprechenden Klassennamen und liefere diesen zurück.
Example
'A/B/C' ==> 'A::B::C'
'A/B/C.pm' ==> 'A::B::C'Typeglobs
createAlias() - Setze Typeglob-Eintrag
Synopsis
$this->createAlias($package,$sym=>$ref);
$this->createAlias($sym=>$ref);Description
Weise dem Typeglob-Eintrag $sym in der Symboltabelle des Package $package die Referenz $ref zu. Die Methode liefert keinen Wert zurück.
Der Aufruf ist äquivalent zu:
no strict 'refs';
*{"$package\::$sym"} = $ref;Ist $package nicht angegeben wird das Package des Aufrufers (d.h. das Package, aus dem heraus der Aufruf erfolgt) genommen.
Example
Alias für Subroutine aus anderer Klasse:
Quiq::Perl->createAlias('MyClass',mySub=>\&MyClass1::mySub1);Eintrag einer Closure in die Symboltabelle:
Quiq::Perl->createAlias(__PACKAGE__,mySub=>sub { <code> });
createHash() - Erzeuge Package-globalen Hash
Synopsis
$ref = $this->createHash($package,$sym);Description
Erzeuge einen globalen Hash in Package $package und liefere eine Referenz diesen zurück.
Example
Erzeuge in $class den Hash %H:
$ref = $this->createHash($class,'H');die Referenz kann geblesst werden:
bless $ref,'Quiq::Hash';
getHash() - Liefere Referenz auf Package-Hash
Synopsis
$ref = $this->getHash($package,$name);Example
$ref = Quiq::Perl->getHash($package,'H');setHash() - Setze Package-Hash auf Wert
Synopsis
$ref = $this->setHash($package,$name,$ref);Description
Setze Package-Hash mit dem Namen $name auf den von $ref referenzierten Wert, also auf %$ref und liefere eine Referenz auf die Variable zurück.
Die Methode kopiert den Wert, sie erzeugt keinen Alias!
Example
Setze Paket-Hash 'h' auf den Wert %hash:
$ref = Quiq::Perl->setHash($package,'h',\%hash);
createArray() - Erzeuge Package-globales Array
Synopsis
$ref = $this->createArray($package,$sym);Description
Erzeuge ein globales Array in Package $package und liefere eine Referenz dieses zurück.
Example
Erzeuge in $class das Array @A:
$ref = Quiq::Perl->createArray($class,'A');die Referenz kann geblesst werden:
bless $ref,'Quiq::Array';
getArray() - Liefere Referenz auf Package-Array
Synopsis
$ref = $this->getArray($package,$name);Example
$ref = Quiq::Perl->getArray($package,'A');setArray() - Setze Package-Array auf Wert
Synopsis
$ref = $this->setArray($package,$name,$ref);Description
Setze Package-Array mit dem Namen $name auf den von $ref referenzierten Wert, also auf @$ref und liefere eine Referenz auf die Variable zurück.
Die Methode kopiert den Wert, sie erzeugt keinen Alias!
Example
Setze Paket-Array 'a' auf den Wert @arr:
$ref = Quiq::Perl->setArray($package,'a',\@arr);
setScalar() - Setze Package-Skalar auf Wert
Synopsis
$ref = $this->setScalar($package,$name,$val);Description
Setze Package-Skalar mit dem Namen $name auf den Wert $val und liefere eine Referenz auf die Variable zurück.
Example
Setze Paket-Skalar 'n' auf den Wert 99:
$ref = $this->setScalar($package,n=>99);
setScalarValue() - Setze Package-Skalar auf Wert
Synopsis
$this->setScalarValue($package,$name=>$val);Description
Setze Package-Skalar mit dem Namen $name auf den Wert $val.
Example
Setze Paket-Skalar 'n' auf den Wert 99:
$ref = Quiq::Perl->setScalarValue($package,n=>99);
getScalarValue() - Liefere Wert von Package-Skalar
Synopsis
$val = $this->getScalarValue($package,$name);Example
Ermittele Wert von Paket-Skalar 'n':
$val = Quiq::Perl->getScalarValue($package,'n');
setVar() - Setze Package-Variable auf Wert
Synopsis
$ref = $this->setVar($package,$sigil,$name,$ref);Description
Setze Paketvariable vom Typ $sigil ('$', '@' oder '%') mit dem Namen $name auf den von $ref referenzierten Wert (also $$ref (falls Skalar) oder @$ref (falls Array) oder %$ref (falls Hash)) und liefere eine Referenz auf die Variable zurück.
Die Subroutine kopiert den Wert, sie erzeugt keinen Alias!
Example
Skalar
$ref = Quiq::Perl->setVar($package,'$','s',\99);Array
$ref = Quiq::Perl->setVar($package,'@','a',\@arr);Hash
$ref = Quiq::Perl->setVar($package,'%','h',\%hash);
getVar() - Liefere Referenz auf Package-Variable
Synopsis
$ref = $this->getVar($package,$sigil,$name,@opt);Options
Description
Liefere eine Referenz auf Package-Variable $name vom Typ $sigil ('$','@' oder '%'). Existiert die Variable nicht, liefere undef.
Caveats
Skalare Variable
Skalare Paketvariable, die mit "our" vereinbart sind und den Wert undef haben, werden von der Funktion nicht erkannt bzw. nicht sicher erkannt (Grund ist unklar). Mit "our" vereinbarte skalare Paketvariable mit definiertem Wert werden sicher erkannt. Workaround: Skalare Paketvariable, die mit der Methode abgefragt werden sollen, auch wenn sie den Wert undef haben, mit "use vars" vereinbaren.
setSubroutine() - Setze Package-Subroutine auf Wert
Synopsis
$ref = $this->setSubroutine($package,$name=>$ref);Returns
Referenz auf die Subroutine.
Description
Füge Subroutine $ref zu Package $package unter dem Namen $name hinzu. Existiert eine Package-Subroutine mit dem Namen bereits, wird diese ersetzt.
Examples
Definition:
$ref = Quiq::Perl->setSubroutine('My::Class',m=>sub {...});Aufruf:
My::Class->m(...);oder
$ref->(...);getSubroutine() - Liefere Referenz auf Subroutine
Synopsis
$ref = $this->getSubroutine($package,$name);Description
Liefere Referenz auf Subroutine $name in Package $package. Enthält das Package keine Subroutine mit dem Namen $name, liefere undef.
Suchpfade
basicIncPaths() - Grundlegende Modul-Suchpfade
Synopsis
@paths|$pathA = $class->basicIncPaths;Description
Liefere die Liste der grundlegenden Suchpfade des aktuell laufenden Perl-Interpreters. Ergänzungen durch
-Ipath
PERLLIB
PERL5LIB
use lib (@paths)
usw.
sind nicht enthalten.
Die Liste entspricht dem Ergebnis des Aufrufs
$ PERLLIB= PERL5LIB= perl -le 'print join "\n",@INC'See Also
Example
Quiq::Perl->basicIncPaths;
==>
/etc/perl
/usr/local/lib/x86_64-linux-gnu/perl/5.20.2
/usr/local/share/perl/5.20.2
/usr/lib/x86_64-linux-gnu/perl5/5.20
/usr/share/perl5
/usr/lib/x86_64-linux-gnu/perl/5.20
/usr/share/perl/5.20
/usr/local/lib/site_perl
.additionalIncPaths() - Zusätzliche Modul-Suchpfade
Synopsis
@paths|$pathA = $class->additionalIncPaths;Description
Liefere die zusätzlichen Suchpfade des aktuell laufenden Perl-Programms, also die Suchpfade, die über die grundlegenden Suchpfade des Perl_interpreters hinausgehen.
See Also
incPaths() - Alle Modul-Suchpfade
Synopsis
@paths|$pathA = $class->incPaths;Description
Liefere alle Suchpfade des aktuell laufenden Perl-Programms, also die Werte des @INC-Arrays Im Skalar-Kontext liefere eine Referenz auf das Array.
See Also
POD
getPod() - Extrahiere POD-Dokumentation aus Perl-Quelltext
Synopsis
$pod = $this->getPod($file);
$pod = $this->getPod(\$text);
($pod,$encoding) = $this->getPod($file);
($pod,$encoding) = $this->getPod(\$text);Description
Lies den POD-Code aus Datei $file bzw. Quelltext $text und liefere diesen zurück. Ist ein Encoding definiert, dekodiere den gelieferten POD-Code entsprechend. Im Array-Kontext liefere zusätzlich zum POD-Code das Encoding.
getPodValues() - Liefere Content von POD-Abschnitten
Synopsis
$this->getPodValues($file,@keyRef);
$this->getPodValues(\$text,@keyRef);removePod() - Entferne POD-Abschnitte aus Quelltext
Synopsis
$newCode = $this->removePod($code);
$this->removePod(\$code);Description
Entferne alle POD-Abschnitte aus dem Quelltext $code und liefere den resultierenden Quelltext zurück. Wird eine Referenz auf den Quelltext übergeben, erfolgt die Manipulation in-place.
Auf den POD-Abschnitt folgende Leerzeilen (die außerhalb des POD-Code liegen) werden ebenfalls entfernt.
VERSION
1.220
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.