/ 
Quiq-1.220
River stage zero No dependents
/ Quiq::Database::Tree

NAME

Quiq::Database::Tree - Baum von Datensätzen

BASE CLASS

Quiq::Hash

DESCRIPTION

Ein Objekt der Klasse repräsentiert eine Menge von Datensätzen, die mittels zweier Attribute $pkColumn und $fkColumn in einer hierarchischen Beziehung zueinander stehen und somit eine Baumstruktur bilden. Die Klasse bietet Methoden, um auf dieser Baumstruktur operieren zu können.

METHODS

Konstruktor

new() - Instantiiere Baum von Datensätzen

Synopsis

$tree = $class->new($tab,$pkColumn,$fkColumn,@opt);

Options

-whenNoParentRow => 'removeRow'|'removeReference'|'throwException' \

(Default: 'throwException') Was getan werden soll, wenn der Parent eines Child-Datensatzes in der Ergebnismenge nicht enthalten ist:

'removeRow'

Entferne den Datensatz aus der Ergebnismenge.

'removeReference'

Setze die Referenz auf NULL (Leerstring). Der Child-Datensatz wird damit logisch zu einem Parent-Datensatz.

'throwException'

Wirf eine Exception.

Die Varianten 'removeRow' und 'removeReference' sind nützlich, wenn die Ergebnismenge nicht alle Sätze enthält, sondern nur eine Teilmenge, z.B. aufgrund einer Selektion mit -limit.

Description

Instantiiere ein Baum-Objekt aus den Datensätzen des ResultSet $tab. Die Datensätze stehen über die Attribute $pkColumn und $fkColumn in einer hierarchischen Beziehung.

Example

Datensätze:

id parent_id name
-- --------- ----
1  NULL      A
2  1         B
3  2         C
4  1         D

Pfade:

A
A/B
A/B/C
A/D

Baum:

A
+-B
| \-C
+-D

Aufruf:

$tree = Quiq::Database::Tree->new($tab,'id','parent_id');

Akzessoren

table() - ResultSet-Objekt

Synopsis

$tab = $tree->table;

Description

Liefere das ResultSet-Objekt, das beim Konstruktor angegeben wurde.

pkIndex() - Primary-Key-Index

Synopsis

$h = $tree->pkIndex;

Description

Liefere eine Referenz auf den Hash, der die Datensätze nach Primary-Key-Index indiziert.

type() - Typ-Bezeichner

Synopsis

$type = $tree->type;

Description

Liefere den (intern generierten) Typ-Bezeichner, für den die Datensatz-Verknüpfung definiert ist.

Objektmethoden

childs() - Kind-Datensätze

Synopsis

@rows|$tab = $tree->childs($row);
@rows|$tab = $tree->childs($pk);

Description

Liefere die Liste der Kind-Datensätze - also der unmittelbar untergeordneten Datensätze - zum Datensatz $row bzw. zum Datensatz mit dem Primärschlüssel $pk. Besitzt der Datensatz keine Kind-Datensätze, ist die Liste leer. Im Skalarkontext liefere ein ResultSet-Objekt mit den Datensätzen.

Example

Aufruf:

@rows = $tree->childs(1);

Resultat:

id parent_id name
-- --------- ----
2  1         B
4  1         D

descendants() - Untergeordnete Datensätze

Synopsis

@rows = $tree->descendants($row);
@rows = $tree->descendants($pk);

Description

Liefere die Liste aller untergeordneten Datensätze zum Datensatz $row bzw. zum Datensatz mit dem Primärschlüssel $pk. Besitzt der Datensatz keine untergeordneten Datensätze, ist die Liste leer. Die Reihenfolge der Datensätze entspricht der einer Tiefensuche. Im Skalarkontext liefere ein ResultSet-Objekt mit den Datensätzen.

Example

Aufruf:

@rows = $tree->descendants(1);

Resultat:

id parent_id name
-- --------- ----
2  1         B
3  2         C
4  1         D

generatePathAttribute() - Erzeuge Pfad-Attribut

Synopsis

$tree->generatePathAttribute($key,$valColumn,$sep);

Description

Füge zu allen Datensätzen das Attribut $key hinzu und setze es auf den Pfad gemäß Datensatz-Attribut $valColumn mit der Trenn-Zeichenkette $sep. Die Methode liefert keinen Wert zurück.

Example

Aufruf:

$tree->generatePathAttribute('path','name','/');

Erweitert alle Datensätze um das Attribut 'path':

id parent_id name path
-- --------- ---- -----
1  NULL      A    A
2  1         B    A/B
3  2         C    A/B/C
4  1         D    A/D

hierarchy() - Datensätze als Hierarchie

Synopsis

@rows|$rowA = $tree->hierarchy(@opt);

Options

-childSort => $sub (Default: sub {0})

Sortierfunktion für die Kind-Datensätze (die Wurzel-Datensätze bleiben in ihrer gegebenen Reihenfolge).

ACHTUNG: Die Sortierfunktion muss mit Prototype ($$) vereinbart werden, damit die Elemente per Parameter und nicht mittels der globalen Variablen $a und $b übergeben werden. Denn die globalen Variablen befinden sich in einem anderen Package als dem, in dem die Sortierfunktion aufgerufen wird. Beispiel:

-childSort => sub ($$) {
    $_[0]->id <=> $_[1]->id;
}
-setTable => $bool (Default: 0)

Setze die hierarchische Reihenfolge auf der zugrunde liegenden Tabelle. D.h. $tree->table->rows() liefert die Datensätze fortan in dieser Reihenfolge.

Description

Liefere die Datensätze der Ergebnismenge in hierarchischer Reihenfolge, also die Kind-Sätze in der Reihenfolge einer Tiefensuche.

level() - Anzahl der übergeordneten Knoten

Synopsis

$level = $tree->level($pk);
$level = $tree->level($row);

lookup() - Datensatz-Lookup

Synopsis

$row = $tree->lookup($pk);
$row = $tree->lookup($row);

Description

Liefere den Datensatz mit dem Primärschlüssel $pk. Wird ein Datensatz $row übergeben, wird dieser unmittelbar zurückgeliefert. Dies ist nützlich, wenn die Methode genutzt wird um eine Variable zu einem Datensatz aufzulösen, die ein Primärschlüssel oder Datensatz sein kann. Die Klasse selbst nutzt die Methode zu diesem Zweck.

parent() - Eltern-Datensatz

Synopsis

$par = $tree->parent($row);
$par = $tree->parent($pk);

Description

Liefere den Eltern-Datensatz zum Datensatz $row bzw. zum Datensatz mit dem Primärschlüssel $pk. Besitzt der Datensatz keinen Eltern-Datensatz, liefere undef.

Example

Aufruf:

$row = $tree->parent(3);

Resultat (ein Datensatz):

id parent_id name
-- --------- ----
2  1         B

path() - Datensatz-Pfad (Datensatz-Liste, Wert-Liste, Zeichenkette)

Synopsis

@rows = $tree->path($row);
@rows = $tree->path($pk);

@values = $tree->path($row,$key);
@values = $tree->path($pk,$key);

$path = $tree->path($row,$key,$sep);
$path = $tree->path($pk,$key,$sep);

Description

Ermittele die Pfad-Datensätze, die Pfad-Werte oder den Pfad des Datensatzes $row bzw. des Datensatzes mit dem Primärschlüssel $pk gemäß der Datensatz-Hierarchie und liefere das Resultat zurück.

Ist Argument $key angegeben, wird die Liste der Werte des Attributs $key geliefert.

Ist zusätzlich Argument $sep angegeben, wird die Liste der Werte mit $sep getrennt zu einer Zeichenkette zusammengefügt.

Examples

  • Pfad als Liste von id-Werten

    Aufruf:

    @values = $tree->path(3,'id');

    Resultat:

    (1,2,3)

    Datensätze und ihre id-Wert-Pfade:

    id parent_id name @values
-- --------- ---- -------
1  NULL      A    (1)
2  1         B    (1,2)
3  2         C    (1,2,3)
4  1         D    (1,4)

  • Pfad als Zeichenkette

    Aufruf:

    $path = $tree->path(3,'name','/');

    Resultat:

    'A/B/C'

    Datensätze und ihre name-Pfade:

    id parent_id name $path
-- --------- ---- -----
1  NULL      A    A
2  1         B    A/B
3  2         C    A/B/C
4  1         D    A/D

rows() - Alle Datensätze (Knoten) des Baums

Synopsis

@rows|$rowA = $tree->rows;

Description

Liefere die Datensätze des Baums. Die Reihenfolge entspricht der Reihenfolge der zugrundeliegenden Tabelle $tab (s. Konstruktor).

roots() - Alle Wurzel-Datensätze

Synopsis

@rows|$rowA = $tree->roots;

Description

Liefere die Liste der Wurzel-Datensätze, also alle Datensätze, die keinen Parent haben. Die Reihenfolge entspricht der Reihenfolge der zugrundeliegenden Tabelle $tab (s. Konstruktor).

siblings() - Geschwister-Datensätze

Synopsis

@rows|$tab = $tree->siblings($row);
@rows|$tab = $tree->siblings($pk);

Description

Liefere die Liste der Geschwister-Datensätze zum Datensatz $row bzw. zum Datensatz mit dem Primärschlüssel $pk. Besitzt der Datensatz keine Geschwister-Datensätze, ist die Liste leer. Im Skalarkontext liefere ein ResultSet-Objekt mit den Datensätzen.

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.