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

NAME

Quiq::Path - Dateisystem-Operationen

BASE CLASS

Quiq::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

Konstruktor

new() - Instantiiere Objekt

Synopsis

$p = $class->new;

Returns

Path-Objekt

Description

Instantiiere ein Objekt der Klasse und liefere eine Referenz auf dieses Objekt zurück. Da die Klasse ausschließlich Klassenmethoden enthält, hat das Objekt ausschließlich die Funktion, eine abkürzende Aufrufschreibweise zu ermöglichen.

Datei-Operationen

append() - Hänge Daten an Datei an

Synopsis

$this->append($file,$data,@opt);

Arguments

$file

Pfad der Datei.

$data

Daten, die auf die Datei geschrieben werden.

Options

-lock => $bool (Default: 0)

Locke die Datei während des Schreibens exklusiv.

Description

Hänge Daten $data an Datei $file an.

checkFileSecurity() - Prüfe, ob Datei geschützt ist

Synopsis

$this->checkFileSecurity($file); # nur Owner darf schreiben und lesen
$this->checkFileSecurity($file,$readableByOthers); # nur Owner darf schreiben

Arguments

$file

Datei, deren Rechte geprüft werden.

$readableByOthers

Wenn wahr, dürfen auch andere die Datei lesen.

Description

Prüfe, ob die Datei $file vor unerlaubtem Zugriff geschützt ist. Wenn nicht, wirf eine Exception.

Per Default darf die Datei nur für ihren Owner lesbar und schreibbar sein, muss also die Zugriffsrechte rw------- besitzen.

Ist $readable wahr, darf die Datei von der Gruppe und anderen gelesen werden, darf also die Zugriffsrechte rw-r--r-- besitzen.

compare() - Prüfe, ob Inhalt 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 (1 oder 2), andernfalls falsch (0). Differiert $file2, wird 1 geliefert, existiert $file2 nicht, wird 2 geliefert.

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

Synopsis

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

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.

convertEncoding() - Wandele Character Encoding

Synopsis

$this->convertEncoding($from,$to,$file);

Arguments

$from

Aktuelles Encoding der Datei

$to

Zukünftiges Encoding der Datei

$file

Datei, deren Encoding gewandelt wird

Description

Wandele das Encoding der Datei $file von Encoding $from in Encoding $to. Die Wandelung findet "in place" statt.

copy() - Kopiere Datei

Synopsis

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

Options

-createDir => $bool (Default: 0)

Erzeuge Zielverzeichnis, falls es nicht existiert.

-move => $bool (Default: 0)

Lösche Quelldatei $srcPath nach dem Kopieren.

-overwrite => $bool (Default: 1)

Wenn gesetzt, wird die Zieldatei $destPath überschrieben, falls sie existiert. Andernfalls wird eine Exception geworfen.

-preserve => $bool (Default: 0)

Behalte den Zeitpunkt der letzten Änderung bei.

Description

Kopiere Datei $srcPath nach $destPath. Ist eine Nulloperation, wenn die Ziledatei existiert und identisch zur Quelldatei ist (gleicher Inode).

copyToDir() - Kopiere Datei in Verzeichnis

Synopsis

$class->copyToDir($srcFile,$destDir,@opt);

Options

-createDir => $bool (Default: 0)

Erzeuge Zielverzeichnis, falls es nicht existiert.

-move => $bool (Default: 0)

Lösche Quelldatei $srcPath nach dem Kopieren.

-overwrite => $bool (Default: 1)

Wenn gesetzt, wird die Zieldatei $destPath überschrieben, falls sie existiert. Andernfalls wird eine Exception geworfen.

-preserve => $bool (Default: 0)

Behalte den Zeitpunkt der letzten Änderung bei.

Description

Kopiere Datei $srcPath nach $destPath.

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

Synopsis

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

Arguments

$method

Anzuwendende Pfadoperation:

copy
move -or- rename
link
symlink
$srcPath

(String) Quellpfad

$destPath

(String) Zielpfad

Options

-preserve => $bool (Default: 0)

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

Description

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

copy
move -or- rename
link
symlink

edit() - Bearbeite Datei oder Daten im Editor

Synopsis

$changed = $this->edit($file,@opt);
$changed = $this->edit(\$data,@opt);

Arguments

$file

Datei, die bearbeitet werden soll.

$data

Daten, die bearbeitet werden sollen.

Returns

Boolschen Wert, der anzeigt, ob die Datei oder die Daten verändert wurden.

Description

Öffne Datei $file oder Daten $data im Editor, so dass diese vom Benutzer bearbeitet werden können. Die Methode prüft nach Verlassen des Editors, ob die Datei bzw. Daten geändert wurden. Falls ja, wird der Benutzer gefragt, ob er die Änderungen beibehalten möchte. Falls ja, liefert die Methode wahr, andernfalls falsch.

detectEncoding() - Liefere das Encoding der Datei

Synopsis

$encoding = $class->detectEncoding($path,$altEncoding);

Alias

encoding()

Description

Analysiere Datei $path hinsichtlich ihres Character-Encodings und liefere den Encoding-Bezeichner zurück. Unterschieden werden:

  • ASCII

  • UTF-8

  • UTF-16/32 mit BOM

und $altEncoding. Ist $altEncoding nicht angegeben, wird 'ISO-8859-1' angenommen.

Anmerkung: Die Datei wird zur Zeichensatz-Analyse vollständig eingelesen. Bei großen Dateien kann dies ineffizient sein.

Synopsis

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

Options

-force => $bool (Default: 0)

Lösche die Datei $link, falls sie bereits existiert.

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 $/ = Quiq::Path->newlineStr($file);

while (<$fh>) {
    chomp;
    # Zeile verarbeiten
}

nextFile() - Generiere nächsten Dateinamen

Synopsis

$file = $this->nextFile($name,$n,$ext);

Arguments

$name

Grundname der Datei. Kann leer (Leerstring oder undef) sein, dann besteht der Dateiname nur aus aus der laufenden Nummer.

$n

Anzahl der Stellen der laufenden Nummer.

$ext

Extension der Datei. Kann leer (Leerstring oder undef) sein.

Description

Ermittele und liefere den nächsten Namen einer Datei. Der Dateiname hat den Aufbau

NAME-NNNN.EXT

Die laufende Nummer NNNN (deren Breite durch den zweiten Parameter festgelegt) wird anhand der vorhandenen Dateien im Dateisystem ermittelt und um 1 erhöht.

Example

Es liegt noch keine Datei vor:

$file = Quiq::Path->nextFile('myfile',3,'log');
=>
myfile-001.log

Die Datei mit der höchsten Nummer ist myfile-031.log:

$file = Quiq::Path->nextFile('myfile',3,'log');
=>
myfile-032.log

nextNumber() - Generiere nächste Dateinamen-Nummer

Synopsis

$num = $this->nextNumber($dir,$width);

Arguments

$dir

Verzeichnis mit nummierten Dateien.

$width

Anzahl der Stellen der Nummer.

Returns

Nummer mit der angegebenen Anzahl Stellen, ggf. mit führenden 0en aufgefüllt.

Description

Ermittele und liefere die nächste Nummer eines Verzeichnisses mit nummerierten Dateien. Die Dateinamen haben einen beliebigen Aufbau, müssen aber eine Nummer mit genau $width Stellen besitzen. Die laufende Nummer NNNN (deren Breite durch den zweiten Parameter festgelegt ist) wird anhand der vorhandenen Dateien im Verzeichnis $dir ermittelt und um 1 erhöht.

Example

Es liegt noch keine Datei mit einer dreistelligen Nummer NNN vor:

$num = Quiq::Path->nextNumber($dir,3);
=>
001

Die Datei mit der höchsten dreistelligen Nummer NNN enthält 031:

$num = Quiq::Path->nextNumber($dir,3);
=>
032

read() - Lies Datei

Synopsis

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

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.

-sloppy => $bool (Default: 0)

Existiert die Datei nicht, liefere undef und wirf keine Exception.

Description

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

sha1() - SHA1 Hex Digest

Synopsis

$this->sha1($file);

Arguments

$file

Pfad der Datei.

Description

Ermittele den SHA1 Hex Digest der Datei $file und liefere diesen zurück.

size() - Größe der Datei in Bytes

Synopsis

$size = $this->size($file);

Arguments

$file

Pfad der Datei.

Description

Ermittele die Größe der Datei in Bytes und liefere diesen Wert zurück. Im Unterschied zu

-s $file

führt die Methode eine Tilde-Expansion durch.

tail() - Überwache Datei und gib hinzugefügte Daten kontinuierlich aus

Synopsis

$data = $this->tail($file,@opt);

Arguments

$file

(String) Pfad der Datei.

Options

-offset => $pos (Default: 0)

Beginne die Überwachung bei Datei-Offset $pos.

-sleepInterval => $s (Default: 0.1)

Zeitraum, der zwischen den Prüfungen auf Änderung gewartet wird.

-timeout => $s (Default: überwache unendlich lange)

Beende die Überwachung der Datei, wenn $s Sekunden (Sekundenbruchteile erlaubt, z.B. 0.5) lang keine Änderung an der Datei erfolgt ist. Der Werte sollte größer sein als das Sleep Interval (s. C{-sleepInterval).

Returns

(String) Die während der Überwachung hinzugefügte Daten.

Description

Überwache Datei $file und gib die am Ende hinzugefügten Daten kontinuierlich aus. Die Überwachung endet, wenn der Datiinhalt sich $s Sekunden lang nicht geändert hat (Option --timeout). Liefere die hinzugefügten Daten zurück.

truncate() - Kürze Datei

Synopsis

$this->truncate($file);

Arguments

$file

Pfad der Datei.

Description

Kürze Datei $file auf Länge 0, falls sie existiert. Existiert die Datei nicht, geschieht nichts.

tempFile() - Erzeuge temporäre Datei

Synopsis

$file = $this->tempFile(@opt);
$file = $this->tempFile($data,@opt);

Arguments

Daten, die in die temporäre Datei geschrieben werden.

Options

Siehe Quiq::TempFile->new().

Returns

$file

Tempdatei-Objekt

Description

Erzeuge eine temporäre Datei, beschreibe sie mit den Daten $data und liefere eine Referenz auf das Objekt zurück.

See Also

Quiq::TempFile

unindent() - Entferne Einrückung

Synopsis

$this->unindent($file);

Arguments

$file

Pfad der Datei.

Description

Lies den Inhalt der Datei $file, entferne dessen Einrückung (per Quiq::Unindent->hereDoc) und schreibe den uneingerückten Inhalt auf die Datei zurück. Besitzt der Dateiinhalt keine Einrückung, findet keine Änderung des Dateiinhalts statt.

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.

-lock => $bool (Default: 0)

Setze während des Schreibens einen Exclusive-Lock auf die Datei. Dies kann im Falle von -append sinnvoll sein.

-mode => $mode (Default: keiner)

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

-recursive => $bool (Default: 1)

Erzeuge übergeordnete Verzeichnisse, wenn nötig.

-unindent => $bool (Default: 0)

Wende Quiq::Unindent->trimNl() auf die Daten $data an. Dies ist für inline geschriebenen Text nützlich.

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

count() - Anzahl der Verzeichniseinträge

Synopsis

$n = $this->count($dir);

Arguments

$dir

Pfad des Verzeichnisses.

Returns

Anzahl Verzeichniseinträge (Integer)

Description

Ermittele die Anzahl Einträge des Verzeichnisses $dir und liefere diese zurück. Die Einträge . und .. werden nicht mitgezählt.

deleteContent() - Lösche Inhalt des Verzeichnis

Synopsis

$this->deleteContent($dir);

Arguments

$dir

Pfad des Verzeichnisses

Description

Lösche den Inhalt des Verzeichnisses $dir.

entries() - Liste der Verzeichniseinträge

Synopsis

@paths | $pathA = $this->entries($dir,@opt);

Arguments

$dir

Pfad des Verzeichnisses.

Options

-encoding => $charset (Default: 'utf-8')

Dekodiere die Verzeichniseinträge gemäß Zeichensatz $charset.

Returns

Liste der Verzeichniseinträge (Array of Strings). Im Skalarkontext eine Referenz auf die Liste.

Description

Ermittele die Einträge des Verzeichnisses $dir und liefere diese als Liste zurück. Die Liste umfasst alle Verzeichniseinträge außer "." und "..".

find() - Liefere Pfade innerhalb eines Verzeichnisses

Synopsis

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

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, d.h. sie werden nicht durchsucht. Matcht ein Pfad die Pattern sowohl von -pattern als auch -exclude, hat der exclude-Pattern Vorrang, d.h. die Datei wird ausgeschlossen.

-excludeRoot => $bool (Default: 0)

Nimm das Wurzelverzeichnis $path nicht in die Pfadliste mit auf.

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

-sort = $bool (Default: 0)

Sortiere die Pfade alphanumerisch.

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

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.

findProgram() - Ermittele Pfad zu Programm

Synopsis

$path = $class->findProgram($program);
$path = $class->findProgram($program,$sloppy);

Arguments

$program

Name des Programms.

$sloppy

Wenn wahr, wird keine Exception geworfen, wenn das Programm nicht gefunden wird, sondern undef zurück geliefert.

Returns

Programmpfad (String)

Description

Suche Programm $program über den Suchpfad der Shell und liefere den vollständigen Pfad zurück. Wird das Programm nicht gefunden, wird eine Exception geworfen.

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

Options

-sloppy => $bool (Default: 0)

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

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.

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

Synopsis

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

Arguments

$dir

Pfad des Verzeichnisses

$max

Der Wert, mit dem die Zählung beginnt.

Options

-sloppy => $bool (Default: 0)

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

Description

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

mkdir() - Erzeuge Verzeichnis

Synopsis

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

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.

Returns

(String) Pfad des erzeugten Verzeichnisses.

Description

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

mtimeDir() - Jüngste Modifikationszeit

Synopsis

$mtime = $this->mtimeDir($dir);

Arguments

$dir

Pfad des Verzeichnisses.

Returns

Zeit in Unix Epoch (Integer)

Description

Ermittele über allen Pfaden in und einschließlch $dir den jüngsten Modifikationszeitpunkt (mtime) und liefere diesen zurück.

rmdir() - Lösche Verzeichnis

Synopsis

$class->rmdir($dir);

Arguments

$dir

Pfad des Verzeichnisses

Returns

nichts

Description

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

tempDir() - Erzeuge temporäres Verzeichnis

Synopsis

$dir = $this->tempDir(@opt);

Options

siehe Quiq::TempDir

Returns

$dir

Tempdir-Objekt

Description

Erzeuge ein temporäres Verzeichnis und liefere eine Referenz auf das Objekt zurück.

See Also

Quiq::TempDir

Pfad-Operationen

absolute() - Expandiere Pfad zu absolutem Pfad

Synopsis

$absolutePath = $this->absolute($path);

Alias

realPath()

Description

Ist $path ein relativer Pfad, expandiere ihn zu einem absolutem Pfad und liefere diesen zurück. Ist $path bereits absolut, liefere ihn unverändert.

age() - Alter der letzten Modifikation

Synopsis

$duration = $this->age($path);

Arguments

$path

Pfad.

Returns

Anzahl Sekunden (Integer)

Description

Ermittele das Alter der letzten Modifiktion des Pfad-Objekts in Sekunden und liefere diesen Wert zurück. Existiert der Pfad nicht, wird eine Exception geworfen.

basename() - Grundname eines Pfads

Synopsis

$basename = $class->basename($path,@opt);

Alias

baseName()

Options

-all => $bool (Default: 0)

Entferne alle, nicht nur die erste Extension.

Description

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

basePath() - Pfad ohne Extension

Synopsis

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

Description

Entferne eine etwaig vorhandene Extension von $path und liefere das Resultat zurück.

chmod() - Setze Zugriffsrechte

Synopsis

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

Description

Setze Zugriffsrechte $mode auf Pfad $path.

delete() - Lösche Pfad (rekursiv)

Synopsis

$this->delete($path);

Options

-sloppy => $bool (Default: 0)

Wirf keine Exception, wenn das Verzeichnis oder die Datei nicht gelöscht werden kann.

Description

Lösche den Pfad aus dem Dateisystem, also die Datei oder das Verzeichnis einschließlich Inhalt. Es ist kein Fehler, wenn der Pfad nicht existiert.

dir() - Pfad ohne letzten Bestandteil

Synopsis

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

Returns

String

Description

Entferne den letzten Pfadbestandteil von $path und liefere den Rest zurück. Enthält $path keinen Slash (/), wird ein Leerstring geliefert.

exists() - Prüfe Existenz

Synopsis

$bool = $this->exists($path);

Description

Prüfe, ob Pfad $path existiert und liefere den entsprechenden Wahrheitswert zurück. Die Methode expandiert ~ am Pfadanfang.

expandTilde() - Expandiere Tilde

Synopsis

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

Returns

Pfad (String)

Description

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

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 ('').

filename() - Letzte Pfadkomponente

Synopsis

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

Description

Liefere die letzte Komponente des Pfads.

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

Synopsis

$path = $this->glob($pat);
@paths = $this->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 = $this->mode($path);

Description

Liefere die Zugriffsrechte des Pfads $path.

Examples

  • Permissions oktal anzeigen

    printf "%04o\n",Quiq::Path->mode('/etc/passwd');
0644

  • Prüfen, ob eine Datei für andere lesbar oder schreibbar ist

    if ($mode & 00066) {
    die "ERROR: File ist readable or writable for others\n";
}

moveToDateSubDir() - Verschiebe Pfad in Datums-Subverzeichnis

Synopsis

$this->moveToDateSubDir($path);
$this->moveToDateSubDir($path,$rootDir);

Arguments

$path

Pfad, der verschoben wird.

$rootDir (Default: '.')

Verzeichnis, in dem das Datums-Subverzeichnis angelegt wird.

Options

-verbose => $bool (Default: 1)

Gib Information aus.

Description

Ermitte das Modifikationsdatum des Pfads $path, erzeuge ein Subverzeichnis YYYY-MM-DD in $rootDir und verschiebe den Pfad dorthin. Diese Methode ist nützlich, wenn der Inhalt eines großen Verzeichnisses, der sich nach-und-nach aufgebaut hat, auf Subverzeichnisse aufgeteilt werden soll.

Example

Innerhalb eines Verzeichnisses:

$ perl -MQuiq::Path -E 'Quiq::Path->moveToDateSubDir($_) for glob("*.jpg")'

Mit Zielverzeichnis ("dest"):

$ perl -MQuiq::Path -E 'Quiq::Path->moveToDateSubDir($_,"dest") for glob("src/*.jpg")'

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.

mtimePaths() - Setze mtime inkrementierend

Synopsis

$this->mtimePaths(\@paths,$startTime,$step);

Arguments

@path

Die Pfade, die zu nummerieren sind.

$startTime

Startzeitpunkt im Format "YYYY-MM-DD HH:MM:SS".

$step

Schrittweite in Sekunden.

Example

$ perl -MQuiq::Path -E '$p = Quiq::Path->new; $p->mtimePaths([$p->glob("*.jpg")],"2019-10-08 20:00:00",60)'

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.

newExtension() - Setze eine neue Extension

Synopsis

$newPath = $this->newExtension($path,$ext);

Description

Entferne die bestehende Extension von Pfad $path und füge $ext als neue Extension hinzu. Besitzt $path keine Extension, wird $ext hinzugefügt. Etension $ext kann mit oder ohne Punkt am Anfang angegeben werden.

Synopsis

$path = $class->readlink($symlinkPath);

Alias

readLink()

Description

Liefere den Pfad, auf den der Symlink $symlinkPath zeigt.

removeExtension() - Entferne Extension

Synopsis

$newPath = $class->removeExtension($path);

Description

Entferne die Extension von Pfad $path und liefere den resultierenden Pfad zurück. Besitzt $path keine Extension, sind $path und $newPath identisch.

rename() - Benenne Pfad um

Synopsis

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

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 nicht-existente Verzeichnisse des Zielpfads und entferne leere Verzeichnisse des Quellpfads.

Description

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

Example

Zielpfad erzeugen, Quellpfad entfernen mit -recursive=>1. Ausgangslage: Unterhalb von /tmp existieren weder a noch x.

my $srcPath = '/tmp/a/b/c/d/f';
my $destPath = '/tmp/x/b/c/d/f';
Quiq::Path->write($srcPath,'',-recursive=>1);
Quiq::Path->rename($srcPath,$destPath,-recursive=>1);

Nach Ausführung existiert der der Pfad /tmp/x/b/c/d/f, aber der Pfad /tmp/a nicht mehr.

numberBasePaths() - Nummeriere die (kurzen) Basisnamen der Pfade

Synopsis

$this->numberBasePaths(\@paths,$width,$step,@opts);

Arguments

@path

Die Menge der Pfade.

$width

Die Breite (Anzahl der Stellen) der Nummer.

$step

Die Schrittweite der Nummerierung.

Options

-start => $n (Default: $step)

Startwert.

-verbose => $bool (Default: 0)

Gib Information aus.

Description

Sortiere die (kurzen) Basisnamen der Pfade @paths lexikalisch und nummeriere ihre Basisnamen durch, beginnend mit Nummer $step und Schrittweite $step. Pfade mit dem gleichen (kurzen) Basisnamen aber unterschiedlichen (lange) Extensions erhalten die gleiche Nummer, behalten aber ihre unterschiedliche (lange) Extension.

Example

$ ls
a.jpg
a.xcf
x.jpg

$ perl -MQuiq::Path -E 'Quiq::Path->numberBasePaths([$p->glob("*")],5,10)'

$ ls
00010.jpg
00010.xcf
00020.jpg

numberPaths() - Nummeriere Pfade

Synopsis

$this->numberPaths(\@paths,$width,$step,@opts);

Arguments

@path

Die Pfade, die zu nummerieren sind.

$width

Die Breite (Anzahl der Stellen) der Nummer.

$step

Die Schrittweite der Nummerierung.

Options

-move => [$after,$from,$to]

Ordne alle Pfade von $from bis $to (lexikalisch sortiert) nach der Datei $after ein. Ist $after leer (Leerstring oder undef), werden die Pfade an den Anfang gestellt. Alle Angaben vor der Nummerierung.

-start => $n (Default: $step)

Verwende $n als Startwert.

Description

Nummeriere die Pfade @paths, gemäß der gegebenen Reihenfolge. Der Basisname der jeweiligen Datei/des Directory aus @paths wird hierbei durch eine Nummer der Breite $width ersetzt. Die Extension (sofern vorhanden) bleibt erhalten. Die Nummerierung erfolgt mit Schrittweite $width.

Example

Der Aufruf

$ perl -MQuiq::Path -E '$p = Quiq::Path->new; $p->numberPaths([$p->glob("*")],5,10)'

benennt alle Dateien, gleichgültig wie sie heißen, im aktuellen Verzeichnis um in

00010.EXT
00020.EXT
00030.EXT
...

wobei EXT die Extension ist, die die Datei vorher hatte, d.h. diese bleibt als einziges vom ursprünglichen Dateinamen erhalten.

sameFile() - Prüfe auf identische Datei

Synopsis

$bool = $this->sameFile($path1,$path2);

Arguments

$path1

Erster Pfad

$path2

Zweiter Pfad

Returns

(Integer)

Description

Prüfe, ob die beiden Pfade $path1 und $path2 auf dieselbe Datei (deselben Inode) verweisen. Wenn ja, liefere 1, sonst 0. Funktioniert auch bei Symlinks.

split() - Zerlege Pfad in seine Komponenten

Synopsis

($dir,$file,$base,$ext,$shortBase,$longExt) = $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.

spreadToSubDirs() - Kopiere, bewege, linke oder symlinke Dateien in Subverzeichnisse

Synopsis

$this->%METHOD($method,$destDir,$maxPerDir);

Arguments

$method

Anzuwendende Pfadoperation (siehe Methode duplicate()):

copy
move -or- rename
link
symlink
$destDir

(String) Verzeichnis, in dem die Subverzeichnisse angelegt werden. Das Verzeichnis muss existieren.

$maxPerDir

(Integer) Maximale Anzahl Dateien pro Unterverzeichnis.

Description

Lies Pfade von <STDIN> und verteile die Pfade auf dynamisch erzeugte Subverzeichnisse.

Example

$ find SRCDIR -type f | sort | perl -MQuiq::Path -E 'Quiq::Path->spreadToSubDirs("link",$destDir,100)'

stat() - Statusinformation eines Pfads

Synopsis

@arr = $class->%METHOD($path);

Arguments

$path

Datei- oder Verzeichnispfad.

Returns

Statusinformation (List)

Description

Ermittele die Statusinformation eines Pfads und liefere diese Information als 13-elementige Liste zurück.

Der Aufruf ist äquivalent zu

stat $path

mit dem Unterschied, dass

  • eine Tilde-Expansion stattfindet

  • eine Exception geworfen, wird, wenn $path nicht existiert

See Also

  • perldoc -f stat

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

Options

-createDir => $bool (Default: 0)

Erzeuge nicht-existente Verzeichnisse des Zielpfads.

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

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 ist, diesen so korrigiert, dass er von $symlink aus korrekt ist. Denn der Pfad $path múss als relativer Pfad als Fortsetzung von $symlink gesehen werden.

Example

Quiq::Path->symlinkRelative('a','x')
# x => a

Quiq::Path->symlinkRelative('a/b','x')
# x => a/b

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

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

touch() - Setze Modifikationszeit auf aktuellen Zeitpunkt

Synopsis

$mtime = $this->touch($path);

Arguments

$path

Pfad der Datei oder des Verzeichnisses, dessen mtime gesetzt werden soll.

Returns

Modifikationszeit in Unix Epoch (Integer)

Description

Setze den Zeitpunkt der letzten Modifikation (mtime) des Pfades $path auf den aktuellen Zeitpunkt.

uid() - UID des Owners der Datei

Synopsis

$uid = $this->%METHOD($path);

Description

Ermittele die UID des Owners der Datei und liefere diese zurück.

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.