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