1 package File::Spec::Mac;
4 use vars qw(@ISA $VERSION);
5 require File::Spec::Unix;
9 @ISA = qw(File::Spec::Unix);
13 $macfiles = eval { require Mac::Files };
18 File::Spec::Mac - File::Spec for Mac OS (Classic)
22 require File::Spec::Mac; # Done internally by File::Spec if needed
26 Methods for manipulating file specifications.
34 On Mac OS, there's nothing to be done. Returns what it's given.
39 my ($self,$path) = @_;
45 Concatenate two or more directory names to form a path separated by colons
46 (":") ending with a directory. Resulting paths are B<relative> by default,
47 but can be forced to be absolute (but avoid this, see below). Automatically
48 puts a trailing ":" on the end of the complete path, because that's what's
49 done in MacPerl's environment and helps to distinguish a file path from a
52 B<IMPORTANT NOTE:> Beginning with version 1.3 of this module, the resulting
53 path is relative by default and I<not> absolute. This descision was made due
54 to portability reasons. Since C<File::Spec-E<gt>catdir()> returns relative paths
55 on all other operating systems, it will now also follow this convention on Mac
56 OS. Note that this may break some existing scripts.
58 The intended purpose of this routine is to concatenate I<directory names>.
59 But because of the nature of Macintosh paths, some additional possibilities
60 are allowed to make using this routine give reasonable results for some
61 common situations. In other words, you are also allowed to concatenate
62 I<paths> instead of directory names (strictly speaking, a string like ":a"
63 is a path, but not a name, since it contains a punctuation character ":").
68 catdir("a","b") = ":a:b:"
69 catdir() = "" (special case)
71 calls like the following
74 catdir(":a","b") = ":a:b:"
75 catdir(":a:","b") = ":a:b:"
76 catdir(":a:",":b:") = ":a:b:"
81 Here are the rules that are used in C<catdir()>; note that we try to be as
82 compatible as possible to Unix:
88 The resulting path is relative by default, i.e. the resulting path will have a
93 A trailing colon is added automatically to the resulting path, to denote a
98 Generally, each argument has one leading ":" and one trailing ":"
99 removed (if any). They are then joined together by a ":". Special
100 treatment applies for arguments denoting updir paths like "::lib:",
101 see (4), or arguments consisting solely of colons ("colon paths"),
106 When an updir path like ":::lib::" is passed as argument, the number
107 of directories to climb up is handled correctly, not removing leading
108 or trailing colons when necessary. E.g.
110 catdir(":::a","::b","c") = ":::a::b:c:"
111 catdir(":::a::","::b","c") = ":::a:::b:c:"
115 Adding a colon ":" or empty string "" to a path at I<any> position
116 doesn't alter the path, i.e. these arguments are ignored. (When a ""
117 is passed as the first argument, it has a special meaning, see
118 (6)). This way, a colon ":" is handled like a "." (curdir) on Unix,
119 while an empty string "" is generally ignored (see
120 C<Unix-E<gt>canonpath()> ). Likewise, a "::" is handled like a ".."
121 (updir), and a ":::" is handled like a "../.." etc. E.g.
123 catdir("a",":",":","b") = ":a:b:"
124 catdir("a",":","::",":b") = ":a::b:"
128 If the first argument is an empty string "" or is a volume name, i.e. matches
129 the pattern /^[^:]+:/, the resulting path is B<absolute>.
133 Passing an empty string "" as the first argument to C<catdir()> is
134 like passingC<File::Spec-E<gt>rootdir()> as the first argument, i.e.
136 catdir("","a","b") is the same as
138 catdir(rootdir(),"a","b").
140 This is true on Unix, where C<catdir("","a","b")> yields "/a/b" and
141 C<rootdir()> is "/". Note that C<rootdir()> on Mac OS is the startup
142 volume, which is the closest in concept to Unix' "/". This should help
143 to run existing scripts originally written for Unix.
147 For absolute paths, some cleanup is done, to ensure that the volume
148 name isn't immediately followed by updirs. This is invalid, because
149 this would go beyond "root". Generally, these cases are handled like
150 their Unix counterparts:
153 Unix->catdir("","") = "/"
154 Unix->catdir("",".") = "/"
155 Unix->catdir("","..") = "/" # can't go beyond root
156 Unix->catdir("",".","..","..","a") = "/a"
158 Mac->catdir("","") = rootdir() # (e.g. "HD:")
159 Mac->catdir("",":") = rootdir()
160 Mac->catdir("","::") = rootdir() # can't go beyond root
161 Mac->catdir("",":","::","::","a") = rootdir() . "a:" # (e.g. "HD:a:")
163 However, this approach is limited to the first arguments following
164 "root" (again, see C<Unix-E<gt>canonpath()> ). If there are more
165 arguments that move up the directory tree, an invalid path going
166 beyond root can be created.
170 As you've seen, you can force C<catdir()> to create an absolute path
171 by passing either an empty string or a path that begins with a volume
172 name as the first argument. However, you are strongly encouraged not
173 to do so, since this is done only for backward compatibility. Newer
174 versions of File::Spec come with a method called C<catpath()> (see
175 below), that is designed to offer a portable solution for the creation
176 of absolute paths. It takes volume, directory and file portions and
177 returns an entire path. While C<catdir()> is still suitable for the
178 concatenation of I<directory names>, you are encouraged to use
179 C<catpath()> to concatenate I<volume names> and I<directory
182 $dir = File::Spec->catdir("tmp","sources");
183 $abs_path = File::Spec->catpath("MacintoshHD:", $dir,"");
187 "MacintoshHD:tmp:sources:" .
198 # take care of the first argument
200 if ($args[0] eq '') { # absolute path, rootdir
203 $first_arg = $self->rootdir;
205 } elsif ($args[0] =~ /^[^:]+:/) { # absolute path, volume name
207 $first_arg = shift @args;
208 # add a trailing ':' if need be (may be it's a path like HD:dir)
209 $first_arg = "$first_arg:" unless ($first_arg =~ /:\Z(?!\n)/);
211 } else { # relative path
213 if ( $args[0] =~ /^::+\Z(?!\n)/ ) {
214 # updir colon path ('::', ':::' etc.), don't shift
216 } elsif ($args[0] eq ':') {
217 $first_arg = shift @args;
219 # add a trailing ':' if need be
220 $first_arg = shift @args;
221 $first_arg = "$first_arg:" unless ($first_arg =~ /:\Z(?!\n)/);
225 # For all other arguments,
226 # (a) ignore arguments that equal ':' or '',
227 # (b) handle updir paths specially:
228 # '::' -> concatenate '::'
229 # '::' . '::' -> concatenate ':::' etc.
230 # (c) add a trailing ':' if need be
232 my $result = $first_arg;
234 my $arg = shift @args;
235 unless (($arg eq '') || ($arg eq ':')) {
236 if ($arg =~ /^::+\Z(?!\n)/ ) { # updir colon path like ':::'
237 my $updir_count = length($arg) - 1;
238 while ((@args) && ($args[0] =~ /^::+\Z(?!\n)/) ) { # while updir colon path
240 $updir_count += (length($arg) - 1);
242 $arg = (':' x $updir_count);
244 $arg =~ s/^://s; # remove a leading ':' if any
245 $arg = "$arg:" unless ($arg =~ /:\Z(?!\n)/); # ensure trailing ':'
251 if ( ($relative) && ($result !~ /^:/) ) {
252 # add a leading colon if need be
253 $result = ":$result";
257 # remove updirs immediately following the volume name
258 $result =~ s/([^:]+:)(:*)(.*)\Z(?!\n)/$1$3/;
266 Concatenate one or more directory names and a filename to form a
267 complete path ending with a filename. Resulting paths are B<relative>
268 by default, but can be forced to be absolute (but avoid this).
270 B<IMPORTANT NOTE:> Beginning with version 1.3 of this module, the
271 resulting path is relative by default and I<not> absolute. This
272 descision was made due to portability reasons. Since
273 C<File::Spec-E<gt>catfile()> returns relative paths on all other
274 operating systems, it will now also follow this convention on Mac OS.
275 Note that this may break some existing scripts.
277 The last argument is always considered to be the file portion. Since
278 C<catfile()> uses C<catdir()> (see above) for the concatenation of the
279 directory portions (if any), the following with regard to relative and
280 absolute paths is true:
283 catfile("file") = "file"
287 catfile("","") = rootdir() # (e.g. "HD:")
288 catfile("","file") = rootdir() . file # (e.g. "HD:file")
289 catfile("HD:","file") = "HD:file"
291 This means that C<catdir()> is called only when there are two or more
292 arguments, as one might expect.
294 Note that the leading ":" is removed from the filename, so that
296 catfile("a","b","file") = ":a:b:file" and
298 catfile("a","b",":file") = ":a:b:file"
300 give the same answer.
302 To concatenate I<volume names>, I<directory paths> and I<filenames>,
303 you are encouraged to use C<catpath()> (see below).
311 return $file unless @_;
312 my $dir = $self->catdir(@_);
319 Returns a string representing the current directory. On Mac OS, this is ":".
329 Returns a string representing the null device. On Mac OS, this is "Dev:Null".
339 Returns a string representing the root directory. Under MacPerl,
340 returns the name of the startup volume, since that's the closest in
341 concept, although other volumes aren't rooted there. The name has a
342 trailing ":", because that's the correct specification for a volume
345 If Mac::Files could not be loaded, the empty string is returned.
351 # There's no real root directory on Mac OS. The name of the startup
352 # volume is returned, since that's the closest in concept.
354 return '' unless $macfiles;
355 my $system = Mac::Files::FindFolder(&Mac::Files::kOnSystemDisk,
356 &Mac::Files::kSystemFolderType);
357 $system =~ s/:.*\Z(?!\n)/:/s;
363 Returns the contents of $ENV{TMPDIR}, if that directory exits or the
364 current working directory otherwise. Under MacPerl, $ENV{TMPDIR} will
365 contain a path like "MacintoshHD:Temporary Items:", which is a hidden
366 directory on your startup volume.
372 return $tmpdir if defined $tmpdir;
374 $tmpdir = $self->_tmpdir( $ENV{TMPDIR} );
379 Returns a string representing the parent directory. On Mac OS, this is "::".
387 =item file_name_is_absolute
389 Takes as argument a path and returns true, if it is an absolute path.
390 If the path has a leading ":", it's a relative path. Otherwise, it's an
391 absolute path, unless the path doesn't contain any colons, i.e. it's a name
392 like "a". In this particular case, the path is considered to be relative
393 (i.e. it is considered to be a filename). Use ":" in the appropriate place
394 in the path if you want to distinguish unambiguously. As a special case,
395 the filename '' is always considered to be absolute. Note that with version
396 1.2 of File::Spec::Mac, this does no longer consult the local filesystem.
400 File::Spec->file_name_is_absolute("a"); # false (relative)
401 File::Spec->file_name_is_absolute(":a:b:"); # false (relative)
402 File::Spec->file_name_is_absolute("MacintoshHD:"); # true (absolute)
403 File::Spec->file_name_is_absolute(""); # true (absolute)
408 sub file_name_is_absolute {
409 my ($self,$file) = @_;
411 return (! ($file =~ m/^:/s) );
412 } elsif ( $file eq '' ) {
415 return 0; # i.e. a file like "a"
421 Returns the null list for the MacPerl application, since the concept is
422 usually meaningless under Mac OS. But if you're using the MacPerl tool under
423 MPW, it gives back $ENV{Commands} suitably split, as is done in
424 :lib:ExtUtils:MM_Mac.pm.
430 # The concept is meaningless under the MacPerl application.
431 # Under MPW, it has a meaning.
433 return unless exists $ENV{Commands};
434 return split(/,/, $ENV{Commands});
439 ($volume,$directories,$file) = File::Spec->splitpath( $path );
440 ($volume,$directories,$file) = File::Spec->splitpath( $path, $no_file );
442 Splits a path into volume, directory, and filename portions.
444 On Mac OS, assumes that the last part of the path is a filename unless
445 $no_file is true or a trailing separator ":" is present.
447 The volume portion is always returned with a trailing ":". The directory portion
448 is always returned with a leading (to denote a relative path) and a trailing ":"
449 (to denote a directory). The file portion is always returned I<without> a leading ":".
450 Empty portions are returned as empty string ''.
452 The results can be passed to C<catpath()> to get back a path equivalent to
453 (usually identical to) the original path.
459 my ($self,$path, $nofile) = @_;
460 my ($volume,$directory,$file);
463 ( $volume, $directory ) = $path =~ m|^((?:[^:]+:)?)(.*)|s;
476 $volume = '' unless defined($volume);
477 $directory = ":$directory" if ( $volume && $directory ); # take care of "HD::dir"
479 # Make sure non-empty directories begin and end in ':'
480 $directory .= ':' unless (substr($directory,-1) eq ':');
481 $directory = ":$directory" unless (substr($directory,0,1) eq ':');
485 $file = '' unless defined($file);
487 return ($volume,$directory,$file);
493 The opposite of C<catdir()>.
495 @dirs = File::Spec->splitdir( $directories );
497 $directories should be only the directory portion of the path on systems
498 that have the concept of a volume or that have path syntax that differentiates
499 files from directories. Consider using C<splitpath()> otherwise.
501 Unlike just splitting the directories on the separator, empty directory names
502 (C<"">) can be returned. Since C<catdir()> on Mac OS always appends a trailing
503 colon to distinguish a directory path from a file path, a single trailing colon
504 will be ignored, i.e. there's no empty directory name after it.
506 Hence, on Mac OS, both
508 File::Spec->splitdir( ":a:b::c:" ); and
509 File::Spec->splitdir( ":a:b::c" );
513 ( "a", "b", "::", "c")
517 File::Spec->splitdir( ":a:b::c::" );
521 ( "a", "b", "::", "c", "::")
527 my ($self, $path) = @_;
529 my ($head, $sep, $tail, $volume, $directories);
531 return ('') if ( (!defined($path)) || ($path eq '') );
532 return (':') if ($path eq ':');
534 ( $volume, $sep, $directories ) = $path =~ m|^((?:[^:]+:)?)(:*)(.*)|s;
536 # deprecated, but handle it correctly
538 push (@result, $volume);
542 while ($sep || $directories) {
543 if (length($sep) > 1) {
544 my $updir_count = length($sep) - 1;
545 for (my $i=0; $i<$updir_count; $i++) {
546 # push '::' updir_count times;
547 # simulate Unix '..' updirs
548 push (@result, '::');
553 ( $head, $sep, $tail ) = $directories =~ m|^((?:[^:]+)?)(:*)(.*)|s;
554 push (@result, $head);
555 $directories = $tail;
564 $path = File::Spec->catpath($volume,$directory,$file);
566 Takes volume, directory and file portions and returns an entire path. On Mac OS,
567 $volume, $directory and $file are concatenated. A ':' is inserted if need be. You
568 may pass an empty string for each portion. If all portions are empty, the empty
569 string is returned. If $volume is empty, the result will be a relative path,
570 beginning with a ':'. If $volume and $directory are empty, a leading ":" (if any)
571 is removed form $file and the remainder is returned. If $file is empty, the
572 resulting path will have a trailing ':'.
578 my ($self,$volume,$directory,$file) = @_;
580 if ( (! $volume) && (! $directory) ) {
581 $file =~ s/^:// if $file;
585 my $path = $volume; # may be ''
586 $path .= ':' unless (substr($path, -1) eq ':'); # ensure trailing ':'
589 $directory =~ s/^://; # remove leading ':' if any
591 $path .= ':' unless (substr($path, -1) eq ':'); # ensure trailing ':'
595 $file =~ s/^://; # remove leading ':' if any
604 Takes a destination path and an optional base path and returns a relative path
605 from the base path to the destination path:
607 $rel_path = File::Spec->abs2rel( $path ) ;
608 $rel_path = File::Spec->abs2rel( $path, $base ) ;
610 Note that both paths are assumed to have a notation that distinguishes a
611 directory path (with trailing ':') from a file path (without trailing ':').
613 If $base is not present or '', then the current working directory is used.
614 If $base is relative, then it is converted to absolute form using C<rel2abs()>.
615 This means that it is taken to be relative to the current working directory.
617 Since Mac OS has the concept of volumes, this assumes that both paths
618 are on the $destination volume, and ignores the $base volume (!).
620 If $base doesn't have a trailing colon, the last element of $base is
621 assumed to be a filename. This filename is ignored (!). Otherwise all path
622 components are assumed to be directories.
624 If $path is relative, it is converted to absolute form using C<rel2abs()>.
625 This means that it is taken to be relative to the current working directory.
627 Based on code written by Shigio Yamaguchi.
632 # maybe this should be done in canonpath() ?
633 sub _resolve_updirs {
637 # resolve any updirs, e.g. "HD:tmp::file" -> "HD:file"
639 $proceed = ($path =~ s/^(.*):[^:]+::(.*?)\z/$1:$2/);
647 my($self,$path,$base) = @_;
650 if ( ! $self->file_name_is_absolute( $path ) ) {
651 $path = $self->rel2abs( $path ) ;
654 # Figure out the effective $base and clean it up.
655 if ( !defined( $base ) || $base eq '' ) {
658 elsif ( ! $self->file_name_is_absolute( $base ) ) {
659 $base = $self->rel2abs( $base ) ;
660 $base = _resolve_updirs( $base ); # resolve updirs in $base
663 $base = _resolve_updirs( $base );
667 my ( $path_dirs, $path_file ) = ($self->splitpath( $path ))[1,2] ;
669 # ignore $base's volume and file
670 my $base_dirs = ($self->splitpath( $base ))[1] ;
672 # Now, remove all leading components that are the same
673 my @pathchunks = $self->splitdir( $path_dirs );
674 my @basechunks = $self->splitdir( $base_dirs );
676 while ( @pathchunks &&
678 lc( $pathchunks[0] ) eq lc( $basechunks[0] ) ) {
683 # @pathchunks now has the directories to descend in to.
684 # ensure relative path, even if @pathchunks is empty
685 $path_dirs = $self->catdir( ':', @pathchunks );
687 # @basechunks now contains the number of directories to climb out of.
688 $base_dirs = (':' x @basechunks) . ':' ;
690 return $self->catpath( '', $self->catdir( $base_dirs, $path_dirs ), $path_file ) ;
695 Converts a relative path to an absolute path:
697 $abs_path = File::Spec->rel2abs( $path ) ;
698 $abs_path = File::Spec->rel2abs( $path, $base ) ;
700 Note that both paths are assumed to have a notation that distinguishes a
701 directory path (with trailing ':') from a file path (without trailing ':').
703 If $base is not present or '', then $base is set to the current working
704 directory. If $base is relative, then it is converted to absolute form
705 using C<rel2abs()>. This means that it is taken to be relative to the
706 current working directory.
708 If $base doesn't have a trailing colon, the last element of $base is
709 assumed to be a filename. This filename is ignored (!). Otherwise all path
710 components are assumed to be directories.
712 If $path is already absolute, it is returned and $base is ignored.
714 Based on code written by Shigio Yamaguchi.
719 my ($self,$path,$base) = @_;
721 if ( ! $self->file_name_is_absolute($path) ) {
722 # Figure out the effective $base and clean it up.
723 if ( !defined( $base ) || $base eq '' ) {
726 elsif ( ! $self->file_name_is_absolute($base) ) {
727 $base = $self->rel2abs($base) ;
732 # igonore $path's volume
733 my ( $path_dirs, $path_file ) = ($self->splitpath($path))[1,2] ;
735 # ignore $base's file part
736 my ( $base_vol, $base_dirs, undef ) = $self->splitpath($base) ;
739 $path_dirs = ':' if ($path_dirs eq '');
740 $base_dirs =~ s/:$//; # remove trailing ':', if any
741 $base_dirs = $base_dirs . $path_dirs;
743 $path = $self->catpath( $base_vol, $base_dirs, $path_file );
753 See the authors list in I<File::Spec>. Mac OS support by Paul Schinder
754 <schinder@pobox.com> and Thomas Wegner <wegner_thomas@yahoo.com>.