NAME

Quiq::Perl - Erweiterte und abgesicherte Perl-Operationen

BASE CLASS

Quiq::Object

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

loadClass()

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');
  ==>
  1

loadClass() - 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
     \ /
     Pkg5

Der Aufruf Quiq::Perl->baseClasses('Pkg5') liefert ein Array mit den Elementen

  Pkg3 Pkg2 Pkg1 Pkg4 UNIVERSAL Pkg6 Pkg7

Die 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
    \ /
    Pkg5

Der Aufruf Quiq::Perl->baseClassesISA('Pkg5') liefert ein Array mit den Elementen

  Pkg3 Pkg2 Pkg1 Pkg4

Die 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
    \ /
    Pkg5

Der Aufruf Quiq::Perl->hierarchyISA('Pkg5') liefert ein Array mit den Elementen

  Pkg3 Pkg2 Pkg1 Pkg4 Pkg2 Pkg1

Die 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
    \ /
    Pkg5

Der Aufruf Quiq::Perl->subClasses('Pkg1') liefert ein Array mit den Elementen:

  Pkg2 Pkg3 Pkg4 Pkg5

Die 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

-create => $bool (Default: 0)

Erzeuge Variable, falls sie nicht existiert.

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

AUTHOR

Frank Seitz, http://fseitz.de/

COPYRIGHT

Copyright (C) 2019 Frank Seitz

LICENSE

This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.