File::chdir(3pm)

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

NAME

6       File::chdir - a more sensible way to change directories
7

VERSION

9       version 0.1011
10

SYNOPSIS

12         use File::chdir;
13
14         $CWD = "/foo/bar";     # now in /foo/bar
15         {
16             local $CWD = "/moo/baz";  # now in /moo/baz
17             ...
18         }
19
20         # still in /foo/bar!
21

DESCRIPTION

23       Perl's chdir() has the unfortunate problem of being very, very, very
24       global.  If any part of your program calls chdir() or if any library
25       you use calls chdir(), it changes the current working directory for the
26       *whole* program.
27
28       This sucks.
29
30       File::chdir gives you an alternative, $CWD and @CWD.  These two
31       variables combine all the power of chdir(), File::Spec and Cwd.
32

$CWD

34       Use the $CWD variable instead of chdir() and Cwd.
35
36           use File::chdir;
37           $CWD = $dir;  # just like chdir($dir)!
38           print $CWD;   # prints the current working directory
39
40       It can be localized, and it does the right thing.
41
42           $CWD = "/foo";      # it's /foo out here.
43           {
44               local $CWD = "/bar";  # /bar in here
45           }
46           # still /foo out here!
47
48       $CWD always returns the absolute path in the native form for the
49       operating system.
50
51       $CWD and normal chdir() work together just fine.
52

@CWD

54       @CWD represents the current working directory as an array, each
55       directory in the path is an element of the array.  This can often make
56       the directory easier to manipulate, and you don't have to fumble with
57       "File::Spec->splitpath" and "File::Spec->catdir" to make portable code.
58
59         # Similar to chdir("/usr/local/src/perl")
60         @CWD = qw(usr local src perl);
61
62       pop, push, shift, unshift and splice all work.  pop and push are
63       probably the most useful.
64
65         pop @CWD;                 # same as chdir(File::Spec->updir)
66         push @CWD, 'some_dir'     # same as chdir('some_dir')
67
68       @CWD and $CWD both work fine together.
69
70       *NOTE* Due to a perl bug you can't localize @CWD.  See "CAVEATS" for a
71       work around.
72

EXAMPLES

74       (We omit the "use File::chdir" from these examples for terseness)
75
76       Here's $CWD instead of chdir():
77
78           $CWD = 'foo';           # chdir('foo')
79
80       and now instead of Cwd.
81
82           print $CWD;             # use Cwd;  print Cwd::abs_path
83
84       you can even do zsh style "cd foo bar"
85
86           $CWD = '/usr/local/foo';
87           $CWD =~ s/usr/var/;
88
89       if you want to localize that, make sure you get the parens right
90
91           {
92               (local $CWD) =~ s/usr/var/;
93               ...
94           }
95
96       It's most useful for writing polite subroutines which don't leave the
97       program in some strange directory:
98
99           sub foo {
100               local $CWD = 'some/other/dir';
101               ...do your work...
102           }
103
104       which is much simpler than the equivalent:
105
106           sub foo {
107               use Cwd;
108               my $orig_dir = Cwd::getcwd;
109               chdir('some/other/dir');
110
111               ...do your work...
112
113               chdir($orig_dir);
114           }
115
116       @CWD comes in handy when you want to start moving up and down the
117       directory hierarchy in a cross-platform manner without having to use
118       File::Spec.
119
120           pop @CWD;                   # chdir(File::Spec->updir);
121           push @CWD, 'some', 'dir'    # chdir(File::Spec->catdir(qw(some dir)));
122
123       You can easily change your parent directory:
124
125           # chdir from /some/dir/bar/moo to /some/dir/foo/moo
126           $CWD[-2] = 'foo';
127

CAVEATS

129   "local @CWD" does not work.
130       "local @CWD" will not localize @CWD.  This is a bug in Perl, you can't
131       localize tied arrays.  As a work around localizing $CWD will
132       effectively localize @CWD.
133
134           {
135               local $CWD;
136               pop @CWD;
137               ...
138           }
139
140   Assigning to @CWD calls chdir() for each element
141           @CWD = qw/a b c d/;
142
143       Internally, Perl clears @CWD and assigns each element in turn.  Thus,
144       this code above will do this:
145
146           chdir 'a';
147           chdir 'a/b';
148           chdir 'a/b/c';
149           chdir 'a/b/c/d';
150
151       Generally, avoid assigning to @CWD and just use push and pop instead.
152
153   Volumes not handled
154       There is currently no way to change the current volume via File::chdir.
155

NOTES

157       $CWD returns the current directory using native path separators, i.e.
158       "\" on Win32.  This ensures that $CWD will compare correctly with
159       directories created using File::Spec.  For example:
160
161           my $working_dir = File::Spec->catdir( $CWD, "foo" );
162           $CWD = $working_dir;
163           doing_stuff_might_chdir();
164           is( $CWD, $working_dir, "back to original working_dir?" );
165
166       Deleting the last item of @CWD will act like a pop.  Deleting from the
167       middle will throw an exception.
168
169           delete @CWD[-1]; # OK
170           delete @CWD[-2]; # Dies
171
172       What should %CWD do?  Something with volumes?
173
174           # chdir to C:\Program Files\Sierra\Half Life ?
175           $CWD{C} = '\\Program Files\\Sierra\\Half Life';
176

DIAGNOSTICS

178       If an error is encountered when changing $CWD or @CWD, one of the
179       following exceptions will be thrown:
180
181       * ~Can't delete except at the end of @CWD~ * ~Failed to change
182       directory to '$dir'~
183

HISTORY

185       Michael wanted "local chdir" to work.  p5p didn't.  But it wasn't over!
186       Was it over when the Germans bombed Pearl Harbor?  Hell, no!
187
188       Abigail and/or Bryan Warnock suggested the $CWD thing (Michael forgets
189       which).  They were right.
190
191       The chdir() override was eliminated in 0.04.
192
193       David became co-maintainer with 0.06_01 to fix some chronic Win32 path
194       bugs.
195
196       As of 0.08, if changing $CWD or @CWD fails to change the directory, an
197       error will be thrown.
198

SUPPORT

204   Bugs / Feature Requests
205       Please report any bugs or feature requests through the issue tracker at
206       <https://github.com/dagolden/File-chdir/issues>.  You will be notified
207       automatically of any progress on your issue.
208
209   Source Code
210       This is open source software.  The code repository is available for
211       public review and contribution under the terms of the license.
212
213       <https://github.com/dagolden/File-chdir>
214
215         git clone https://github.com/dagolden/File-chdir.git
216

AUTHORS

218       •   David Golden <dagolden@cpan.org>
219
220       •   Michael G. Schwern <schwern@pobox.com>
221

CONTRIBUTORS

223       •   David Golden <xdg@xdg.me>
224
225       •   Joel Berger <joel.a.berger@gmail.com>
226
227       •   Philippe Bruhat (BooK) <book@cpan.org>
228

COPYRIGHT AND LICENSE

230       This software is copyright (c) 2016 by Michael G. Schwern and David
231       Golden.
232
233       This is free software; you can redistribute it and/or modify it under
234       the same terms as the Perl 5 programming language system itself.
235
236
237
238perl v5.38.0                      2023-07-20                    File::chdir(3)