/ 
Quiq-1.220
River stage zero No dependents
/ Quiq::Object

NAME

Quiq::Object - Basisklasse für alle Klassen der Klassenbibliothek

SYNOPSIS

package MyClass;
use base qw/Quiq::Object/;
...

METHODS

Blessen

bless() - Blesse Objekt auf Klasse

Synopsis

$obj = $class->bless($ref);

Description

Objektorientierte Syntax für bless(). Blesse Objekt (Referenz) $ref auf Klasse $class und liefere die geblesste Referenz zurück. Dies geht natürlich nur, wenn $class eine direkte oder indirekte Subklasse von Quiq::Object ist.

Der Aufruf ist äquivalent zu:

$obj = bless $ref,$class;

Example

$hash = Hash->bless({});

rebless() - Blesse Objekt auf eine andere Klasse

Synopsis

$obj->rebless($class);

Description

Blesse Objekt $obj auf Klasse $class um.

Der Aufruf ist äquivalent zu:

bless $obj,$class;

Example

$hash->rebless('MyClass');

Parameterübergabe

parameters() - Argumente und Optionen eines Methodenaufrufs

Synopsis

[1] $this->parameters(\@param,@optRef);
[2] $this->parameters($sloppy,\@param,@optRef);
[3] $argA = $this->parameters($minArgs,$maxArgs,\@param,@optRef);
[4] $argA = $this->parameters($sloppy,$minArgs,$maxArgs,\@param,@optRef);

Arguments

$sloppy

Wirf keine Exception, wenn unerwartete Parameter (also Optionen und Argumente) in @param enthalten sind. Diese Parameter werden aus @param nicht entfernt, bleiben also für eine weitere Verarbeitung stehen.

$minArgs

Mindestanzahl an Argumenten.

$maxArgs

Maximale Anzahl an Argumenten.

@params

Liste der Parameter, typischerweise @_.

@optRef

Liste der erwarteten Optionen zusammen mit Referenzen auf die zugehörigen Optionsvariablen.

Returns

$argA

Referenz auf Array mit mindestens $minArgs und höchstens $maxArgs Argumenten.

Description

Liefere die Argumente und Optionen eines Methodenaufrufs. Die Methode kann eine Klassen- oder Objektmethode sein. Das Argument @params ist typischerweise @_. Parameters() behandelt den Fall sehr effizient, dass @params leer ist, denn dann kehrt parameters() sofort zurück.

[1] Wenn die Methode eine feste Anzahl an Argumenten besitzt und diese von ihr selbst behandelt werden, ist die Nutzung am effizientesten. Denn die Argumente müssen von parameters() dann nicht kopiert werden und wenn der Methodenaufruf ohne Optionen erfolgt, kehrt parameters(), sofort zurück. Beispiel:

sub myMethod {
    my ($this,$arg1,$arg2,$arg3) = splice @_,0,4;

    # Optionen

    my $opt1 = 1;
    my $opt2 = 2;

    $this->parameters(\@_,
        -opt1 => \$opt1,
        -opt2 => \$opt2,
    );

    # ...
}

[2] Wie [1], nur dass keine Exception geworfen wird, wenn unbekannte Parameter übergeben werden. Diese bleiben in @_ stehen. Dies ist nützlich, wenn die Methode zusätzliche Parameter empfängt und diese unbesehen an eine andere Methode weiterleitet. Der Aufruf von parameters() ändert sich zu:

$this->parameters(1,\@_,
    -opt1 => \$opt1,
    -opt2 => \$opt2,
);

[3], [4] Wie [1] bzw. [2], nur dass parameters() zusätzlich die Argumente der Methode behandelt. Dies ist nützlich, wenn die Methode eine variable Anzahl an Argumenten hat. Diese werden von parameters() aus der Parameterliste "herausgefischt" und eine Referenz auf diese Liste zurückgegeben. Beispiel:

sub myMethod {
    my $this = shift;

    # Optionen und Argumente

    my $opt1 = 1;
    my $opt2 = 2;

    $argA = $this->parameters(0,\@_,
        -opt1 => \$opt1,
        -opt2 => \$opt2,
    );
    my ($arg1,$arg2,$arg3,$arg4) = @$argA;

    # ...
}

Exceptions

throw() - Wirf Exception

Synopsis

$this->throw;
$this->throw(@opt,@keyVal);
$this->throw($msg,@opt,@keyVal);

Options

-stdout => $bool (Default: 0)

Erzeuge die Meldung auf STDOUT (statt STDERR), wenn -warning => 1 gesetzt ist.

-stacktrace => $bool (Default: 1)

Ergänze den Exception-Text um einen Stacktrace.

-warning => $bool (Default: 0)

Wirf keine Exception, sondern gib lediglich eine Warnung aus.

Description

Wirf eine Exception mit dem Fehlertext $msg und den hinzugefügten Schlüssel/Wert-Paaren @keyVal. Die Methode kehrt nur zurück, wenn Option -warning gesetzt ist.

Sonstiges

addMethod() - Erweitere Klasse um Methode

Synopsis

$this->addMethod($name,$ref);

Description

Füge Codereferenz $ref unter dem Namen $name zur Klasse $this hinzu. Existiert die Methode bereits, wird sie überschrieben.

Example

MyClass->addMethod(myMethod => sub {
    my $self = shift;
    return 4711;
});

classFile() - Pfad der .pm-Datei

Synopsis

$dir = $this->classFile;

Description

Ermitte den Pfad der .pm-Datei der Klasse $this und liefere diesen zurück. Die Klasse muss bereits geladen worden sein.

Example

$path = Quiq::Object->classFile;
==>
<PFAD>Quiq/Object.pm

methodName() - Liefere Namen der ausgeführten Methode

Synopsis

$name = $this->methodName;

Returns

$name

(String) Methodenname

Description

Ermittele den Namen der ausgeführten Methode und liefere diesen zurück.

this() - Liefere Klassenname und Objektreferenz

Synopsis

($class,$self,$isClassMethod) = Quiq::Object->this($this);
$class = Quiq::Object->this($this);

Arguments

$this

Der erste Parameter der Methode

Returns

$class

(String) Klassenname

$self

(Referenz) Objektreferenz.

$isClassMethod

(Boolean) Zeigt an, ob die Methode als Klassenmethode gerufen wurde.

Description

Liefere Klassenname und/oder die Objektreferenz zu Parameter $this und zeige auf dem dritten Rückgabewert an, ob die Methode als Klassen- oder Objektmethode gerufen wurde.

Ist $this ein Klassenname (eine Zeichenkette) liefere den Namen selbst, als Objektreferenz undef und als dritten Rückgabewert

  1. Ist $this eine Objektreferenz, liefere den Klassennamen zur

Objektreferenz, die Objektreferenz selbst und als dritten Rückgabewert 0.

Im Skalarkontext liefere nur den Klassennamen.

Example

  • Klassen- sowie Objektmethode:

    sub myMethod {
    my ($class,$self) = Quiq::Object->this(shift);

    if ($self) {
        # Aufruf als Objektmethode
    }
    else {
        # Aufruf als Klassenmethode
    }
}

  • Klassenmethode, die als Objektmethode gerufen werden kann:

    sub mymethod {
    my $class = Quiq::Object->this(shift);
    ...
}

  • Objektmethode, die als Klassenmethode gerufen werden kann:

    sub myMethod {
    my ($class,$self,$isClassMethod) = Quiq::Object->this(shift);

    $self = $class->new(@_);

    # Ab hier ist mittels $self nicht mehr feststellbar,
    # ob die Methode als Klassen- oder Objektmethode gerufen wurde.
    # Die Variable $isclassmethod zeigt es an.

    $self->specialMethod if $isClassMethod;
    ...
}

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.