NAME

File::Transaction - transactional change to a set of files

SYNOPSIS

#
# In this example, we wish to replace the word 'foo' with the
# word 'bar' in several files, and we wish to minimize the risk
# of ending up with the replacement done in some files but not
# in others.
#

use File::Transaction;

my $ft = File::Transaction->new;

eval {
    foreach my $file (@list_of_file_names) {
        $ft->linewise_rewrite($file, sub {
             s#\bfoo\b#bar#g;
        });
    }
};

if ($@) {
    $ft->revert;
    die "update aborted: $@";
}
else {
    $ft->commit;
}

DESCRIPTION

A File::Transaction object encapsulates a change to a set of files, performed by writing out a new version of each file first and then swapping all of the new versions in. The set of files can only end up in an inconsistent state if a rename system call fails or if the Perl process is interrupted during the commit().

Files will be committed in the order in which they are added to the transaction. This order should be chosen with care to limit the damage to your data if the commit() fails part way through. If there is no order that renders a partial commit acceptable then consider using File::Transaction::Atomic instead.

CONSTRUCTORS

new ( [TMPEXT] )

Creates a new empty File::Transaction object.

The TMPEXT parameter gives the string to append to a filename to make a temporary filename for the new version. The default is .tmp.

METHODS

linewise_rewrite ( OLDFILE, CALLBACK )

Writes out a new version of the file OLDFILE and adds it to the transaction, invoking the coderef CALLBACK once for each line of the file, with the line in $_. The name of the new file is generated by appending the TMPEXT passed to new() to OLDFILE, and this file is overwritten if it already exists.

The callback must not invoke the commit() or revert() methods of the File::Transaction object that calls it.

This method calls die() on error, without first reverting any other files in the transaction.

addfile ( OLDFILE, TMPFILE )

Adds an update to a single file to the transaction. OLDFILE is the name of the old version of the file, and TMPFILE is the name of the temporary file to which the new version has been written.

OLDFILE will be replaced with TMPFILE on commit(), and TMPFILE will be unlinked on revert(). OLDFILE need not exist.

revert ()

Deletes any new versions of files that have been created with the addfile() method so far. Dies on error.

commit ()

Swaps all new versions that have been created so far into place. Dies on error.

BUGS

• If a rename fails or the Perl process is interrupted in the commit() method then some files will be updated but others will not. See File::Transaction::Atomic if that's a problem for you.

SEE ALSO

File::Transaction::Atomic

AUTHOR

Nick Cleaton <nick@cleaton.net>

COPYRIGHT

Copyright (C) 2002-2003 Nick Cleaton. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.