NAME
    File::pushd - temporary chdir 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();
     }

DESCRIPTION
    File::pushd does a temporary `chdir' that is easily and automatically
    reverted. It works by creating a simple 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.

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

USAGE
     use File::pushd;

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

    File::pushd also overloads stringification so that objects created with
    `pushd' or `tempd' stringify as the absolute filepath that was set when
    the object was created.

  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. When the object is
    destroyed, the working directory reverts to the original directory.

    The 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();
     }

    Like `pushd' but automatically create and `chdir' to a temporary
    directory from 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. A warning will be issued if the directory
    cannot be removed.

  as_string

     print "$dir"; # calls $dir->as_string()

    Returns the absolute path of the working directory set by the pushd
    object. Used automatically when the object is stringified.

SEE ALSO
    File::chdir

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

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.

SEE ALSO
    perl(1).

