NAME

File::Append::TempFile - Perl extension for appending data to files

SYNOPSIS

  use File::Append::TempFile;

  $f = new File::Append::TempFile();
  $f->begin_work('/etc/hosts') or die "Appending: ".$f->err();
  $f->add_line("127.0.0.2 localhvost\n");
  $f->commit();

  $f->begin_work('/etc/hosts') or die "Appending: ".$f->err();
  $f->add_line("...\n");
  $f->rollback();

DESCRIPTION

The File::Append::TempFile module provides an OOP interface to appending data to files using a temporary file, in order to ensure the atomicity of the updates.

An append session is initiated by invoking the begin_work() method and passing it the name of the file. At this point, a temporary file is created in the same directory as the original file and the original's contents is copied to the temporary. More data is added to the temporary file using the add_line() method. When done appending, the commit() method will atomically move the temporary file over the original. If something goes wrong, the rollback() method will remove the temporary file without affecting the original in any way.

METHODS

The File::Append::TempFile class defines the following methods:

new (): Create a new File::Append::TempFile object. No file processing is done at this point.
err ( [MESSAGE] ): Set or obtain an error message describing the last error that occurred during the processing of the current File::Append::TempFile object.
diag ([FLAG]): Set or obtain the diagnostic output flag. If it is set, the methods will display diagnostic information on the standard error stream.
begin_work (FILENAME): Creates a temporary file in the same directory as the specified one and copies the original's contents over to the new file. Further data may be added using the add_line() method and then either stored as the original with the commit() method, or discarded with the rollback() method.
add_line (DATA): Append data to the temporary file. This does not affect the original in any way until commit() is invoked.
commit (): Replace the original file with the temporary copy, to which data may have been added using add_line().; NOTE: This method uninitializes the File::Append::TempFile object, that is, removes any association between it and the original file and even file name! The next method invoked on this File::Append::TempFile object should be begin_work().
rollback (): Discard all the changes made to the temporary copy and remove it. This does not affect the original file in any way.; NOTE: This method uninitializes the File::Append::TempFile object, that is, removes any association between it and the original file and even file name! The next method invoked on this File::Append::TempFile object should be begin_work().

There are also several methods used internally by the File::Append::TempFile routines:

debug (MESSAGE): Display a diagnostic message to the standard error stream if the output of diagnostic messages has been enabled.
do_copy (ORIG TEMP): Actually perform the copying of the original file data into the temporary file at begin_work() time. This allows derived classes to modify the file structure if needed.; The two parameters are the file handles for the original and the temporary file.

BUGS

Note that the original file may have changed between begin_work() and commit() - those changes will be lost!

AUTHOR

Peter Pentchev, <roam@ringlet.net>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.

$Id: TempFile.pm 306 2006-02-13 14:52:08Z roam $