<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">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}

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

     # object stringifies naturally as an absolute path
     {
        my $dir = pushd( '/tmp' );
        my $filename = File::Spec-&gt;catfile( $dir, "somefile.txt" );
        # gives /tmp/somefile.txt
     }
    
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.

    For convenience, the object stringifies as the canonical form of the
    absolute pathname of the directory entered.

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

    The provided target directory can 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-&gt;preserve;      # mark to preserve at end of scope
         $dir-&gt;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
    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.

</pre></body></html>