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
89           "Unix->canonpath()" ). 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 "Unix->canonpath()" ). If there are more
134           arguments that move up the directory tree, an invalid path going
135           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 a string representing the root directory.  Under MacPerl,
206         returns the name of the startup volume, since that's the closest in
207         concept, although other volumes aren't rooted there. The name has a
208         trailing ":", because that's the correct specification for a volume
209         name on Mac OS.
210
211         If Mac::Files could not be loaded, the empty string is returned.
212
213       tmpdir
214         Returns the contents of $ENV{TMPDIR}, if that directory exits or the
215         current working directory otherwise. Under MacPerl, $ENV{TMPDIR} will
216         contain a path like "MacintoshHD:Temporary Items:", which is a hidden
217         directory on your startup volume.
218
219       updir
220         Returns a string representing the parent directory. On Mac OS, this
221         is "::".
222
223       file_name_is_absolute
224         Takes as argument a path and returns true, if it is an absolute path.
225         If the path has a leading ":", it's a relative path. Otherwise, it's
226         an absolute path, unless the path doesn't contain any colons, i.e.
227         it's a name like "a". In this particular case, the path is considered
228         to be relative (i.e. it is considered to be a filename). Use ":" in
229         the appropriate place in the path if you want to distinguish
230         unambiguously. As a special case, the filename '' is always
231         considered to be absolute. Note that with version 1.2 of
232         File::Spec::Mac, this does no longer consult the local filesystem.
233
234         E.g.
235
236             File::Spec->file_name_is_absolute("a");         # false (relative)
237             File::Spec->file_name_is_absolute(":a:b:");     # false (relative)
238             File::Spec->file_name_is_absolute("MacintoshHD:");
239                                                             # true (absolute)
240             File::Spec->file_name_is_absolute("");          # true (absolute)
241
242       path
243         Returns the null list for the MacPerl application, since the concept
244         is usually meaningless under Mac OS. But if you're using the MacPerl
245         tool under MPW, it gives back $ENV{Commands} suitably split, as is
246         done in :lib:ExtUtils:MM_Mac.pm.
247
248       splitpath
249             ($volume,$directories,$file) = File::Spec->splitpath( $path );
250             ($volume,$directories,$file) = File::Spec->splitpath( $path,
251                                                                   $no_file );
252
253         Splits a path into volume, directory, and filename portions.
254
255         On Mac OS, assumes that the last part of the path is a filename
256         unless $no_file is true or a trailing separator ":" is present.
257
258         The volume portion is always returned with a trailing ":". The
259         directory portion is always returned with a leading (to denote a
260         relative path) and a trailing ":" (to denote a directory). The file
261         portion is always returned without a leading ":".  Empty portions are
262         returned as empty string ''.
263
264         The results can be passed to "catpath()" to get back a path
265         equivalent to (usually identical to) the original path.
266
267       splitdir
268         The opposite of "catdir()".
269
270             @dirs = File::Spec->splitdir( $directories );
271
272         $directories should be only the directory portion of the path on
273         systems that have the concept of a volume or that have path syntax
274         that differentiates files from directories. Consider using
275         "splitpath()" otherwise.
276
277         Unlike just splitting the directories on the separator, empty
278         directory names ("") can be returned. Since "catdir()" on Mac OS
279         always appends a trailing colon to distinguish a directory path from
280         a file path, a single trailing colon will be ignored, i.e. there's no
281         empty directory name after it.
282
283         Hence, on Mac OS, both
284
285             File::Spec->splitdir( ":a:b::c:" );    and
286             File::Spec->splitdir( ":a:b::c" );
287
288         yield:
289
290             ( "a", "b", "::", "c")
291
292         while
293
294             File::Spec->splitdir( ":a:b::c::" );
295
296         yields:
297
298             ( "a", "b", "::", "c", "::")
299
300       catpath
301             $path = File::Spec->catpath($volume,$directory,$file);
302
303         Takes volume, directory and file portions and returns an entire path.
304         On Mac OS, $volume, $directory and $file are concatenated.  A ':' is
305         inserted if need be. You may pass an empty string for each portion.
306         If all portions are empty, the empty string is returned. If $volume
307         is empty, the result will be a relative path, beginning with a ':'.
308         If $volume and $directory are empty, a leading ":" (if any) is
309         removed form $file and the remainder is returned. If $file is empty,
310         the resulting path will have a trailing ':'.
311
312       abs2rel
313         Takes a destination path and an optional base path and returns a
314         relative path from the base path to the destination path:
315
316             $rel_path = File::Spec->abs2rel( $path ) ;
317             $rel_path = File::Spec->abs2rel( $path, $base ) ;
318
319         Note that both paths are assumed to have a notation that
320         distinguishes a directory path (with trailing ':') from a file path
321         (without trailing ':').
322
323         If $base is not present or '', then the current working directory is
324         used.  If $base is relative, then it is converted to absolute form
325         using "rel2abs()".  This means that it is taken to be relative to the
326         current working directory.
327
328         If $path and $base appear to be on two different volumes, we will not
329         attempt to resolve the two paths, and we will instead simply return
330         $path.  Note that previous versions of this module ignored the volume
331         of $base, which resulted in garbage results part of the time.
332
333         If $base doesn't have a trailing colon, the last element of $base is
334         assumed to be a filename.  This filename is ignored.  Otherwise all
335         path components are assumed to be directories.
336
337         If $path is relative, it is converted to absolute form using
338         "rel2abs()".  This means that it is taken to be relative to the
339         current working directory.
340
341         Based on code written by Shigio Yamaguchi.
342
343       rel2abs
344         Converts a relative path to an absolute path:
345
346             $abs_path = File::Spec->rel2abs( $path ) ;
347             $abs_path = File::Spec->rel2abs( $path, $base ) ;
348
349         Note that both paths are assumed to have a notation that
350         distinguishes a directory path (with trailing ':') from a file path
351         (without trailing ':').
352
353         If $base is not present or '', then $base is set to the current
354         working directory. If $base is relative, then it is converted to
355         absolute form using "rel2abs()". This means that it is taken to be
356         relative to the current working directory.
357
358         If $base doesn't have a trailing colon, the last element of $base is
359         assumed to be a filename.  This filename is ignored.  Otherwise all
360         path components are assumed to be directories.
361
362         If $path is already absolute, it is returned and $base is ignored.
363
364         Based on code written by Shigio Yamaguchi.
365

AUTHORS

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

SEE ALSO

377       See File::Spec and File::Spec::Unix.  This package overrides the
378       implementation of these methods, not the semantics.
379
380
381
382perl v5.16.3                      2013-01-16                File::Spec::Mac(3)
Impressum