/ 
Quiq-1.222
River stage zero No dependents
/ Quiq::FileHandle

NAME

Quiq::FileHandle - Datei-Handle

BASE CLASS

Quiq::Object

SYNOPSIS

Datei schreiben:

my $fh = Quiq::FileHandle->new('>',$path);
$fh->print("Test\n");
$fh->close;

Datei lesen:

my $fh = Quiq::FileHandle->new('<',$path);
while (<$fh>) {
    print;
}
$fh->close;

Programm darf nur einmal laufen:

my $fh = eval{Quiq::FileHandle->new('<',$file,-lock=>'EXNB')};
if ($@) {
    exit 5;
}

Zähler-Datei mit Locking:

my $fh = Quiq::FileHandle->new('+>>',$file,-lock=>'EX');
$fh->seek(0);
my $count = <$fh> || "0\n";
chomp $count;
$fh->truncate;
$fh->print(++$count,"\n");

# Der Lock bleibt so lange bestehen bis $fh aus dem Scope geht

Siehe auch Quiq::LockedCounter.

DESCRIPTION

Ein Objekt der Klasse repräsentiert eine Dateihandle, über die Daten gelesen oder geschrieben werden können.

METHODS

Konstruktor

new() - Öffne Dateihandle

Synopsis

$fh = $class->new($mode,$path,@opt);
$fh = $class->new($globRef,@opt);
$fh = $class->new('<'); # Lesen von STDIN
$fh = $class->new('>'); # Schreiben nach STDOUT

Alias

open()

Options

-createDir => $bool (Default: 0)

Erzeuge den Verzeichnispfad einer Datei, die geschrieben wird, falls er nicht existiert.

-lock => 'EX'|'SH'|'EXNB'|'SHNB' (Default: kein Lock)

Locke die Dateihandle nach dem Öffnen im angegebenen Lock-Modus. Folgende Lockmodes werden unterschieden: 'SH' (shared lock), 'EX' (exclusive lock). Durch den Zusatz 'NB' (also Lockmode 'SHNB' der 'EXNB') wird die Operation "non blocking" ausgeführt, d.h. wenn der Lock nicht sofort erworben werden kann, wird eine Exception ausgelöst.

Wurde die Datei vom Konstruktor geöffnet, schließt er sie, wenn der Lock nicht erworben werden kann. Andernfalls bleibt die Dateihandle geöffnet.

Description

Instantiiere Dateihandle-Objekt und liefere eine Referenz auf dieses Objekt zurück.

Examples

Filehandle-Objekt für STDOUT:

$fh = Quiq::FileHandle->new(\*STDOUT);

Lesen von STDIN:

$fh = $class->new('<');
$fh = $class->new('<','');
$fh = $class->new('<','-');

Schreiben nach STDOUT:

$fh = $class->new('>');
$fh = $class->new('>','');
$fh = $class->new('>','-');

close() - Schließe Dateihandle

Synopsis

$fh->close;

Alias

destroy()

Description

Schließe Dateihandle. Die Methode liefert keinen Wert zurück. Nach Aufruf der Methode ist die Objektreferenz ungültig.

DESTROY() - Schließe Dateihandle

Synopsis

$fh->DESTROY;

Description

Schließe Dateihandle. Die Methode liefert keinen Wert zurück.

Lesen

read() - Lies Daten von Dateihandle

Synopsis

$data = $fh->read($n);

Description

Lies die nächste die nächsten $n Zeichen von Dateihandle $fh und liefere diese zurück. Ist das Dateiende erreicht, liefere undef.

readData() - Lies Daten mit Längenangabe

Synopsis

$data = $fh->readData;

Description

Lies Daten in der Repräsentation

<LENGTH><DATA>

und liefere <DATA> zurück. <LENGTH> ist ein 32 Bit Integer und <DATA> sind beliebige Daten mit <LENGTH> Bytes Länge.

Wurden die Daten in einem Encoding wie UTF-8 geschrieben, müssen diese nach dem Einlesen anscheinend nicht dekodiert werden. Warum?

Wurden die Daten $data in einem Encoding wie UTF-8 geschrieben, müssen diese anschließend decodiert werden mit

Encode::decode('utf-8',$data);

Auf der FileHandle $fh das Encoding zu definieren, ist nicht richtig, da die Längenangabe diesem Encoding nicht unterliegt!

See Also

writeData()

readLine() - Lies Zeile von Dateihandle

Synopsis

$line = $fh->readLine;

Description

Lies die nächste Zeile von Dateihandle $fh und liefere diese zurück. Schlägt dies fehl, wirf eine Exception.

readLines() - Lies mehrere Zeilen von Dateihandle

Synopsis

@lines|$lineA = $fh->readLines($n);

Description

Lies die nächsten $n Zeilen von Dateihandle $fh und liefere diese als Liste zurück. Der Zeilentrenner am Ende jeder Zeile wird entfernt. Im Skalarkontext liefere eine Referenz auf die Liste, wenn Zeilen gelesen wurden, sonst undef.

Example

Liefere Chunks von 1000 Pfaden:

my $fh = Quiq::FileHandle->new('-|',"find @$dirA -name '*.xml.gz'");
while (my $fileA = $fh->readLines(1000)) {
    ...
}
$fh->close;

readLineChomp() - Lies Zeile ohne Zeilentrenner von Dateihandle

Synopsis

$line = $fh->readLineChomp;

Description

Lies die nächste Zeile von Dateihandle $fh, entferne den Zeilentrenner mit chomp() und liefere das Resultat zurück.

readLineNoWhiteSpace() - Lies Zeile und entferne Whitespace am Ende

Synopsis

$line = $fh->readLineNoWhiteSpace;

Description

Lies die nächste Zeile von Dateihandle $fh, entferne jeglichen Whitespace am Zeilenende (mit s/\s+$//) und liefere das Resultat zurück.

Diese Funktion ist nützlich, wenn verschiedene Zeilentrenner CRLF oder LF vorkommen können und Zeilen nur mit Whitespace zu Leerzeilen reduziert werden sollen.

getc() - Lies nächstes Zeichen

Synopsis

$c = $fh->getc;

slurp() - Lies Rest der Datei

Synopsis

$data = $fh->slurp;

Returns

String

Description

Lies den Rest von Dateihandle $fh liefere diesen zurück.

Die Methode ist nützlich, wenn der gesamte Inhalt einer Datei ab einer bestimmten Position gelesen werden soll.

Example

Lies gesamten Inhalt einer Datei ab Position $pos:

my $fh = Quiq::FileHandle->open('<',$logFile);
$fh->seek($pos);
my $data = $fh->slurp;

Schreiben

print() - Schreibe Daten auf Dateihandle

Synopsis

$fh->print(@data);

Alias

write()

Description

Schreibe Daten @data auf Dateihandle $fh. Die Methode liefert keinen Wert zurück.

writeData() - Schreibe Daten mit Längenangabe

Synopsis

$fh->writeData($data);

Description

Schreibe die Daten $data in der Repräsentation

<LENGTH><DATA>

Hierbei ist <LENGTH> ein 32 Bit Integer, der die Länge der darauffolgenden Daten <DATA> in Bytes angibt.

Liegen die Daten $data in einem Encoding wie UTF-8 vor, müssen diese zuvor encodiert werden mit

Encode::encode('utf-8',$data);

Auf der FileHandle $fh das Encoding zu definieren, ist nicht richtig, da die Längenangabe diesem Encoding nicht unterliegt!

See Also

readData()

truncate() - Kürze Datei

Synopsis

$fh->truncate;
$fh->truncate($length);

Description

Kürze Datei auf Länge $length. Ist $length nicht angegeben, kürze Datei auf Länge 0.

Positionieren

seek() - Setze Position in Datei

Synopsis

$fh->seek($pos);
$fh->seek($pos,$whence);

Description

Setze die Position der Filehandle in der Datei. Die Methode liefert keinen Wert zurück. Genaue Funktionsbeschreibung siehe Perl-Dokumentation (perldoc -f seek).

tell() - Liefere Position in Datei

Synopsis

$pos = $fh->tell;

Description

Liefere die Position der Filehandle in der Datei. Genaue Funktionsbeschreibung siehe Perl-Dokumentation (perldoc -f tell).

Sperren

lock() - Sperre Datei

Synopsis

$fh->lock($lockMode);

Description

Locke die Datei im Lock-Modus $lockMode. Die Methode liefert keinen Wert zurück.

Folgende Lockmodes werden unterschieden:

'SH'

shared lock

'EX'

exclusive lock

'SHNB'

shared lock, non-blocking

'EXNB'

exclusive lock, non-bloking

Liefere "wahr", wenn der Lock gesetzt werden kann, im Fehlerfall liefere "falsch".

unlock() - Hebe Sperre auf

Synopsis

$fh->unlock;

Description

Hebe Sperre auf Dateihandle $fh auf. Die Methode liefert keinen Wert zurück.

Encoding

setEncoding() - Setze Encoding

Synopsis

$fh = $fh->setEncoding($encoding);

Arguments

$encoding

Bezeichnung des Encoding.

Returns

FileHandle-Objekt (für Method-Chaining)

Description

Definiere für Filehandle $fh das Encoding $encoding. D.h. alle Daten werden automatisch gemäß diesem Encoding beim Schreiben encodiert bzw. beim Lesen dekodiert.

Verschiedenes

autoFlush() - Schalte Filehandle in ungepufferten Modus

Synopsis

$fh->autoFlush;
$fh->autoFlush($bool);

binmode() - Aktiviere Binärmodus oder Layer

Synopsis

$fh->binmode;
$fh->binmode($layer);

Description

Schalte Filehandle in Binärmodus oder setze Layer $layer. Genaue Funktionsbeschreibung siehe Perl-Dokumentation (perldoc -f binmode).

Klassenmethoden

captureStderr() - Fange STDERR ab

Synopsis

$class->captureStderr(\$str);

Returns

Die Methode liefert keinen Wert zurrück

Description

Fange alle Ausgaben auf STDERR ab und lenke sie auf Skalarvariable $str um.

slurpFromStdin() - Lies Eingaben von STDIN

Synopsis

$data = $class->slurpFromStdin;

Returns

String

Description

Lies alle Eingaben von STDIN und liefere diese als eine Zeichenkette zurück.

VERSION

1.222

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.