more prose fixups to bytes.pm deprecation warning
[p5sagit/p5-mst-13.2.git] / lib / FindBin.pm
1 # FindBin.pm
2 #
3 # Copyright (c) 1995 Graham Barr & Nick Ing-Simmons. All rights reserved.
4 # This program is free software; you can redistribute it and/or modify it
5 # under the same terms as Perl itself.
6
7 =head1 NAME
8
9 FindBin - Locate directory of original perl script
10
11 =head1 SYNOPSIS
12
13  use FindBin;
14  use lib "$FindBin::Bin/../lib";
15
16  or
17
18  use FindBin qw($Bin);
19  use lib "$Bin/../lib";
20
21 =head1 DESCRIPTION
22
23 Locates the full path to the script bin directory to allow the use
24 of paths relative to the bin directory.
25
26 This allows a user to setup a directory tree for some software with
27 directories C<< <root>/bin >> and C<< <root>/lib >>, and then the above
28 example will allow the use of modules in the lib directory without knowing
29 where the software tree is installed.
30
31 If perl is invoked using the B<-e> option or the perl script is read from
32 C<STDIN> then FindBin sets both C<$Bin> and C<$RealBin> to the current
33 directory.
34
35 =head1 EXPORTABLE VARIABLES
36
37  $Bin         - path to bin directory from where script was invoked
38  $Script      - basename of script from which perl was invoked
39  $RealBin     - $Bin with all links resolved
40  $RealScript  - $Script with all links resolved
41
42 =head1 KNOWN ISSUES
43
44 If there are two modules using C<FindBin> from different directories
45 under the same interpreter, this won't work. Since C<FindBin> uses a
46 C<BEGIN> block, it'll be executed only once, and only the first caller
47 will get it right. This is a problem under mod_perl and other persistent
48 Perl environments, where you shouldn't use this module. Which also means
49 that you should avoid using C<FindBin> in modules that you plan to put
50 on CPAN. To make sure that C<FindBin> will work is to call the C<again>
51 function:
52
53   use FindBin;
54   FindBin::again(); # or FindBin->again;
55
56 In former versions of FindBin there was no C<again> function. The
57 workaround was to force the C<BEGIN> block to be executed again:
58
59   delete $INC{'FindBin.pm'};
60   require FindBin;
61
62 =head1 KNOWN BUGS
63
64 If perl is invoked as
65
66    perl filename
67
68 and I<filename> does not have executable rights and a program called
69 I<filename> exists in the users C<$ENV{PATH}> which satisfies both B<-x>
70 and B<-T> then FindBin assumes that it was invoked via the
71 C<$ENV{PATH}>.
72
73 Workaround is to invoke perl as
74
75  perl ./filename
76
77 =head1 AUTHORS
78
79 FindBin is supported as part of the core perl distribution. Please send bug
80 reports to E<lt>F<perlbug@perl.org>E<gt> using the perlbug program
81 included with perl.
82
83 Graham Barr E<lt>F<gbarr@pobox.com>E<gt>
84 Nick Ing-Simmons E<lt>F<nik@tiuk.ti.com>E<gt>
85
86 =head1 COPYRIGHT
87
88 Copyright (c) 1995 Graham Barr & Nick Ing-Simmons. All rights reserved.
89 This program is free software; you can redistribute it and/or modify it
90 under the same terms as Perl itself.
91
92 =cut
93
94 package FindBin;
95 use Carp;
96 require 5.000;
97 require Exporter;
98 use Cwd qw(getcwd cwd abs_path);
99 use File::Basename;
100 use File::Spec;
101
102 @EXPORT_OK = qw($Bin $Script $RealBin $RealScript $Dir $RealDir);
103 %EXPORT_TAGS = (ALL => [qw($Bin $Script $RealBin $RealScript $Dir $RealDir)]);
104 @ISA = qw(Exporter);
105
106 $VERSION = "1.50";
107
108
109 # needed for VMS-specific filename translation
110 if( $^O eq 'VMS' ) {
111     require VMS::Filespec;
112     VMS::Filespec->import;
113 }
114
115 sub cwd2 {
116    my $cwd = getcwd();
117    # getcwd might fail if it hasn't access to the current directory.
118    # try harder.
119    defined $cwd or $cwd = cwd();
120    $cwd;
121 }
122
123 sub init
124 {
125  *Dir = \$Bin;
126  *RealDir = \$RealBin;
127
128  if($0 eq '-e' || $0 eq '-')
129   {
130    # perl invoked with -e or script is on C<STDIN>
131    $Script = $RealScript = $0;
132    $Bin    = $RealBin    = cwd2();
133    $Bin = VMS::Filespec::unixify($Bin) if $^O eq 'VMS';
134   }
135  else
136   {
137    my $script = $0;
138
139    if ($^O eq 'VMS')
140     {
141      ($Bin,$Script) = VMS::Filespec::rmsexpand($0) =~ /(.*[\]>\/]+)(.*)/s;
142      # C<use disk:[dev]/lib> isn't going to work, so unixify first
143      ($Bin = VMS::Filespec::unixify($Bin)) =~ s/\/\z//;
144      ($RealBin,$RealScript) = ($Bin,$Script);
145     }
146    else
147     {
148      my $dosish = ($^O eq 'MSWin32' or $^O eq 'os2');
149      unless(($script =~ m#/# || ($dosish && $script =~ m#\\#))
150             && -f $script)
151       {
152        my $dir;
153        foreach $dir (File::Spec->path)
154         {
155         my $scr = File::Spec->catfile($dir, $script);
156
157         # $script can been found via PATH but perl could have
158         # been invoked as 'perl file'. Do a dumb check to see
159         # if $script is a perl program, if not then keep $script = $0
160         #
161         # well we actually only check that it is an ASCII file
162         # we know its executable so it is probably a script
163         # of some sort.
164         if(-f $scr && -r _ && ($dosish || -x _) && -s _ && -T _)
165          {
166           $script = $scr;
167           last;
168          }
169        }
170      }
171
172      croak("Cannot find current script '$0'") unless(-f $script);
173
174      # Ensure $script contains the complete path in case we C<chdir>
175
176      $script = File::Spec->catfile(cwd2(), $script)
177        unless File::Spec->file_name_is_absolute($script);
178
179      ($Script,$Bin) = fileparse($script);
180
181      # Resolve $script if it is a link
182      while(1)
183       {
184        my $linktext = readlink($script);
185
186        ($RealScript,$RealBin) = fileparse($script);
187        last unless defined $linktext;
188
189        $script = (File::Spec->file_name_is_absolute($linktext))
190                   ? $linktext
191                   : File::Spec->catfile($RealBin, $linktext);
192       }
193
194      # Get absolute paths to directories
195      if ($Bin) {
196       my $BinOld = $Bin;
197       $Bin = abs_path($Bin);
198       defined $Bin or $Bin = File::Spec->canonpath($BinOld);
199      }
200      $RealBin = abs_path($RealBin) if($RealBin);
201     }
202   }
203 }
204
205 BEGIN { init }
206
207 *again = \&init;
208
209 1; # Keep require happy