.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "File::chdir 3pm" .TH File::chdir 3pm "2020-12-27" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" File::chdir \- a more sensible way to change directories .SH "VERSION" .IX Header "VERSION" version 0.1008 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use File::chdir; \& \& $CWD = "/foo/bar"; # now in /foo/bar \& { \& local $CWD = "/moo/baz"; # now in /moo/baz \& ... \& } \& \& # still in /foo/bar! .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Perl's \f(CW\*(C`chdir()\*(C'\fR has the unfortunate problem of being very, very, very global. If any part of your program calls \f(CW\*(C`chdir()\*(C'\fR or if any library you use calls \f(CW\*(C`chdir()\*(C'\fR, it changes the current working directory for the \fBwhole\fR program. .PP This sucks. .PP File::chdir gives you an alternative, \f(CW$CWD\fR and \f(CW@CWD\fR. These two variables combine all the power of \f(CW\*(C`chdir()\*(C'\fR, File::Spec and Cwd. .ie n .SH "$CWD" .el .SH "\f(CW$CWD\fP" .IX Header "$CWD" Use the \f(CW$CWD\fR variable instead of \f(CW\*(C`chdir()\*(C'\fR and Cwd. .PP .Vb 3 \& use File::chdir; \& $CWD = $dir; # just like chdir($dir)! \& print $CWD; # prints the current working directory .Ve .PP It can be localized, and it does the right thing. .PP .Vb 5 \& $CWD = "/foo"; # it\*(Aqs /foo out here. \& { \& local $CWD = "/bar"; # /bar in here \& } \& # still /foo out here! .Ve .PP \&\f(CW$CWD\fR always returns the absolute path in the native form for the operating system. .PP \&\f(CW$CWD\fR and normal \f(CW\*(C`chdir()\*(C'\fR work together just fine. .ie n .SH "@CWD" .el .SH "\f(CW@CWD\fP" .IX Header "@CWD" \&\f(CW@CWD\fR represents the current working directory as an array, each directory in the path is an element of the array. This can often make the directory easier to manipulate, and you don't have to fumble with \&\f(CW\*(C`File::Spec\->splitpath\*(C'\fR and \f(CW\*(C`File::Spec\->catdir\*(C'\fR to make portable code. .PP .Vb 2 \& # Similar to chdir("/usr/local/src/perl") \& @CWD = qw(usr local src perl); .Ve .PP pop, push, shift, unshift and splice all work. pop and push are probably the most useful. .PP .Vb 2 \& pop @CWD; # same as chdir(File::Spec\->updir) \& push @CWD, \*(Aqsome_dir\*(Aq # same as chdir(\*(Aqsome_dir\*(Aq) .Ve .PP \&\f(CW@CWD\fR and \f(CW$CWD\fR both work fine together. .PP \&\fB\s-1NOTE\s0\fR Due to a perl bug you can't localize \f(CW@CWD\fR. See \*(L"\s-1CAVEATS\*(R"\s0 for a work around. .SH "EXAMPLES" .IX Header "EXAMPLES" (We omit the \f(CW\*(C`use File::chdir\*(C'\fR from these examples for terseness) .PP Here's \f(CW$CWD\fR instead of \f(CW\*(C`chdir()\*(C'\fR: .PP .Vb 1 \& $CWD = \*(Aqfoo\*(Aq; # chdir(\*(Aqfoo\*(Aq) .Ve .PP and now instead of Cwd. .PP .Vb 1 \& print $CWD; # use Cwd; print Cwd::abs_path .Ve .PP you can even do zsh style \f(CW\*(C`cd foo bar\*(C'\fR .PP .Vb 2 \& $CWD = \*(Aq/usr/local/foo\*(Aq; \& $CWD =~ s/usr/var/; .Ve .PP if you want to localize that, make sure you get the parens right .PP .Vb 4 \& { \& (local $CWD) =~ s/usr/var/; \& ... \& } .Ve .PP It's most useful for writing polite subroutines which don't leave the program in some strange directory: .PP .Vb 4 \& sub foo { \& local $CWD = \*(Aqsome/other/dir\*(Aq; \& ...do your work... \& } .Ve .PP which is much simpler than the equivalent: .PP .Vb 4 \& sub foo { \& use Cwd; \& my $orig_dir = Cwd::getcwd; \& chdir(\*(Aqsome/other/dir\*(Aq); \& \& ...do your work... \& \& chdir($orig_dir); \& } .Ve .PP \&\f(CW@CWD\fR comes in handy when you want to start moving up and down the directory hierarchy in a cross-platform manner without having to use File::Spec. .PP .Vb 2 \& pop @CWD; # chdir(File::Spec\->updir); \& push @CWD, \*(Aqsome\*(Aq, \*(Aqdir\*(Aq # chdir(File::Spec\->catdir(qw(some dir))); .Ve .PP You can easily change your parent directory: .PP .Vb 2 \& # chdir from /some/dir/bar/moo to /some/dir/foo/moo \& $CWD[\-2] = \*(Aqfoo\*(Aq; .Ve .SH "CAVEATS" .IX Header "CAVEATS" \fI\f(CI\*(C`local @CWD\*(C'\fI does not work.\fR .IX Subsection "local @CWD does not work." .PP \&\f(CW\*(C`local @CWD\*(C'\fR will not localize \f(CW@CWD\fR. This is a bug in Perl, you can't localize tied arrays. As a work around localizing \f(CW$CWD\fR will effectively localize \f(CW@CWD\fR. .PP .Vb 5 \& { \& local $CWD; \& pop @CWD; \& ... \& } .Ve .PP \fIAssigning to \f(CI@CWD\fI calls \f(CI\*(C`chdir()\*(C'\fI for each element\fR .IX Subsection "Assigning to @CWD calls chdir() for each element" .PP .Vb 1 \& @CWD = qw/a b c d/; .Ve .PP Internally, Perl clears \f(CW@CWD\fR and assigns each element in turn. Thus, this code above will do this: .PP .Vb 4 \& chdir \*(Aqa\*(Aq; \& chdir \*(Aqa/b\*(Aq; \& chdir \*(Aqa/b/c\*(Aq; \& chdir \*(Aqa/b/c/d\*(Aq; .Ve .PP Generally, avoid assigning to \f(CW@CWD\fR and just use push and pop instead. .PP \fIVolumes not handled\fR .IX Subsection "Volumes not handled" .PP There is currently no way to change the current volume via File::chdir. .SH "NOTES" .IX Header "NOTES" \&\f(CW$CWD\fR returns the current directory using native path separators, i.e. \e on Win32. This ensures that \f(CW$CWD\fR will compare correctly with directories created using File::Spec. For example: .PP .Vb 4 \& my $working_dir = File::Spec\->catdir( $CWD, "foo" ); \& $CWD = $working_dir; \& doing_stuff_might_chdir(); \& is( $CWD, $working_dir, "back to original working_dir?" ); .Ve .PP Deleting the last item of \f(CW@CWD\fR will act like a pop. Deleting from the middle will throw an exception. .PP .Vb 2 \& delete @CWD[\-1]; # OK \& delete @CWD[\-2]; # Dies .Ve .PP What should \f(CW%CWD\fR do? Something with volumes? .PP .Vb 2 \& # chdir to C:\eProgram Files\eSierra\eHalf Life ? \& $CWD{C} = \*(Aq\e\eProgram Files\e\eSierra\e\eHalf Life\*(Aq; .Ve .SH "DIAGNOSTICS" .IX Header "DIAGNOSTICS" If an error is encountered when changing \f(CW$CWD\fR or \f(CW@CWD\fR, one of the following exceptions will be thrown: .IP "\(bu" 4 \&\fICan't delete except at the end of \f(CI@CWD\fI\fR .IP "\(bu" 4 \&\fIFailed to change directory to '$dir'\fR .SH "HISTORY" .IX Header "HISTORY" Michael wanted \f(CW\*(C`local chdir\*(C'\fR to work. p5p didn't. But it wasn't over! Was it over when the Germans bombed Pearl Harbor? Hell, no! .PP Abigail and/or Bryan Warnock suggested the \f(CW$CWD\fR thing (Michael forgets which). They were right. .PP The \f(CW\*(C`chdir()\*(C'\fR override was eliminated in 0.04. .PP David became co-maintainer with 0.06_01 to fix some chronic Win32 path bugs. .PP As of 0.08, if changing \f(CW$CWD\fR or \f(CW@CWD\fR fails to change the directory, an error will be thrown. .SH "SEE ALSO" .IX Header "SEE ALSO" File::pushd, File::Spec, Cwd, \*(L"chdir\*(R" in perlfunc, \&\*(L"Animal House\*(R" .SH "SUPPORT" .IX Header "SUPPORT" .SS "Bugs / Feature Requests" .IX Subsection "Bugs / Feature Requests" Please report any bugs or feature requests through the issue tracker at . You will be notified automatically of any progress on your issue. .SS "Source Code" .IX Subsection "Source Code" This is open source software. The code repository is available for public review and contribution under the terms of the license. .PP .PP .Vb 1 \& git clone git://github.com/dagolden/file\-chdir.git .Ve .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 David A Golden .IP "\(bu" 4 Michael G Schwern (original author) .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2012 by Michael G Schwern and David A Golden. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.