/ 
File-pushd-0.20
River stage four • 135 direct dependents • 2781 total dependents
/ File::pushd

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