lib/File/Spec/Mac.pm

   1 package File::Spec::Mac;
   2
   3 use strict;
   4 use vars qw(@ISA);
   5 require File::Spec::Unix;
   6 @ISA = qw(File::Spec::Unix);
   7
   8 =head1 NAME
   9
  10 File::Spec::Mac - File::Spec for MacOS
  11
  12 =head1 SYNOPSIS
  13
  14  require File::Spec::Mac; # Done internally by File::Spec if needed
  15
  16 =head1 DESCRIPTION
  17
  18 Methods for manipulating file specifications.
  19
  20 =head1 METHODS
  21
  22 =over 2
  23
  24 =item canonpath
  25
  26 On MacOS, there's nothing to be done.  Returns what it's given.
  27
  28 =cut
  29
  30 sub canonpath {
  31     my ($self,$path) = @_;
  32     return $path;
  33 }
  34
  35 =item catdir
  36
  37 Concatenate two or more directory names to form a complete path ending with
  38 a directory.  Put a trailing : on the end of the complete path if there
  39 isn't one, because that's what's done in MacPerl's environment.
  40
  41 The fundamental requirement of this routine is that
  42
  43           File::Spec->catdir(split(":",$path)) eq $path
  44
  45 But because of the nature of Macintosh paths, some additional
  46 possibilities are allowed to make using this routine give reasonable results
  47 for some common situations.  Here are the rules that are used.  Each
  48 argument has its trailing ":" removed.  Each argument, except the first,
  49 has its leading ":" removed.  They are then joined together by a ":".
  50
  51 So
  52
  53           File::Spec->catdir("a","b") = "a:b:"
  54           File::Spec->catdir("a:",":b") = "a:b:"
  55           File::Spec->catdir("a:","b") = "a:b:"
  56           File::Spec->catdir("a",":b") = "a:b"
  57           File::Spec->catdir("a","","b") = "a::b"
  58
  59 etc.
  60
  61 To get a relative path (one beginning with :), begin the first argument with :
  62 or put a "" as the first argument.
  63
  64 If you don't want to worry about these rules, never allow a ":" on the ends
  65 of any of the arguments except at the beginning of the first.
  66
  67 Under MacPerl, there is an additional ambiguity.  Does the user intend that
  68
  69           File::Spec->catfile("LWP","Protocol","http.pm")
  70
  71 be relative or absolute?  There's no way of telling except by checking for the
  72 existence of LWP: or :LWP, and even there he may mean a dismounted volume or
  73 a relative path in a different directory (like in @INC).   So those checks
  74 aren't done here. This routine will treat this as absolute.
  75
  76 =cut
  77
  78 sub catdir {
  79     shift;
  80     my @args = @_;
  81     my $result = shift @args;
  82     $result =~ s/:$//;
  83     foreach (@args) {
  84         s/:$//;
  85         s/^://;
  86         $result .= ":$_";
  87     }
  88     return "$result:";
  89 }
  90
  91 =item catfile
  92
  93 Concatenate one or more directory names and a filename to form a
  94 complete path ending with a filename.  Since this uses catdir, the
  95 same caveats apply.  Note that the leading : is removed from the filename,
  96 so that
  97
  98           File::Spec->catfile($ENV{HOME},"file");
  99
 100 and
 101
 102           File::Spec->catfile($ENV{HOME},":file");
 103
 104 give the same answer, as one might expect.
 105
 106 =cut
 107
 108 sub catfile {
 109     my $self = shift;
 110     my $file = pop @_;
 111     return $file unless @_;
 112     my $dir = $self->catdir(@_);
 113     $file =~ s/^://;
 114     return $dir.$file;
 115 }
 116
 117 =item curdir
 118
 119 Returns a string representing the current directory.
 120
 121 =cut
 122
 123 sub curdir {
 124     return ":";
 125 }
 126
 127 =item devnull
 128
 129 Returns a string representing the null device.
 130
 131 =cut
 132
 133 sub devnull {
 134     return "Dev:Null";
 135 }
 136
 137 =item rootdir
 138
 139 Returns a string representing the root directory.  Under MacPerl,
 140 returns the name of the startup volume, since that's the closest in
 141 concept, although other volumes aren't rooted there.
 142
 143 =cut
 144
 145 sub rootdir {
 146 #
 147 #  There's no real root directory on MacOS.  The name of the startup
 148 #  volume is returned, since that's the closest in concept.
 149 #
 150     require Mac::Files;
 151     my $system =  Mac::Files::FindFolder(&Mac::Files::kOnSystemDisk,
 152                                          &Mac::Files::kSystemFolderType);
 153     $system =~ s/:.*$/:/;
 154     return $system;
 155 }
 156
 157 =item tmpdir
 158
 159 Returns a string representation of the first existing directory
 160 from the following list or '' if none exist:
 161
 162     $ENV{TMPDIR}
 163
 164 =cut
 165
 166 my $tmpdir;
 167 sub tmpdir {
 168     return $tmpdir if defined $tmpdir;
 169     $tmpdir = $ENV{TMPDIR} if -d $ENV{TMPDIR};
 170     $tmpdir = '' unless defined $tmpdir;
 171     return $tmpdir;
 172 }
 173
 174 =item updir
 175
 176 Returns a string representing the parent directory.
 177
 178 =cut
 179
 180 sub updir {
 181     return "::";
 182 }
 183
 184 =item file_name_is_absolute
 185
 186 Takes as argument a path and returns true, if it is an absolute path.  In
 187 the case where a name can be either relative or absolute (for example, a
 188 folder named "HD" in the current working directory on a drive named "HD"),
 189 relative wins.  Use ":" in the appropriate place in the path if you want to
 190 distinguish unambiguously.
 191
 192 =cut
 193
 194 sub file_name_is_absolute {
 195     my ($self,$file) = @_;
 196     if ($file =~ /:/) {
 197         return ($file !~ m/^:/);
 198     } else {
 199         return (! -e ":$file");
 200     }
 201 }
 202
 203 =item path
 204
 205 Returns the null list for the MacPerl application, since the concept is
 206 usually meaningless under MacOS. But if you're using the MacPerl tool under
 207 MPW, it gives back $ENV{Commands} suitably split, as is done in
 208 :lib:ExtUtils:MM_Mac.pm.
 209
 210 =cut
 211
 212 sub path {
 213 #
 214 #  The concept is meaningless under the MacPerl application.
 215 #  Under MPW, it has a meaning.
 216 #
 217     return unless exists $ENV{Commands};
 218     return split(/,/, $ENV{Commands});
 219 }
 220
 221 =back
 222
 223 =head1 SEE ALSO
 224
 225 L<File::Spec>
 226
 227 =cut
 228
 229 1;