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.