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. new `new' should never be used directly. It is a passthrough function that exists to ensure that directories derived from a `File::pushd' are just regular `Path::Class::Dir' objects. 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.