1File::Spec::Mac(3)    User Contributed Perl Documentation   File::Spec::Mac(3)
2
3
4

NAME

6       File::Spec::Mac - File::Spec for Mac OS (Classic)
7

SYNOPSIS

9        require File::Spec::Mac; # Done internally by File::Spec if needed
10

DESCRIPTION

12       Methods for manipulating file specifications.
13

METHODS

15       canonpath
16         On Mac OS, there's nothing to be done. Returns what it's given.
17
18       catdir()
19         Concatenate two or more directory names to form a path separated by
20         colons (":") ending with a directory. Resulting paths are relative by
21         default, but can be forced to be absolute (but avoid this, see
22         below). Automatically puts a trailing ":" on the end of the complete
23         path, because that's what's done in MacPerl's environment and helps
24         to distinguish a file path from a directory path.
25
26         IMPORTANT NOTE: Beginning with version 1.3 of this module, the
27         resulting path is relative by default and not absolute. This decision
28         was made due to portability reasons. Since "File::Spec->catdir()"
29         returns relative paths on all other operating systems, it will now
30         also follow this convention on Mac OS. Note that this may break some
31         existing scripts.
32
33         The intended purpose of this routine is to concatenate directory
34         names.  But because of the nature of Macintosh paths, some additional
35         possibilities are allowed to make using this routine give reasonable
36         results for some common situations. In other words, you are also
37         allowed to concatenate paths instead of directory names (strictly
38         speaking, a string like ":a" is a path, but not a name, since it
39         contains a punctuation character ":").
40
41         So, beside calls like
42
43             catdir("a") = ":a:"
44             catdir("a","b") = ":a:b:"
45             catdir() = ""                    (special case)
46
47         calls like the following
48
49             catdir(":a:") = ":a:"
50             catdir(":a","b") = ":a:b:"
51             catdir(":a:","b") = ":a:b:"
52             catdir(":a:",":b:") = ":a:b:"
53             catdir(":") = ":"
54
55         are allowed.
56
57         Here are the rules that are used in "catdir()"; note that we try to
58         be as compatible as possible to Unix:
59
60         1.
61           The resulting path is relative by default, i.e. the resulting path
62           will have a leading colon.
63
64         2.
65           A trailing colon is added automatically to the resulting path, to
66           denote a directory.
67
68         3.
69           Generally, each argument has one leading ":" and one trailing ":"
70           removed (if any). They are then joined together by a ":". Special
71           treatment applies for arguments denoting updir paths like "::lib:",
72           see (4), or arguments consisting solely of colons ("colon paths"),
73           see (5).
74
75         4.
76           When an updir path like ":::lib::" is passed as argument, the
77           number of directories to climb up is handled correctly, not
78           removing leading or trailing colons when necessary. E.g.
79
80               catdir(":::a","::b","c")    = ":::a::b:c:"
81               catdir(":::a::","::b","c")  = ":::a:::b:c:"
82
83         5.
84           Adding a colon ":" or empty string "" to a path at any position
85           doesn't alter the path, i.e. these arguments are ignored. (When a
86           "" is passed as the first argument, it has a special meaning, see
87           (6)). This way, a colon ":" is handled like a "." (curdir) on Unix,
88           while an empty string "" is generally ignored (see "canonpath()" in
89           File::Spec::Unix ). Likewise, a "::" is handled like a ".."
90           (updir), and a ":::" is handled like a "../.." etc.  E.g.
91
92               catdir("a",":",":","b")   = ":a:b:"
93               catdir("a",":","::",":b") = ":a::b:"
94
95         6.
96           If the first argument is an empty string "" or is a volume name,
97           i.e. matches the pattern /^[^:]+:/, the resulting path is absolute.
98
99         7.
100           Passing an empty string "" as the first argument to "catdir()" is
101           like passing"File::Spec->rootdir()" as the first argument, i.e.
102
103               catdir("","a","b")          is the same as
104
105               catdir(rootdir(),"a","b").
106
107           This is true on Unix, where "catdir("","a","b")" yields "/a/b" and
108           "rootdir()" is "/". Note that "rootdir()" on Mac OS is the startup
109           volume, which is the closest in concept to Unix' "/". This should
110           help to run existing scripts originally written for Unix.
111
112         8.
113           For absolute paths, some cleanup is done, to ensure that the volume
114           name isn't immediately followed by updirs. This is invalid, because
115           this would go beyond "root". Generally, these cases are handled
116           like their Unix counterparts:
117
118            Unix:
119               Unix->catdir("","")                 =  "/"
120               Unix->catdir("",".")                =  "/"
121               Unix->catdir("","..")               =  "/"        # can't go
122                                                                 # beyond root
123               Unix->catdir("",".","..","..","a")  =  "/a"
124            Mac:
125               Mac->catdir("","")                  =  rootdir()  # (e.g. "HD:")
126               Mac->catdir("",":")                 =  rootdir()
127               Mac->catdir("","::")                =  rootdir()  # can't go
128                                                                 # beyond root
129               Mac->catdir("",":","::","::","a")   =  rootdir() . "a:"
130                                                               # (e.g. "HD:a:")
131
132           However, this approach is limited to the first arguments following
133           "root" (again, see "canonpath()" in File::Spec::Unix. If there are
134           more arguments that move up the directory tree, an invalid path
135           going beyond root can be created.
136
137         As you've seen, you can force "catdir()" to create an absolute path
138         by passing either an empty string or a path that begins with a volume
139         name as the first argument. However, you are strongly encouraged not
140         to do so, since this is done only for backward compatibility. Newer
141         versions of File::Spec come with a method called "catpath()" (see
142         below), that is designed to offer a portable solution for the
143         creation of absolute paths.  It takes volume, directory and file
144         portions and returns an entire path. While "catdir()" is still
145         suitable for the concatenation of directory names, you are encouraged
146         to use "catpath()" to concatenate volume names and directory paths.
147         E.g.
148
149             $dir      = File::Spec->catdir("tmp","sources");
150             $abs_path = File::Spec->catpath("MacintoshHD:", $dir,"");
151
152         yields
153
154             "MacintoshHD:tmp:sources:" .
155
156       catfile
157         Concatenate one or more directory names and a filename to form a
158         complete path ending with a filename. Resulting paths are relative by
159         default, but can be forced to be absolute (but avoid this).
160
161         IMPORTANT NOTE: Beginning with version 1.3 of this module, the
162         resulting path is relative by default and not absolute. This decision
163         was made due to portability reasons. Since "File::Spec->catfile()"
164         returns relative paths on all other operating systems, it will now
165         also follow this convention on Mac OS.  Note that this may break some
166         existing scripts.
167
168         The last argument is always considered to be the file portion. Since
169         "catfile()" uses "catdir()" (see above) for the concatenation of the
170         directory portions (if any), the following with regard to relative
171         and absolute paths is true:
172
173             catfile("")     = ""
174             catfile("file") = "file"
175
176         but
177
178             catfile("","")        = rootdir()         # (e.g. "HD:")
179             catfile("","file")    = rootdir() . file  # (e.g. "HD:file")
180             catfile("HD:","file") = "HD:file"
181
182         This means that "catdir()" is called only when there are two or more
183         arguments, as one might expect.
184
185         Note that the leading ":" is removed from the filename, so that
186
187             catfile("a","b","file")  = ":a:b:file"    and
188
189             catfile("a","b",":file") = ":a:b:file"
190
191         give the same answer.
192
193         To concatenate volume names, directory paths and filenames, you are
194         encouraged to use "catpath()" (see below).
195
196       curdir
197         Returns a string representing the current directory. On Mac OS, this
198         is ":".
199
200       devnull
201         Returns a string representing the null device. On Mac OS, this is
202         "Dev:Null".
203
204       rootdir
205         Returns the empty string.  Mac OS has no real root directory.
206
207       tmpdir
208         Returns the contents of $ENV{TMPDIR}, if that directory exits or the
209         current working directory otherwise. Under MacPerl, $ENV{TMPDIR} will
210         contain a path like "MacintoshHD:Temporary Items:", which is a hidden
211         directory on your startup volume.
212
213       updir
214         Returns a string representing the parent directory. On Mac OS, this
215         is "::".
216
217       file_name_is_absolute
218         Takes as argument a path and returns true, if it is an absolute path.
219         If the path has a leading ":", it's a relative path. Otherwise, it's
220         an absolute path, unless the path doesn't contain any colons, i.e.
221         it's a name like "a". In this particular case, the path is considered
222         to be relative (i.e. it is considered to be a filename). Use ":" in
223         the appropriate place in the path if you want to distinguish
224         unambiguously. As a special case, the filename '' is always
225         considered to be absolute. Note that with version 1.2 of
226         File::Spec::Mac, this does no longer consult the local filesystem.
227
228         E.g.
229
230             File::Spec->file_name_is_absolute("a");         # false (relative)
231             File::Spec->file_name_is_absolute(":a:b:");     # false (relative)
232             File::Spec->file_name_is_absolute("MacintoshHD:");
233                                                             # true (absolute)
234             File::Spec->file_name_is_absolute("");          # true (absolute)
235
236       path
237         Returns the null list for the MacPerl application, since the concept
238         is usually meaningless under Mac OS. But if you're using the MacPerl
239         tool under MPW, it gives back $ENV{Commands} suitably split, as is
240         done in :lib:ExtUtils:MM_Mac.pm.
241
242       splitpath
243             ($volume,$directories,$file) = File::Spec->splitpath( $path );
244             ($volume,$directories,$file) = File::Spec->splitpath( $path,
245                                                                   $no_file );
246
247         Splits a path into volume, directory, and filename portions.
248
249         On Mac OS, assumes that the last part of the path is a filename
250         unless $no_file is true or a trailing separator ":" is present.
251
252         The volume portion is always returned with a trailing ":". The
253         directory portion is always returned with a leading (to denote a
254         relative path) and a trailing ":" (to denote a directory). The file
255         portion is always returned without a leading ":".  Empty portions are
256         returned as empty string ''.
257
258         The results can be passed to "catpath()" to get back a path
259         equivalent to (usually identical to) the original path.
260
261       splitdir
262         The opposite of "catdir()".
263
264             @dirs = File::Spec->splitdir( $directories );
265
266         $directories should be only the directory portion of the path on
267         systems that have the concept of a volume or that have path syntax
268         that differentiates files from directories. Consider using
269         "splitpath()" otherwise.
270
271         Unlike just splitting the directories on the separator, empty
272         directory names ("") can be returned. Since "catdir()" on Mac OS
273         always appends a trailing colon to distinguish a directory path from
274         a file path, a single trailing colon will be ignored, i.e. there's no
275         empty directory name after it.
276
277         Hence, on Mac OS, both
278
279             File::Spec->splitdir( ":a:b::c:" );    and
280             File::Spec->splitdir( ":a:b::c" );
281
282         yield:
283
284             ( "a", "b", "::", "c")
285
286         while
287
288             File::Spec->splitdir( ":a:b::c::" );
289
290         yields:
291
292             ( "a", "b", "::", "c", "::")
293
294       catpath
295             $path = File::Spec->catpath($volume,$directory,$file);
296
297         Takes volume, directory and file portions and returns an entire path.
298         On Mac OS, $volume, $directory and $file are concatenated.  A ':' is
299         inserted if need be. You may pass an empty string for each portion.
300         If all portions are empty, the empty string is returned. If $volume
301         is empty, the result will be a relative path, beginning with a ':'.
302         If $volume and $directory are empty, a leading ":" (if any) is
303         removed form $file and the remainder is returned. If $file is empty,
304         the resulting path will have a trailing ':'.
305
306       abs2rel
307         Takes a destination path and an optional base path and returns a
308         relative path from the base path to the destination path:
309
310             $rel_path = File::Spec->abs2rel( $path ) ;
311             $rel_path = File::Spec->abs2rel( $path, $base ) ;
312
313         Note that both paths are assumed to have a notation that
314         distinguishes a directory path (with trailing ':') from a file path
315         (without trailing ':').
316
317         If $base is not present or '', then the current working directory is
318         used.  If $base is relative, then it is converted to absolute form
319         using "rel2abs()".  This means that it is taken to be relative to the
320         current working directory.
321
322         If $path and $base appear to be on two different volumes, we will not
323         attempt to resolve the two paths, and we will instead simply return
324         $path.  Note that previous versions of this module ignored the volume
325         of $base, which resulted in garbage results part of the time.
326
327         If $base doesn't have a trailing colon, the last element of $base is
328         assumed to be a filename.  This filename is ignored.  Otherwise all
329         path components are assumed to be directories.
330
331         If $path is relative, it is converted to absolute form using
332         "rel2abs()".  This means that it is taken to be relative to the
333         current working directory.
334
335         Based on code written by Shigio Yamaguchi.
336
337       rel2abs
338         Converts a relative path to an absolute path:
339
340             $abs_path = File::Spec->rel2abs( $path ) ;
341             $abs_path = File::Spec->rel2abs( $path, $base ) ;
342
343         Note that both paths are assumed to have a notation that
344         distinguishes a directory path (with trailing ':') from a file path
345         (without trailing ':').
346
347         If $base is not present or '', then $base is set to the current
348         working directory. If $base is relative, then it is converted to
349         absolute form using "rel2abs()". This means that it is taken to be
350         relative to the current working directory.
351
352         If $base doesn't have a trailing colon, the last element of $base is
353         assumed to be a filename.  This filename is ignored.  Otherwise all
354         path components are assumed to be directories.
355
356         If $path is already absolute, it is returned and $base is ignored.
357
358         Based on code written by Shigio Yamaguchi.
359

AUTHORS

361       See the authors list in File::Spec. Mac OS support by Paul Schinder
362       <schinder@pobox.com> and Thomas Wegner <wegner_thomas@yahoo.com>.
363
365       Copyright (c) 2004 by the Perl 5 Porters.  All rights reserved.
366
367       This program is free software; you can redistribute it and/or modify it
368       under the same terms as Perl itself.
369

SEE ALSO

371       See File::Spec and File::Spec::Unix.  This package overrides the
372       implementation of these methods, not the semantics.
373
374
375
376perl v5.34.0                      2021-07-22                File::Spec::Mac(3)
Impressum