1File::pushd(3)        User Contributed Perl Documentation       File::pushd(3)
2
3
4

NAME

6       File::pushd - change directory temporarily for a limited scope
7

VERSION

9       This documentation describes version 1.00.
10

SYNOPSIS

12         use File::pushd;
13
14         chdir $ENV{HOME};
15
16         # change directory again for a limited scope
17         {
18             my $dir = pushd( '/tmp' );
19             # working directory changed to /tmp
20         }
21         # working directory has reverted to $ENV{HOME}
22
23         # tempd() is equivalent to pushd( File::Temp::tempdir )
24         {
25             my $dir = tempd();
26         }
27
28         # object stringifies naturally as an absolute path
29         {
30            my $dir = pushd( '/tmp' );
31            my $filename = File::Spec->catfile( $dir, "somefile.txt" );
32            # gives /tmp/somefile.txt
33         }
34

DESCRIPTION

36       File::pushd does a temporary "chdir" that is easily and automatically
37       reverted, similar to "pushd" in some Unix command shells.  It works by
38       creating an object that caches the original working directory.  When
39       the object is destroyed, the destructor calls "chdir" to revert to the
40       original working directory.  By storing the object in a lexical
41       variable with a limited scope, this happens automatically at the end of
42       the scope.
43
44       This is very handy when working with temporary directories for tasks
45       like testing; a function is provided to streamline getting a temporary
46       directory from File::Temp.
47
48       For convenience, the object stringifies as the canonical form of the
49       absolute pathname of the directory entered.
50

USAGE

52         use File::pushd;
53
54       Using File::pushd automatically imports the "pushd" and "tempd"
55       functions.
56
57   pushd
58         {
59             my $dir = pushd( $target_directory );
60         }
61
62       Caches the current working directory, calls "chdir" to change to the
63       target directory, and returns a File::pushd object.  When the object is
64       destroyed, the working directory reverts to the original directory.
65
66       The provided target directory can be a relative or absolute path. If
67       called with no arguments, it uses the current directory as its target
68       and returns to the current directory when the object is destroyed.
69
70   tempd
71         {
72             my $dir = tempd();
73         }
74
75       This function is like "pushd" but automatically creates and calls
76       "chdir" to a temporary directory created by File::Temp. Unlike normal
77       File::Temp cleanup which happens at the end of the program, this
78       temporary directory is removed when the object is destroyed. (But also
79       see "preserve".)  A warning will be issued if the directory cannot be
80       removed.
81
82   preserve
83         {
84             my $dir = tempd();
85             $dir->preserve;      # mark to preserve at end of scope
86             $dir->preserve(0);   # mark to delete at end of scope
87         }
88
89       Controls whether a temporary directory will be cleaned up when the
90       object is destroyed.  With no arguments, "preserve" sets the directory
91       to be preserved.  With an argument, the directory will be preserved if
92       the argument is true, or marked for cleanup if the argument is false.
93       Only "tempd" objects may be marked for cleanup.  (Target directories to
94       "pushd" are always preserved.)  "preserve" returns true if the
95       directory will be preserved, and false otherwise.
96

SEE ALSO

98       ยท   File::chdir
99

BUGS

101       Please report any bugs or feature using the CPAN Request Tracker.  Bugs
102       can be submitted through the web interface at
103       <http://rt.cpan.org/Dist/Display.html?Queue=File-pushd>
104
105       When submitting a bug or request, please include a test-file or a patch
106       to an existing test-file that illustrates the bug or desired feature.
107

AUTHOR

109       David A. Golden (DAGOLDEN)
110

112       Copyright (c) 2005, 2006, 2007 by David A. Golden
113
114       Licensed under the Apache License, Version 2.0 (the "License"); you may
115       not use this file except in compliance with the License.  You may
116       obtain a copy of the License at
117       <http://www.apache.org/licenses/LICENSE-2.0>
118
119       Files produced as output though the use of this software, including
120       generated copies of boilerplate templates provided with this software,
121       shall not be considered Derivative Works, but shall be considered the
122       original work of the Licensor.
123
124       Unless required by applicable law or agreed to in writing, software
125       distributed under the License is distributed on an "AS IS" BASIS,
126       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
127       implied.  See the License for the specific language governing
128       permissions and limitations under the License.
129
130
131
132perl v5.10.1                      2010-11-12                    File::pushd(3)
Impressum