1File::pushd(3) User Contributed Perl Documentation File::pushd(3)
2
6 File::pushd - change directory temporarily for a limited scope
7
9 version 1.016
10
12 use File::pushd;
13 chdir $ENV{HOME};
15 # 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 # tempd() is equivalent to pushd( File::Temp::tempdir )
24 {
25 my $dir = tempd();
26 }
27 # 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
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 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 For convenience, the object stringifies as the canonical form of the
49 absolute pathname of the directory entered.
50 Warning: if you create multiple "pushd" objects in the same lexical
52 scope, their destruction order is not guaranteed and you might not wind
53 up in the directory you expect.
54
56 use File::pushd;
57 Using File::pushd automatically imports the "pushd" and "tempd"
59 functions.
60 pushd
62 {
63 my $dir = pushd( $target_directory );
64 }
65 Caches the current working directory, calls "chdir" to change to the
67 target directory, and returns a File::pushd object. When the object is
68 destroyed, the working directory reverts to the original directory.
69 The provided target directory can be a relative or absolute path. If
71 called with no arguments, it uses the current directory as its target
72 and returns to the current directory when the object is destroyed.
73 If the target directory does not exist or if the directory change fails
75 for some reason, "pushd" will die with an error message.
76 Can be given a hashref as an optional second argument. The only
78 supported option is "untaint_pattern", which is used to untaint file
79 paths involved. It defaults to {qr{^("" in -+@\w.+)$}}, which is
80 reasonably restrictive (e.g. it does not even allow spaces in the
81 path). Change this to suit your circumstances and security needs if
82 running under taint mode. *Note*: you must include the parentheses in
83 the pattern to capture the untainted portion of the path.
84 tempd
86 {
87 my $dir = tempd();
88 }
89 This function is like "pushd" but automatically creates and calls
91 "chdir" to a temporary directory created by File::Temp. Unlike normal
92 File::Temp cleanup which happens at the end of the program, this
93 temporary directory is removed when the object is destroyed. (But also
94 see "preserve".) A warning will be issued if the directory cannot be
95 removed.
96 As with "pushd", "tempd" will die if "chdir" fails.
98 It may be given a single options hash that will be passed internally to
100 "pushd".
101 preserve
103 {
104 my $dir = tempd();
105 $dir->preserve; # mark to preserve at end of scope
106 $dir->preserve(0); # mark to delete at end of scope
107 }
108 Controls whether a temporary directory will be cleaned up when the
110 object is destroyed. With no arguments, "preserve" sets the directory
111 to be preserved. With an argument, the directory will be preserved if
112 the argument is true, or marked for cleanup if the argument is false.
113 Only "tempd" objects may be marked for cleanup. (Target directories to
114 "pushd" are always preserved.) "preserve" returns true if the
115 directory will be preserved, and false otherwise.
116
118 "pushd" and "tempd" warn with message "Useless use of File::pushd::%s
119 in void context" if called in void context and the warnings category
120 "void" is enabled.
121 {
123 use warnings 'void';
124 pushd();
126 }
127
129 • File::chdir
130
132 Bugs / Feature Requests
133 Please report any bugs or feature requests through the issue tracker at
134 <https://github.com/dagolden/File-pushd/issues>. You will be notified
135 automatically of any progress on your issue.
136 Source Code
138 This is open source software. The code repository is available for
139 public review and contribution under the terms of the license.
140 <https://github.com/dagolden/File-pushd>
142 git clone https://github.com/dagolden/File-pushd.git
144
146 David Golden <dagolden@cpan.org>
147
149 • Diab Jerius <djerius@cfa.harvard.edu>
150 • Graham Ollis <plicease@cpan.org>
152 • Olivier Mengué <dolmen@cpan.org>
154 • Shoichi Kaji <skaji@cpan.org>
156
158 This software is Copyright (c) 2018 by David A Golden.
159 This is free software, licensed under:
161 The Apache License, Version 2.0, January 2004
163perl v5.36.0 2023-01-20 File::pushd(3)