1 package File::Spec::Mac;
4 use vars qw(@ISA $VERSION);
5 require File::Spec::Unix;
9 @ISA = qw(File::Spec::Unix);
14 $macfiles = eval { require Mac::Files };
19 File::Spec::Mac - File::Spec for Mac OS (Classic)
23 require File::Spec::Mac; # Done internally by File::Spec if needed
27 Methods for manipulating file specifications.
35 On Mac OS, there's nothing to be done. Returns what it's given.
40 my ($self,$path) = @_;
46 Concatenate two or more directory names to form a path separated by colons
47 (":") ending with a directory. Resulting paths are B<relative> by default,
48 but can be forced to be absolute (but avoid this, see below). Automatically
49 puts a trailing ":" on the end of the complete path, because that's what's
50 done in MacPerl's environment and helps to distinguish a file path from a
53 B<IMPORTANT NOTE:> Beginning with version 1.3 of this module, the resulting
54 path is relative by default and I<not> absolute. This descision was made due
55 to portability reasons. Since C<File::Spec-E<gt>catdir()> returns relative paths
56 on all other operating systems, it will now also follow this convention on Mac
57 OS. Note that this may break some existing scripts.
59 The intended purpose of this routine is to concatenate I<directory names>.
60 But because of the nature of Macintosh paths, some additional possibilities
61 are allowed to make using this routine give reasonable results for some
62 common situations. In other words, you are also allowed to concatenate
63 I<paths> instead of directory names (strictly speaking, a string like ":a"
64 is a path, but not a name, since it contains a punctuation character ":").
69 catdir("a","b") = ":a:b:"
70 catdir() = "" (special case)
72 calls like the following
75 catdir(":a","b") = ":a:b:"
76 catdir(":a:","b") = ":a:b:"
77 catdir(":a:",":b:") = ":a:b:"
82 Here are the rules that are used in C<catdir()>; note that we try to be as
83 compatible as possible to Unix:
89 The resulting path is relative by default, i.e. the resulting path will have a
94 A trailing colon is added automatically to the resulting path, to denote a
99 Generally, each argument has one leading ":" and one trailing ":"
100 removed (if any). They are then joined together by a ":". Special
101 treatment applies for arguments denoting updir paths like "::lib:",
102 see (4), or arguments consisting solely of colons ("colon paths"),
107 When an updir path like ":::lib::" is passed as argument, the number
108 of directories to climb up is handled correctly, not removing leading
109 or trailing colons when necessary. E.g.
111 catdir(":::a","::b","c") = ":::a::b:c:"
112 catdir(":::a::","::b","c") = ":::a:::b:c:"
116 Adding a colon ":" or empty string "" to a path at I<any> position
117 doesn't alter the path, i.e. these arguments are ignored. (When a ""
118 is passed as the first argument, it has a special meaning, see
119 (6)). This way, a colon ":" is handled like a "." (curdir) on Unix,
120 while an empty string "" is generally ignored (see
121 C<Unix-E<gt>canonpath()> ). Likewise, a "::" is handled like a ".."
122 (updir), and a ":::" is handled like a "../.." etc. E.g.
124 catdir("a",":",":","b") = ":a:b:"
125 catdir("a",":","::",":b") = ":a::b:"
129 If the first argument is an empty string "" or is a volume name, i.e. matches
130 the pattern /^[^:]+:/, the resulting path is B<absolute>.
134 Passing an empty string "" as the first argument to C<catdir()> is
135 like passingC<File::Spec-E<gt>rootdir()> as the first argument, i.e.
137 catdir("","a","b") is the same as
139 catdir(rootdir(),"a","b").
141 This is true on Unix, where C<catdir("","a","b")> yields "/a/b" and
142 C<rootdir()> is "/". Note that C<rootdir()> on Mac OS is the startup
143 volume, which is the closest in concept to Unix' "/". This should help
144 to run existing scripts originally written for Unix.
148 For absolute paths, some cleanup is done, to ensure that the volume
149 name isn't immediately followed by updirs. This is invalid, because
150 this would go beyond "root". Generally, these cases are handled like
151 their Unix counterparts:
154 Unix->catdir("","") = "/"
155 Unix->catdir("",".") = "/"
156 Unix->catdir("","..") = "/" # can't go beyond root
157 Unix->catdir("",".","..","..","a") = "/a"
159 Mac->catdir("","") = rootdir() # (e.g. "HD:")
160 Mac->catdir("",":") = rootdir()
161 Mac->catdir("","::") = rootdir() # can't go beyond root
162 Mac->catdir("",":","::","::","a") = rootdir() . "a:" # (e.g. "HD:a:")
164 However, this approach is limited to the first arguments following
165 "root" (again, see C<Unix-E<gt>canonpath()> ). If there are more
166 arguments that move up the directory tree, an invalid path going
167 beyond root can be created.
171 As you've seen, you can force C<catdir()> to create an absolute path
172 by passing either an empty string or a path that begins with a volume
173 name as the first argument. However, you are strongly encouraged not
174 to do so, since this is done only for backward compatibility. Newer
175 versions of File::Spec come with a method called C<catpath()> (see
176 below), that is designed to offer a portable solution for the creation
177 of absolute paths. It takes volume, directory and file portions and
178 returns an entire path. While C<catdir()> is still suitable for the
179 concatenation of I<directory names>, you are encouraged to use
180 C<catpath()> to concatenate I<volume names> and I<directory
183 $dir = File::Spec->catdir("tmp","sources");
184 $abs_path = File::Spec->catpath("MacintoshHD:", $dir,"");
188 "MacintoshHD:tmp:sources:" .
199 # take care of the first argument
201 if ($args[0] eq '') { # absolute path, rootdir
204 $first_arg = $self->rootdir;
206 } elsif ($args[0] =~ /^[^:]+:/) { # absolute path, volume name
208 $first_arg = shift @args;
209 # add a trailing ':' if need be (may be it's a path like HD:dir)
210 $first_arg = "$first_arg:" unless ($first_arg =~ /:\Z(?!\n)/);
212 } else { # relative path
214 if ( $args[0] =~ /^::+\Z(?!\n)/ ) {
215 # updir colon path ('::', ':::' etc.), don't shift
217 } elsif ($args[0] eq ':') {
218 $first_arg = shift @args;
220 # add a trailing ':' if need be
221 $first_arg = shift @args;
222 $first_arg = "$first_arg:" unless ($first_arg =~ /:\Z(?!\n)/);
226 # For all other arguments,
227 # (a) ignore arguments that equal ':' or '',
228 # (b) handle updir paths specially:
229 # '::' -> concatenate '::'
230 # '::' . '::' -> concatenate ':::' etc.
231 # (c) add a trailing ':' if need be
233 my $result = $first_arg;
235 my $arg = shift @args;
236 unless (($arg eq '') || ($arg eq ':')) {
237 if ($arg =~ /^::+\Z(?!\n)/ ) { # updir colon path like ':::'
238 my $updir_count = length($arg) - 1;
239 while ((@args) && ($args[0] =~ /^::+\Z(?!\n)/) ) { # while updir colon path
241 $updir_count += (length($arg) - 1);
243 $arg = (':' x $updir_count);
245 $arg =~ s/^://s; # remove a leading ':' if any
246 $arg = "$arg:" unless ($arg =~ /:\Z(?!\n)/); # ensure trailing ':'
252 if ( ($relative) && ($result !~ /^:/) ) {
253 # add a leading colon if need be
254 $result = ":$result";
258 # remove updirs immediately following the volume name
259 $result =~ s/([^:]+:)(:*)(.*)\Z(?!\n)/$1$3/;
267 Concatenate one or more directory names and a filename to form a
268 complete path ending with a filename. Resulting paths are B<relative>
269 by default, but can be forced to be absolute (but avoid this).
271 B<IMPORTANT NOTE:> Beginning with version 1.3 of this module, the
272 resulting path is relative by default and I<not> absolute. This
273 descision was made due to portability reasons. Since
274 C<File::Spec-E<gt>catfile()> returns relative paths on all other
275 operating systems, it will now also follow this convention on Mac OS.
276 Note that this may break some existing scripts.
278 The last argument is always considered to be the file portion. Since
279 C<catfile()> uses C<catdir()> (see above) for the concatenation of the
280 directory portions (if any), the following with regard to relative and
281 absolute paths is true:
284 catfile("file") = "file"
288 catfile("","") = rootdir() # (e.g. "HD:")
289 catfile("","file") = rootdir() . file # (e.g. "HD:file")
290 catfile("HD:","file") = "HD:file"
292 This means that C<catdir()> is called only when there are two or more
293 arguments, as one might expect.
295 Note that the leading ":" is removed from the filename, so that
297 catfile("a","b","file") = ":a:b:file" and
299 catfile("a","b",":file") = ":a:b:file"
301 give the same answer.
303 To concatenate I<volume names>, I<directory paths> and I<filenames>,
304 you are encouraged to use C<catpath()> (see below).
312 return $file unless @_;
313 my $dir = $self->catdir(@_);
320 Returns a string representing the current directory. On Mac OS, this is ":".
330 Returns a string representing the null device. On Mac OS, this is "Dev:Null".
340 Returns a string representing the root directory. Under MacPerl,
341 returns the name of the startup volume, since that's the closest in
342 concept, although other volumes aren't rooted there. The name has a
343 trailing ":", because that's the correct specification for a volume
346 If Mac::Files could not be loaded, the empty string is returned.
352 # There's no real root directory on Mac OS. The name of the startup
353 # volume is returned, since that's the closest in concept.
355 return '' unless $macfiles;
356 my $system = Mac::Files::FindFolder(&Mac::Files::kOnSystemDisk,
357 &Mac::Files::kSystemFolderType);
358 $system =~ s/:.*\Z(?!\n)/:/s;
364 Returns the contents of $ENV{TMPDIR}, if that directory exits or the current working
365 directory otherwise. Under MacPerl, $ENV{TMPDIR} will contain a path like
366 "MacintoshHD:Temporary Items:", which is a hidden directory on your startup volume.
372 return $tmpdir if defined $tmpdir;
373 $tmpdir = $ENV{TMPDIR} if -d $ENV{TMPDIR};
374 unless (defined($tmpdir)) {
382 Returns a string representing the parent directory. On Mac OS, this is "::".
390 =item file_name_is_absolute
392 Takes as argument a path and returns true, if it is an absolute path.
393 If the path has a leading ":", it's a relative path. Otherwise, it's an
394 absolute path, unless the path doesn't contain any colons, i.e. it's a name
395 like "a". In this particular case, the path is considered to be relative
396 (i.e. it is considered to be a filename). Use ":" in the appropriate place
397 in the path if you want to distinguish unambiguously. As a special case,
398 the filename '' is always considered to be absolute. Note that with version
399 1.2 of File::Spec::Mac, this does no longer consult the local filesystem.
403 File::Spec->file_name_is_absolute("a"); # false (relative)
404 File::Spec->file_name_is_absolute(":a:b:"); # false (relative)
405 File::Spec->file_name_is_absolute("MacintoshHD:"); # true (absolute)
406 File::Spec->file_name_is_absolute(""); # true (absolute)
411 sub file_name_is_absolute {
412 my ($self,$file) = @_;
414 return (! ($file =~ m/^:/s) );
415 } elsif ( $file eq '' ) {
418 return 0; # i.e. a file like "a"
424 Returns the null list for the MacPerl application, since the concept is
425 usually meaningless under Mac OS. But if you're using the MacPerl tool under
426 MPW, it gives back $ENV{Commands} suitably split, as is done in
427 :lib:ExtUtils:MM_Mac.pm.
433 # The concept is meaningless under the MacPerl application.
434 # Under MPW, it has a meaning.
436 return unless exists $ENV{Commands};
437 return split(/,/, $ENV{Commands});
442 ($volume,$directories,$file) = File::Spec->splitpath( $path );
443 ($volume,$directories,$file) = File::Spec->splitpath( $path, $no_file );
445 Splits a path in to volume, directory, and filename portions.
447 On Mac OS, assumes that the last part of the path is a filename unless
448 $no_file is true or a trailing separator ":" is present.
450 The volume portion is always returned with a trailing ":". The directory portion
451 is always returned with a leading (to denote a relative path) and a trailing ":"
452 (to denote a directory). The file portion is always returned I<without> a leading ":".
453 Empty portions are returned as empty string ''.
455 The results can be passed to C<catpath()> to get back a path equivalent to
456 (usually identical to) the original path.
462 my ($self,$path, $nofile) = @_;
463 my ($volume,$directory,$file);
466 ( $volume, $directory ) = $path =~ m|^((?:[^:]+:)?)(.*)|s;
479 $volume = '' unless defined($volume);
480 $directory = ":$directory" if ( $volume && $directory ); # take care of "HD::dir"
482 # Make sure non-empty directories begin and end in ':'
483 $directory .= ':' unless (substr($directory,-1) eq ':');
484 $directory = ":$directory" unless (substr($directory,0,1) eq ':');
488 $file = '' unless defined($file);
490 return ($volume,$directory,$file);
496 The opposite of C<catdir()>.
498 @dirs = File::Spec->splitdir( $directories );
500 $directories should be only the directory portion of the path on systems
501 that have the concept of a volume or that have path syntax that differentiates
502 files from directories. Consider using C<splitpath()> otherwise.
504 Unlike just splitting the directories on the separator, empty directory names
505 (C<"">) can be returned. Since C<catdir()> on Mac OS always appends a trailing
506 colon to distinguish a directory path from a file path, a single trailing colon
507 will be ignored, i.e. there's no empty directory name after it.
509 Hence, on Mac OS, both
511 File::Spec->splitdir( ":a:b::c:" ); and
512 File::Spec->splitdir( ":a:b::c" );
516 ( "a", "b", "::", "c")
520 File::Spec->splitdir( ":a:b::c::" );
524 ( "a", "b", "::", "c", "::")
530 my ($self, $path) = @_;
532 my ($head, $sep, $tail, $volume, $directories);
534 return ('') if ( (!defined($path)) || ($path eq '') );
535 return (':') if ($path eq ':');
537 ( $volume, $sep, $directories ) = $path =~ m|^((?:[^:]+:)?)(:*)(.*)|s;
539 # deprecated, but handle it correctly
541 push (@result, $volume);
545 while ($sep || $directories) {
546 if (length($sep) > 1) {
547 my $updir_count = length($sep) - 1;
548 for (my $i=0; $i<$updir_count; $i++) {
549 # push '::' updir_count times;
550 # simulate Unix '..' updirs
551 push (@result, '::');
556 ( $head, $sep, $tail ) = $directories =~ m|^((?:[^:]+)?)(:*)(.*)|s;
557 push (@result, $head);
558 $directories = $tail;
567 $path = File::Spec->catpath($volume,$directory,$file);
569 Takes volume, directory and file portions and returns an entire path. On Mac OS,
570 $volume, $directory and $file are concatenated. A ':' is inserted if need be. You
571 may pass an empty string for each portion. If all portions are empty, the empty
572 string is returned. If $volume is empty, the result will be a relative path,
573 beginning with a ':'. If $volume and $directory are empty, a leading ":" (if any)
574 is removed form $file and the remainder is returned. If $file is empty, the
575 resulting path will have a trailing ':'.
581 my ($self,$volume,$directory,$file) = @_;
583 if ( (! $volume) && (! $directory) ) {
584 $file =~ s/^:// if $file;
588 my $path = $volume; # may be ''
589 $path .= ':' unless (substr($path, -1) eq ':'); # ensure trailing ':'
592 $directory =~ s/^://; # remove leading ':' if any
594 $path .= ':' unless (substr($path, -1) eq ':'); # ensure trailing ':'
598 $file =~ s/^://; # remove leading ':' if any
607 Takes a destination path and an optional base path and returns a relative path
608 from the base path to the destination path:
610 $rel_path = File::Spec->abs2rel( $path ) ;
611 $rel_path = File::Spec->abs2rel( $path, $base ) ;
613 Note that both paths are assumed to have a notation that distinguishes a
614 directory path (with trailing ':') from a file path (without trailing ':').
616 If $base is not present or '', then the current working directory is used.
617 If $base is relative, then it is converted to absolute form using C<rel2abs()>.
618 This means that it is taken to be relative to the current working directory.
620 Since Mac OS has the concept of volumes, this assumes that both paths
621 are on the $destination volume, and ignores the $base volume (!).
623 If $base doesn't have a trailing colon, the last element of $base is
624 assumed to be a filename. This filename is ignored (!). Otherwise all path
625 components are assumed to be directories.
627 If $path is relative, it is converted to absolute form using C<rel2abs()>.
628 This means that it is taken to be relative to the current working directory.
630 Based on code written by Shigio Yamaguchi.
635 # maybe this should be done in canonpath() ?
636 sub _resolve_updirs {
640 # resolve any updirs, e.g. "HD:tmp::file" -> "HD:file"
642 $proceed = ($path =~ s/^(.*):[^:]+::(.*?)\z/$1:$2/);
650 my($self,$path,$base) = @_;
653 if ( ! $self->file_name_is_absolute( $path ) ) {
654 $path = $self->rel2abs( $path ) ;
657 # Figure out the effective $base and clean it up.
658 if ( !defined( $base ) || $base eq '' ) {
661 elsif ( ! $self->file_name_is_absolute( $base ) ) {
662 $base = $self->rel2abs( $base ) ;
663 $base = _resolve_updirs( $base ); # resolve updirs in $base
666 $base = _resolve_updirs( $base );
670 my ( $path_dirs, $path_file ) = ($self->splitpath( $path ))[1,2] ;
672 # ignore $base's volume and file
673 my $base_dirs = ($self->splitpath( $base ))[1] ;
675 # Now, remove all leading components that are the same
676 my @pathchunks = $self->splitdir( $path_dirs );
677 my @basechunks = $self->splitdir( $base_dirs );
679 while ( @pathchunks &&
681 lc( $pathchunks[0] ) eq lc( $basechunks[0] ) ) {
686 # @pathchunks now has the directories to descend in to.
687 # ensure relative path, even if @pathchunks is empty
688 $path_dirs = $self->catdir( ':', @pathchunks );
690 # @basechunks now contains the number of directories to climb out of.
691 $base_dirs = (':' x @basechunks) . ':' ;
693 return $self->catpath( '', $self->catdir( $base_dirs, $path_dirs ), $path_file ) ;
698 Converts a relative path to an absolute path:
700 $abs_path = File::Spec->rel2abs( $path ) ;
701 $abs_path = File::Spec->rel2abs( $path, $base ) ;
703 Note that both paths are assumed to have a notation that distinguishes a
704 directory path (with trailing ':') from a file path (without trailing ':').
706 If $base is not present or '', then $base is set to the current working
707 directory. If $base is relative, then it is converted to absolute form
708 using C<rel2abs()>. This means that it is taken to be relative to the
709 current working directory.
711 If $base doesn't have a trailing colon, the last element of $base is
712 assumed to be a filename. This filename is ignored (!). Otherwise all path
713 components are assumed to be directories.
715 If $path is already absolute, it is returned and $base is ignored.
717 Based on code written by Shigio Yamaguchi.
722 my ($self,$path,$base) = @_;
724 if ( ! $self->file_name_is_absolute($path) ) {
725 # Figure out the effective $base and clean it up.
726 if ( !defined( $base ) || $base eq '' ) {
729 elsif ( ! $self->file_name_is_absolute($base) ) {
730 $base = $self->rel2abs($base) ;
735 # igonore $path's volume
736 my ( $path_dirs, $path_file ) = ($self->splitpath($path))[1,2] ;
738 # ignore $base's file part
739 my ( $base_vol, $base_dirs, undef ) = $self->splitpath($base) ;
742 $path_dirs = ':' if ($path_dirs eq '');
743 $base_dirs =~ s/:$//; # remove trailing ':', if any
744 $base_dirs = $base_dirs . $path_dirs;
746 $path = $self->catpath( $base_vol, $base_dirs, $path_file );
756 See the authors list in I<File::Spec>. Mac OS support by Paul Schinder
757 <schinder@pobox.com> and Thomas Wegner <wegner_thomas@yahoo.com>.