NAME
    File::pushd - change directory temporarily for a limited scope

SYNOPSIS
     use File::pushd;

     chdir $ENV{HOME};
 
     # change directory again for a limited scope
     {
         my $dir = pushd( '/tmp' );
         # working directory changed to /tmp
     }
     # working directory has reverted to $ENV{HOME}

     # equivalent to pushd( File::Temp::tempdir )
     {
         my $dir = tempd();
     }

     # $dir is a Path::Class::Dir object
     {
         my $dir = pushd( '/tmp' );
         print "Contents of $dir:\n";
         print "  $_\n" for $dir->children();
     }

DESCRIPTION
    File::pushd does a temporary `chdir' that is easily and automatically
    reverted, similar to `pushd' in some Unix command shells. It works by
    creating an object that caches the original working directory. When the
    object is destroyed, the destructor calls `chdir' to revert to the
    original working directory. By storing the object in a lexical variable
    with a limited scope, this happens automatically at the end of the
    scope.

    This is very handy when working with temporary directories for tasks
    like testing; a function is provided to streamline getting a temporary
    directory from File::Temp.

    The directory objects created are subclassed from Path::Class::Dir, and
    provide all the power and simplicity of Path::Class.

USAGE
     use File::pushd;

    Using File::pushd automatically imports the `pushd' and `tempd'
    functions.

  pushd

     {
         my $dir = pushd( $target_directory );
     }

    Caches the current working directory, calls `chdir' to change to the
    target directory, and returns a File::pushd object (which is a subclass
    of a Path::Class::Dir object with an absolute pathname). When the object
    is destroyed, the working directory reverts to the original directory.

    The provided target directory can either be a relative or absolute path.
    If called with no arguments, it uses the current directory as its target
    and returns to the current directory when the object is destroyed.

  tempd

     {
         my $dir = tempd();
     }

    This function is like `pushd' but automatically creates and calls
    `chdir' to a temporary directory as created by File::Temp. Unlike normal
    File::Temp cleanup which happens at the end of the program, this
    temporary directory is removed when the object is destroyed. (But also
    see `preserve'.) A warning will be issued if the directory cannot be
    removed.

  preserve

     {
         my $dir = tempd();
         $dir->preserve;      # mark to preserve at end of scope
         $dir->preserve(0);   # mark to delete at end of scope
     }

    Controls whether a temporary directory will be cleaned up when the
    object is destroyed. With no arguments, `preserve' sets the directory to
    be preserved. With an argument, the directory will be preserved if the
    argument is true, or marked for cleanup if the argument is false. Only
    `tempd' objects may be marked for cleanup. (Target directories to
    `pushd' are always preserved.) `preserve' returns true if the directory
    will be preserved, and false otherwise.

SEE ALSO
    Path::Class, File::chdir

BUGS
    Please report bugs using the CPAN Request Tracker at
    http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-pushd

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.

AUTHOR
    David A Golden (DAGOLDEN)

    dagolden@cpan.org

    http://dagolden.com/

COPYRIGHT
    Copyright (c) 2005 by David A Golden

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

    The full text of the license can be found in the LICENSE file included
    with this module.

