Frank Seitz
and 1 contributors

NAME

Prty::Perl - Erweiterte und abgesicherte Perl-Operationen

BASE CLASS

Prty::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;

Example

    Prty::Perl->autoFlush(*STDOUT);

See Also

perldoc -f select

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.

Example

    Prty::Perl->binmode(*STDOUT,':encoding(utf-8)');

See Also

perldoc -f binmode

print() - Schreibe auf Dateihandle

Synopsis

    Prty::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.

Example

    Prty::Perl->print($fh,"Hello world\n");

See Also

perldoc -f print

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 = Prty::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 = Prty::Perl->perlDoFile($file);

Inhalt Konfigurationsdatei:

    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 = Prty::Perl->packages;
  • Liste in sortierter Form

        @arr = Prty::Perl->packages->sort;
  • Liste, eingeschränkt auf Packages, deren Name einen Regex erfüllt:

        @arr = Prty::Perl->packages->select(qr/patch\d+/);
  • Liste aller Packages unterhalb und einschließlich Package X:

        @arr = Prty::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

    Prty::Perl->classExists('Prty::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

    Prty::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 Prty::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 Prty::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 Prty::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 Prty::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 = Prty::Perl->subClasses('Pkg1')->sort;
  • Liste, eingeschränkt auf Klassen, deren Name einen Regex erfüllt:

        @arr = Prty::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:

        Prty::Perl->createAlias('MyClass',mySub=>\&MyClass1::mySub1);
  • Eintrag einer Closure in die Symboltabelle:

        Prty::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,'Prty::Hash';

getHash() - Liefere Referenz auf Package-Hash

Synopsis

    $ref = $this->getHash($package,$name);

Example

    $ref = Prty::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 = Prty::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 = Prty::Perl->createArray($class,'A');
  • die Referenz kann geblesst werden:

        bless $ref,'Prty::Array';

getArray() - Liefere Referenz auf Package-Array

Synopsis

    $ref = $this->getArray($package,$name);

Example

    $ref = Prty::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 = Prty::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 = Prty::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 = Prty::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 = Prty::Perl->setVar($package,'$','s',\99);
  • Array

        $ref = Prty::Perl->setVar($package,'@','a',\@arr);
  • Hash

        $ref = Prty::Perl->setVar($package,'%','h',\%hash);

getVar() - Liefere Referenz auf Package-Variable

Synopsis

    $ref = $this->getVar($package,$sigil,$name,@opt);

Description

Liefere eine Referenz auf Package-Variable $name vom Typ $sigil ('$','@' oder '%'). Existiert die Variable nicht, liefere undef.

Options

-create => $bool (Default: 0)

Erzeuge Variable, falls sie nicht existiert.

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

Description

Füge Subroutine $ref zu Package $package unter dem Namen $name hinzu. Existiert eine Package-Subroutine mit dem Namen bereits, wird diese ersetzt.

Returns

Referenz auf die Subroutine.

Examples

Definition:

    $ref = Prty::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.

Referenzen

refType() - Liefere Grundtyp der Referenz

Synopsis

    $refType = $class->refType($ref);

Alias

reftype()

Description

Liefere den Grundtyp der Referenz.

Grundtypen sind:

    SCALAR
    ARRAY
    HASH
    CODE
    GLOB
    IO
    REF

isBlessedRef() - Test, ob Referenz geblesst ist

Synopsis

    $bool = $class->isBlessedRef($ref);

Alias

isBlessed()

isArrayRef() - Teste auf Array-Referenz

Synopsis

    $bool = $class->isArrayRef($ref);

isHashRef() - Teste auf Hash-Referenz

Synopsis

    $bool = $class->isHashRef($ref);

isCodeRef() - Teste auf Code-Referenz

Synopsis

    $bool = $class->isCodeRef($ref);

isRegexRef() - Teste auf Regex-Referenz

Synopsis

    $bool = $class->isRegexRef($ref);

Caveats

Wenn die Regex-Referenz umgeblesst wurde, muss sie auf eine Subklasse von Regex geblesst worden sein, sonst schlägt der Test fehl. Aktuell gibt es nicht den Grundtyp REGEX, der von reftype() geliefert würde, sondern eine Regex-Referenz gehört standardmäßig zu der Klasse Regex.

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'

Example

    Prty::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
    .

See Also

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

AUTHOR

Frank Seitz, http://fseitz.de/

COPYRIGHT

Copyright (C) 2017 Frank Seitz

LICENSE

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