Frank Seitz
and 1 contributors

NAME

Prty::Path - Dateisystem-Operationen

BASE CLASS

Prty::Object

DESCRIPTION

Die Klasse definiert alle grundlegenden (link, mkdir, rename, symlink usw.) und komplexen (copy, glob, find usw.) Dateisystem-Operationen. Eine Dateisystem-Operation ist eine Operation auf einem Pfad.

METHODS

Datei-Operationen

append() - Hänge Daten an Datei an

Synopsis

    $class->append($file,$data);

Description

Hänge Daten $data an Datei $file an. Die Methode liefert keinen Wert zurück.

compare() - Prüfe, ob Inhalt der Dateien differiert

Synopsis

    $bool = $class->compare($file1,$file2);

Description

Prüfe, ob der Inhalt der Dateien $file1 und $file2 differiert. Ist dies der Fall, liefere wahr, andernfalls falsch.

compareData() - Prüfe, ob Datei-Inhalt von Daten differiert

Synopsis

    $bool = $class->compareData($file,$data);

Alias

different()

Description

Prüfe, ob der Inhalt der Datei $file von $data differiert. Ist dies der Fall, liefere wahr, andernfalls falsch. Die Datei $file muss nicht existieren.

copy() - Kopiere Datei

Synopsis

    $class->copy($srcPath,$destPath,@opt);

Description

Kopiere Datei $srcPath nach $destPath.

Options

-createDir => $bool (Default: 0)

Erzeuge Zielverzeichnis, falls es nicht existiert.

-preserve => $bool (Default: 0)

Behalte den Zeitpunkt der letzten Änderung bei.

duplicate() - Kopiere, bewege, linke oder symlinke Datei

Synopsis

    $class->duplicate($method,$srcPath,$destPath,@opt);

Description

Mache Datei $srcPath nach Methode $method unter $destPath verfügbar. Werte für $method:

    copy
    move -or- rename
    link
    symlink

Options

-preserve => $bool (Default: 0)

Behalte den Zeitpunkt der letzten Änderung bei (nur bei 'copy' relevant).

Synopsis

    $class->link($path,$link);

Description

Erzeuge einen Hardlink $link auf Pfad $path. Die Methode liefert keinen Wert zurück.

newlineStr() - Ermittele Zeilentrenner

Synopsis

    $nl = $class->newlineStr($file);

Description

Ermittele den physischen Zeilentrenner (CR, LF oder CRLF) der Datei $file und liefere diesen zurück. Wird kein Zeilentrenner gefunden, liefere undef.

Example

    local $/ = Prty::Path->newlineStr($file);
    
    while (<$fh>) {
        chomp;
        # Zeile verarbeiten
    }

read() - Lies Datei

Synopsis

    $data = $class->read($file,@opt);

Description

Lies den Inhalt der Datei und liefere diesen zurück.

Options

-autoDecode => $bool (Default: 0)

Auto-Dekodiere die gelesenen Daten als Text und entscheide selbständig, ob es sich um UTF-8 oder ISO-8859-1 Encoding handelt.

-decode => $encoding (Default: undef)

Decodiere die Datei gemäß dem Encoding $encoding.

-delete => $bool (Default: 0)

Lösche Datei nach dem Lesen.

-maxLines => $n (Default: 0)

Lies höchstens $n Zeilen. Die Zählung beginnt nach den Skiplines (s. Option -skipLines). 0 bedeutet, lies alle Zeilen.

-skip => $regex (Default: keiner)

Überlies alle Zeilen, die das Muster $regex erfüllen. $regex wird als Zeichenkette angegeben. Die Option kann beispielsweise dazu verwendet werden, um Kommentarzeilen zu überlesen.

-skipLines => $n (Default: 0)

Überlies die ersten $n Zeilen.

write() - Schreibe Datei

Synopsis

    $class->write($file); # leere Datei
    $class->write($file,$data,@opt);
    $class->write($file,\$data,@opt);

Options

-append => $bool (Default: 0)

Öffne die Datei im Append-Modus, d.h. hänge die Daten an die Datei an.

-encode => $encoding (Default: keiner)

Encodiere $data gemäß dem Encoding $encoding.

-mode => $mode (Default: keiner)

Setze die Permissions der Datei auf $mode. Beispiel: -mode=>0775

-recursive => $bool (Default: 1)

Erzeuge übergeordnete Verzeichnisse, wenn nötig.

writeIfDifferent() - Schreibe Datei, wenn Inhalt differiert

Synopsis

    $class->writeIfDifferent($file,$data);

writeInline() - Schreibe Inline-Daten in Datei

Synopsis

    $class->writeInline($file,<<'__EOT__',@opt);
    DATA
    ...
    __EOT__

Verzeichnis-Operationen

find() - Liefere Pfade innerhalb eines Verzeichnisses

Synopsis

    @paths|$pathA = $class->find($path,@opt);

Description

Finde alle Dateien und Verzeichnisse unterhalb von und einschließlich Verzeichnis $path und liefere die Liste der gefundenen Pfade zurück. Im Skalarkontext liefere eine Referenz auf die Liste.

Ist $dir Null (Leerstring oder undef), wird das aktuelle Verzeichnis ('.') durchsucht.

Die Reihenfolge der Dateien ist undefiniert.

Options

-decode => $encoding

Dekodiere die Dateinamen gemäß dem angegebenen Encoding.

-exclude => $regex (Default: keiner)

Schließe alle Pfade aus, die Muster $regex erfüllen. Directories werden gepruned. Matcht ein Pfad die Pattern sowohl von -pattern als auch -exclude, hat der exclude-Pattern Vorrang, d.h. die Datei wird ausgeschlossen.

-follow => $bool (Default: 1)

Folge Symbolic Links.

-leavesOnly => $bool (Default: 0)

Liefere nur Pfade, die kein Anfang eines anderen Pfads sind. Anwendungsfall: nur die Blatt-Verzeichnisse eines Verzeichnisbaums.

-olderThan => $seconds (Default: 0)

Liefere nur Dateien, die vor mindestens $seconds zuletzt geändert wurden. Diese Option ist z.B. nützlich, um veraltete temporäre Dateien zu finden, um sie zu löschen.

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

Filehandle, auf die Ausgabe im Falle von -verbose=>1 geschrieben werden.

-pattern => $regex (Default: keiner)

Schränke die Treffer auf jene Pfade ein, die Muster $regex erfüllen. Matcht ein Pfad die Pattern sowohl von -pattern als auch -exclude, hat der exclude-Pattern Vorrang, d.h. die Datei wird ausgeschlossen.

-slash => $bool (Default: 0)

Füge einen Slash (/) am Ende von Directory-Namen hinzu.

-sloppy => $bool (Default: 0)

Wirf keine Exception, wenn $path nicht existiert, sondern liefere undef bzw. eine leere Liste.

-subPath => $bool (Default: 0)

Liefere nur den Subpfad, entferne also $path am Anfang.

-testSub => sub {} (Default: undef)

Subroutine, die den Pfad als Argument erthält und einen boolschen Wert liefert, der angibt, ob der Pfad zur Ergebnismenge gehört oder nicht.

-type => 'd' | 'f' | undef (Default: undef)

Liefere nur Verzeichnisse ('d') oder nur, was kein Verzeichnis ist ('f'), oder liefere alles (undef).

-verbose => $bool (Default: 0)

Schreibe Meldungen auf Ausgabe-Handle (s. Option -outHandle).

maxFilename() - Liefere den lexikalisch größten Dateinamen

Synopsis

    $max = $class->maxFilename($dir);

Description

Liefere den lexikalisch größten Dateinamen aus Verzeichnis $dir.

maxFileNumber() - Liefere den numerisch größten Dateinamen

Synopsis

    $max = $class->maxFileNumber($dir,@opt);

Description

Liefere den numerisch größten Dateinamen aus Verzeichnis $dir. Die Methode ist nützlich, wenn die Dateinamen mit einer Zahl NNNNNN beginnen und man die Datei mit der größten Zahl ermitteln möchte um einer neu erzeugten Datei die nächsthöhere Nummer zuzuweisen.

Options

-sloppy => $bool (Default: 0)

Wirf keine Exception, wenn ein Dateiname nicht mit einer Nummer beginnt.

mkdir() - Erzeuge Verzeichnis

Synopsis

    $class->mkdir($dir,@opt);

Description

Erzeuge Verzeichnis. Existiert das Verzeichnis bereits, hat der Aufruf keinen Effekt. Kann das Verzeichnis nicht angelegt werden, wird eine Exception ausgelöst.

Options

-createParent => $bool (Default: 0)

Erzeuge nicht den angegebenen Pfad, sondern den Parent-Pfad. Dies ist nützlich, wenn der übergebene Pfad ein Dateiname ist, dessen Verzeichnis bei Nicht-Existenz erzeugt werden soll. Impliziert -recursive=>1, wenn nicht explizit -recursive=>0 gesetzt ist.

-forceMode => $mode (Default: keiner)

Setze Verzeichnisrechte auf $mode ohne Berücksichtigung der umask des Prozesses.

-mode => $mode (Default: 0775)

Setze Verzeichnisrechte auf $mode mit Berücksichtigung der umask des Prozesses.

-mustNotExist => $bool (Default: 0)

Das Verzeichnis darf nicht existieren. Wenn es existiert, wird eine Exception geworfen.

-recursive => 0 | 1 (Default: 0)

Erzeuge übergeordnete Verzeichnisse, wenn nötig.

rmdir() - Lösche Verzeichnis

Synopsis

    $class->rmdir($dir);

Description

Lösche Verzeichnis $dir, falls dieses leer ist. Kann das Verzeichnis nicht gelöscht werden, wird eine Exception ausgelöst.

Arguments

$dir

Pfad des Verzeichnisses

Returns

nichts

Pfad-Operationen

basename() - Grundname eines Pfads

Synopsis

    $basename = $class->basename($path);

Alias

baseName()

Description

Liefere den Grundnamen des Pfads, d.h. ohne Pfadanfang und Extension.

chmod() - Setze Zugriffsrechte

Synopsis

    $class->chmod($path,$mode);

Description

Setze Zugriffsrechte $mode auf Pfad $path.

delete() - Lösche Pfad (rekursiv)

Synopsis

    $class->delete($path);

Description

Lösche den Pfad aus dem Dateisystem, also entweder die Datei oder das Verzeichnis einschließlich Inhalt. Es ist kein Fehler, wenn der Pfad im Dateisystem nicht existiert. Existiert der Pfad und kann nicht gelöscht werden, wird eine Exception ausgelöst. Die Methode liefert keinen Wert zurück.

expandTilde() - Expandiere Tilde

Synopsis

    $path = $class->expandTilde($path);

Description

Ersetze eine Tilde am Pfadanfang durch das Home-Verzeichnis des Benutzers und liefere den resultierenden Pfad zurück.

Returns

Pfad (String)

extension() - Extension des Pfads

Synopsis

    $ext = $class->extension($path);

Description

Ermittele die Extension des Pfads $path und liefere diese zurück. Besitzt der Pfad keine Extension, liefere einen Leerstring ('').

glob() - Liefere Pfade, die Shell-Pattern erfüllen

Synopsis

    $path = $class->glob($pat);
    @paths = $class->glob($pat);

Description

Liefere die Pfad-Objekte, die Shell-Pattern $pat erfüllen. Im Skalarkontext liefere den ersten Pfad, der dann der einzig erfüllbare Pfad sein muss, sonst wird eine Exception geworfen.

isEmpty() - Prüfe, ob Datei oder Verzeichnis leer ist

Synopsis

    $bool = $class->isEmpty($path);

mode() - Liefere Zugriffsrechte

Synopsis

    $mode = $class->mode($path);

Description

Liefere die Zugriffsrechte des Pfads $path.

mtime() - Setze/Liefere Modifikationszeit

Synopsis

    $mtime = $class->mtime($path);
    $mtime = $class->mtime($path,$mtime);

Description

Liefere die Zeit der letzten Modifikation des Pfads $path. Wenn der Pfad nicht existiert, liefere 0.

Ist ein zweiter Parameter $mtime angegeben, setze die Zeit auf den angegebenen Wert. In dem Fall muss der Pfad existieren.

newer() - Vergleiche Modifikationsdatum zweier Pfade

Synopsis

    $bool = $class->newer($path1,$path2);

Description

Prüfe, ob Pfad $path1 ein jüngeres Modifikationsdatum besitzt als $path2. Ist dies der Fall, liefere 1, andernfalls 0. Liefere ebenfalls 1, wenn Datei $path2 nicht existiert. Pfad $path1 muss existieren.

Pfad $path2 kann eine Zeichenkette oder ein Pfad-Objekt sein.

Dieser Test ist nützlich, wenn $path2 aus $path1 erzeugt wird und geprüft werden soll, ob eine Neuerzeugung notwendig ist.

rename() - Benenne Pfad um

Synopsis

    $class->rename($oldPath,$newPath,@opt);

Description

Benenne Pfad $oldPath in $newPath um. Die Methode liefert keinen Wert zurück.

Options

-overwrite => $bool (Default: 1)

Wenn gesetzt, wird die Datei $newPath überschrieben, falls sie existiert. Wenn nicht gesetzt, wird eine Exception geworfen, falls sie existiert.

-recursive => 0 | 1 (Default: 0)

Erzeuge übergeordnete Verzeichnisse, wenn nötig.

split() - Zerlege Pfad in seine Komponenten

Synopsis

    ($dir,$file,$base,$ext) = $class->split($path);

Description

Zerlege Pfad in die vier Komponenten Verzeichnisname, Dateiname, Basisname (= Dateiname ohne Extension) und Extension und liefere diese zurück.

Für eine Komponente, die nicht existiert, wird ein Leerstring geliefert.

Synopsis

    $class->symlink($path,$symlink);

Description

Erzeuge Symlink $symlink für Pfad $path. Die Methode liefert keinen Wert zurück.

Synopsis

    $class->symlinkRelative($path,$symlink,@opt);

Description

Erzeuge einen Symlink $symlink, der auf den Pfad $path verweist. Die Methode liefert keinen Wert zurück.

Die Methode zeichnet sich gegenüber der Methode symlink() dadurch aus, dass sie, wenn $path ein relativer Pfad zum ist, diesen so korrigiert, dass er von Pfad auch von $symlink aus korrekt ist. Denn der Pfad $path ist als relativer Pfad die Fortsetzung von $symlink!

Options

-dryRun => $bool (Default: 0)

Führe das Kommando nicht aus. Speziell Verbindung mit -verbose=>1 sinnvoll, um Code zu testen.

-verbose => $bool (Default: 0)

Gib Informationen über die erzeugten Symlinks auf STDOUT aus.

Example

    Prty::Path->symlinkRelative('a','x')
    # x => a
    
    Prty::Path->symlinkRelative('a/b','x')
    # x => a/b
    
    Prty::Path->symlinkRelative('a/b','x/y')
    # x/y => ../a/b
    
    Prty::Path->symlinkRelative('a/b','x/y/z')
    # x/y/z => ../../a/b

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.