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

NAME

Quiq::DestinationTree - Verwalte Zielbaum eines Datei-Generators

BASE CLASS

Quiq::Object

SYNOPSIS

use Quiq::DestinationTree;

$dt = Quiq::DestinationTree->(@dirs);
...
# Dateien und Verzeichnisse erzeugen
$dt->addFile($file,$content);
$dt->addDir($dir);
...
# Überzählige Dateien und Verzeichnisse entfernen
$dt->cleanup;

DESCRIPTION

Die Klasse verwaltet die Dateien und Unterverzeichnisse von einem oder mehreren Zielverzeichnissen. Sie ist für Dateigeneratoren gedacht, die den Inhalt ihrer Zielverzeichnisse komplett kontrollieren.

METHODS

Konstruktor

new() - Konstruktor

Synopsis

$tree = $class->new(@dirs,@opt);

Options

-cleanup => $bool (Default: 0)

Entferne alle Dateien und Verzeichnisse, die generiert wurden.

Diese Option ist für ein "make clean" nützlich. Im Unterschied zu einem $tree->cleanup() direkt nach Objektinstantiierung, werden hierbei Dateien, die mit -writeInitially=>1 erzeugt wurden, nur dann gelöscht, wenn sie nicht modifiziert wurden. Wurden sie modifiziert, bleiben sie erhalten.

-dryRun => $bool (Default: 0)

Ändere nichts, zeige die Operationen nur an.

-exclude => $regex (Default: keiner)

Schließe alle Dateien, die Regex $regex erfüllen von der Betrachtung aus. D.h. diese werden vom Nutzer der Klasse nicht verwaltet (weder erzeugt noch entfernt).

-files => \@files (Default: [])

Liste von Einzeldateien. Beispiel:

-files=>[glob '*_1.sql'],
-force => $bool (Default: 0)

Forciere das Schreiben aller Dateien, auch wenn ihr Inhalt nicht differiert.

-include => $regex (Default: keiner)

Berücksichtige nur Dateien, die Regex $regex erfüllen, alle anderen werden von der Klasse nicht verwaltet (weder erzeugt noch entfernt).

-inHandle => $fh (Default: \*STDIN)

Filehandle, von der Benutzereingaben gelesen werden.

-language => 'de'|'en' (Default: 'de')

Sprache für die Kommunikation mit dem Benutzer.

-prefix => $str (Default: '')

Setze Zeichenkette $str an den Anfang jeder Änderungsmeldung. Beispiel: -prefix=>'* '

-quiet => $bool (Default: 0)

Schreibe keine Meldungen nach STDERR.

-outHandle => $fh (Default: \*STDOUT)

Filehandle, auf die Ausgaben geschrieben werden.

Description

Instantiiere ein Dateibaumobjekt über den Verzeichnissen @dirs und liefere eine Referenz auf dieses Objekt zurück. Die Verzeichnisse in @dirs müssen nicht existieren. Hat ein Verzeichnis die Form "DIR/*" wird nicht rekursiv in DIR abgestiegen, sondern nur die Dateien (nicht die Verzeichnisse) in DIR werden verwaltet.

Objektmethoden

addDir() - Füge Verzeichnis zum Dateibaum hinzu

Synopsis

$bool = $tree->addDir($dir);

Description

Füge Verzeichnis $dir zum Dateibaum hinzu. Die Methode liefert 1, wenn das Verzeichnis effektiv erzeugt wurde (s.u.) oder 0, wenn dies nicht der Fall war.

Das Verzeichnis wird effektiv nur erzeugt, wenn es noch nicht existiert. In dem Fall schreibt die Methode eine entsprechende Meldung auf den Ausgabekanal und liefert als Returnwert 1.

Der Rückgabewert kann benutzt werden, um im Falle der Verzeichniserzeugung weitere Aktionen auszuführen, wie z.B. das Setzen von Verzeichnisrechten.

paths() - Liefere die Liste der Pfade

Synopsis

@paths | $pathA = $tree->paths;

Description

Liefere die Liste der Pfade, die zu den Zielverzeichnissen gehören.

  • Die Reihenfolge ist undefiniert.

  • Die Liste enthält sowohl Verzeichnisse also auch Dateien.

Sortierung herstellen:

@paths = sort $tree->paths;

Nur Dateien erhalten:

@paths = grep {!-d} $tree->paths;

addFile() - Füge Datei zum Dateibaum hinzu

Synopsis

$bool = $tree->addFile($file,$data,@opt);
$bool = $tree->addFile($file,\$data,@opt);
$bool = $tree->addFile($file,@opt);
$bool = $tree->addFile($file,
    -generate => $bool,
    -onGenerate => sub {
        ...
        return $data;
    },
    @opt
);

Options

-encoding => $encoding (Default: undef)

Encodiere/decodiere die Daten mit Encoding $encoding.

-force => $bool (Default: 0)

Forciere das Schreiben der Datei ohne den Dateiinhalt zu vergleichen. Die Option ist nützlich, wenn der Aufrufer bereits festgestellt hat, dass eine Differenz besteht.

-generate => $bool (Default: 0)

Rufe die onGenerate-Subroutine auf, um den Dateiinhalt zu generieren.

-onGenerate => sub { ... } (Default: undef)

Die Subroutine generiert und liefert den Inhalt der Datei. Sie wird aufgerufen, wenn Argument $data nicht definiert ist und die Datei nicht existiert oder Option -generate wahr ist.

-onUpdate => sub { ... } (Default: undef)

Führe Subroutine aus, bevor Datei $file geschrieben wird.

-quiet => $bool (Default: 0)

Unterdrücke Ausgabe der Meldung.

-skipEmptyFiles => $bool

Übergehe Dateien mit leerem Inhalt.

-writeInitially => $bool (Default: 0)

Schreibe Datei nur, wenn sie nicht existiert.

Diese Option ist nützlich, wenn von einer Datei ein anfängliches Muster erzeugt werden soll, das anschließend manuell bearbeitet werden kann. Die manuell bearbeitete Datei soll danach natürlich nicht mehr vom Muster überschieben werden.

Description

Füge Datei $file mit dem Inhalt $data zum Dateibaum hinzu. Die Methode liefert 0, wenn die Datei nicht geschrieben wurde, 1, wenn die Datei existiert hat und geschrieben wurde, 2, wenn die Datei neu erzeugt wurde.

Ist $data undef wird die Datei nicht geschrieben, bleibt aber weiter bestehen. Dies ist nützlich, wenn es teuer ist, den Inhalt der Datei zu generieren, und bekannt ist, dass sich am Inhalt nichts geändert hat.

Die Datei wird effektiv geschrieben, wenn sie nicht existiert oder der Inhalt differiert. In dem Fall schreibt die Methode eine entsprechende Meldung nach STDERR und liefert als Returnwert 1.

Der Rückgabewert kann benutzt werden, um im Falle des Schreibens der Datei weitere Aktionen auszuführen, wie z.B. das Setzen von Dateirechten.

obsoletePaths() - Liste der überzähligen Pfade

Synopsis

@arr | $arr = $tree->obsoletePaths;

Description

Die Pfade werden lexikalisch absteigend sortiert, so dass der Inhalt eines Verzeichnisses typischerweise vor dem Verzeichnis kommt. Dies ist aber nicht garantiert, da Punkt "." und Bindestrich "-" vor dem Verzeichnistrenner "/" kommen.

removePath() - Lösche Datei oder Verzeichnis aus Baum

Synopsis

$bool = $tree->removePath($path);

Description

Lösche Datei oder Verzeichnis $path aus dem Zielbaum. Liefere 1, wenn die Löschung durchgeführt wurde, andernfalls 0.

Im Falle eines Verzeichnisses wird die Löschung nur durchgeführt, wenn das Verzeichnis leer ist. Dateien werden grundsätzlich gelöscht.

cleanup() - Entferne überzählige Pfade aus dem Zielbaum

Synopsis

$n|@paths = $tree->cleanup;
$n|@paths = $tree->cleanup($ask);
$n|@paths = $tree->cleanup($ask,\$timer);

Returns

Anzahl oder Liste der gelöschten Pfade (Skalarkontext/Arraykontext)

Description

Entferne alle Dateien und Verzeichnisse aus dem Zielbaum, die obsolet geworden sind, die seit Objekt-Instantiierung also nicht via $tree->addFile() oder $tree->addDir() angelegt wurden.

Ist der Parameter $ask angegeben und wahr, wird vor der Löschung eine Rückfrage auf STDERR gestellt, ob die Löschung wirklich erfolgen soll. Wird diese nicht mit 'y' beantwortet (auf STDIN), findet kein Löschen statt und die Methode liefert 0.

Ist ferner der Parameter $timer angegeben, wird die Antwortzeit des Benutzers auf dessen Wert aufaddiert.

close() - Schließe Zielbaumvergleich ab

Synopsis

$dt->close;

Description

Schließe Zielbaumvergeleich ab. Nach Aufruf kann die Objektreferenz nicht mehr verwendet werden. Die Methode liefert keinen Wert zurück.

getText() - Liefere Übersetzung

Synopsis

$text = $tree->getText($textDe);

Returns

Übersetzten Text (String)

Description

Liefere die Übersetzung zum deutschen Text $textDe.

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.