Introduce NVef, NVff, and NVgf, use the middle one.
[perl.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 E<lt>rootE<gt>/bin and E<lt>rootE<gt>/lib and then the above example will allow
28 the use of modules in the lib directory without knowing where the software
29 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 BUGS
43
44 if perl is invoked as
45
46    perl filename
47
48 and I<filename> does not have executable rights and a program called I<filename>
49 exists in the users C<$ENV{PATH}> which satisfies both B<-x> and B<-T> then FindBin
50 assumes that it was invoked via the C<$ENV{PATH}>.
51
52 Workaround is to invoke perl as
53
54  perl ./filename
55
56 =head1 AUTHORS
57
58 FindBin is supported as part of the core perl distribution. Please send bug
59 reports to E<lt>F<perlbug@perl.org>E<gt> using the perlbug program included with perl.
60
61 Graham Barr E<lt>F<gbarr@pobox.com>E<gt>
62 Nick Ing-Simmons E<lt>F<nik@tiuk.ti.com>E<gt>
63
64 =head1 COPYRIGHT
65
66 Copyright (c) 1995 Graham Barr & Nick Ing-Simmons. All rights reserved.
67 This program is free software; you can redistribute it and/or modify it
68 under the same terms as Perl itself.
69
70 =cut
71
72 package FindBin;
73 use Carp;
74 require 5.000;
75 require Exporter;
76 use Cwd qw(getcwd abs_path);
77 use Config;
78 use File::Basename;
79 use File::Spec;
80
81 @EXPORT_OK = qw($Bin $Script $RealBin $RealScript $Dir $RealDir);
82 %EXPORT_TAGS = (ALL => [qw($Bin $Script $RealBin $RealScript $Dir $RealDir)]);
83 @ISA = qw(Exporter);
84
85 $VERSION = "1.42";
86
87 BEGIN
88 {
89  *Dir = \$Bin;
90  *RealDir = \$RealBin;
91
92  if($0 eq '-e' || $0 eq '-')
93   {
94    # perl invoked with -e or script is on C<STDIN>
95
96    $Script = $RealScript = $0;
97    $Bin    = $RealBin    = getcwd();
98   }
99  else
100   {
101    my $script = $0;
102
103    if ($^O eq 'VMS')
104     {
105      ($Bin,$Script) = VMS::Filespec::rmsexpand($0) =~ /(.*\])(.*)/s;
106      ($RealBin,$RealScript) = ($Bin,$Script);
107     }
108    else
109     {
110      my $IsWin32 = $^O eq 'MSWin32';
111      unless(($script =~ m#/# || ($IsWin32 && $script =~ m#\\#))
112             && -f $script)
113       {
114        my $dir;
115        foreach $dir (File::Spec->path)
116         {
117         my $scr = File::Spec->catfile($dir, $script);
118         if(-r $scr && (!$IsWin32 || -x _))
119          {
120           $script = $scr;
121
122           if (-f $0)
123            {
124             # $script has been found via PATH but perl could have
125             # been invoked as 'perl file'. Do a dumb check to see
126             # if $script is a perl program, if not then $script = $0
127             #
128             # well we actually only check that it is an ASCII file
129             # we know its executable so it is probably a script
130             # of some sort.
131
132             $script = $0 unless(-T $script);
133            }
134           last;
135          }
136        }
137      }
138
139      croak("Cannot find current script '$0'") unless(-f $script);
140
141      # Ensure $script contains the complete path incase we C<chdir>
142
143      $script = File::Spec->catfile(getcwd(), $script)
144        unless File::Spec->file_name_is_absolute($script);
145
146      ($Script,$Bin) = fileparse($script);
147
148      # Resolve $script if it is a link
149      while(1)
150       {
151        my $linktext = readlink($script);
152
153        ($RealScript,$RealBin) = fileparse($script);
154        last unless defined $linktext;
155
156        $script = (File::Spec->file_name_is_absolute($linktext))
157                   ? $linktext
158                   : File::Spec->catfile($RealBin, $linktext);
159       }
160
161      # Get absolute paths to directories
162      $Bin     = abs_path($Bin)     if($Bin);
163      $RealBin = abs_path($RealBin) if($RealBin);
164     }
165   }
166 }
167
168 1; # Keep require happy
169