1File::Spec::Mac(3pm)   Perl Programmers Reference Guide   File::Spec::Mac(3pm)
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 beyond root
122               Unix->catdir("",".","..","..","a")  =  "/a"
123            Mac:
124               Mac->catdir("","")                  =  rootdir()         # (e.g. "HD:")
125               Mac->catdir("",":")                 =  rootdir()
126               Mac->catdir("","::")                =  rootdir()         # can't go beyond root
127               Mac->catdir("",":","::","::","a")   =  rootdir() . "a:"  # (e.g. "HD:a:")
128
129           However, this approach is limited to the first arguments following
130           "root" (again, see "Unix->canonpath()" ). If there are more
131           arguments that move up the directory tree, an invalid path going
132           beyond root can be created.
133
134         As you've seen, you can force "catdir()" to create an absolute path
135         by passing either an empty string or a path that begins with a volume
136         name as the first argument. However, you are strongly encouraged not
137         to do so, since this is done only for backward compatibility. Newer
138         versions of File::Spec come with a method called "catpath()" (see
139         below), that is designed to offer a portable solution for the
140         creation of absolute paths.  It takes volume, directory and file
141         portions and returns an entire path. While "catdir()" is still
142         suitable for the concatenation of directory names, you are encouraged
143         to use "catpath()" to concatenate volume names and directory paths.
144         E.g.
145
146             $dir      = File::Spec->catdir("tmp","sources");
147             $abs_path = File::Spec->catpath("MacintoshHD:", $dir,"");
148
149         yields
150
151             "MacintoshHD:tmp:sources:" .
152
153       catfile
154         Concatenate one or more directory names and a filename to form a
155         complete path ending with a filename. Resulting paths are relative by
156         default, but can be forced to be absolute (but avoid this).
157
158         IMPORTANT NOTE: Beginning with version 1.3 of this module, the
159         resulting path is relative by default and not absolute. This decision
160         was made due to portability reasons. Since "File::Spec->catfile()"
161         returns relative paths on all other operating systems, it will now
162         also follow this convention on Mac OS.  Note that this may break some
163         existing scripts.
164
165         The last argument is always considered to be the file portion. Since
166         "catfile()" uses "catdir()" (see above) for the concatenation of the
167         directory portions (if any), the following with regard to relative
168         and absolute paths is true:
169
170             catfile("")     = ""
171             catfile("file") = "file"
172
173         but
174
175             catfile("","")        = rootdir()         # (e.g. "HD:")
176             catfile("","file")    = rootdir() . file  # (e.g. "HD:file")
177             catfile("HD:","file") = "HD:file"
178
179         This means that "catdir()" is called only when there are two or more
180         arguments, as one might expect.
181
182         Note that the leading ":" is removed from the filename, so that
183
184             catfile("a","b","file")  = ":a:b:file"    and
185
186             catfile("a","b",":file") = ":a:b:file"
187
188         give the same answer.
189
190         To concatenate volume names, directory paths and filenames, you are
191         encouraged to use "catpath()" (see below).
192
193       curdir
194         Returns a string representing the current directory. On Mac OS, this
195         is ":".
196
197       devnull
198         Returns a string representing the null device. On Mac OS, this is
199         "Dev:Null".
200
201       rootdir
202         Returns a string representing the root directory.  Under MacPerl,
203         returns the name of the startup volume, since that's the closest in
204         concept, although other volumes aren't rooted there. The name has a
205         trailing ":", because that's the correct specification for a volume
206         name on Mac OS.
207
208         If Mac::Files could not be loaded, the empty string is returned.
209
210       tmpdir
211         Returns the contents of $ENV{TMPDIR}, if that directory exits or the
212         current working directory otherwise. Under MacPerl, $ENV{TMPDIR} will
213         contain a path like "MacintoshHD:Temporary Items:", which is a hidden
214         directory on your startup volume.
215
216       updir
217         Returns a string representing the parent directory. On Mac OS, this
218         is "::".
219
220       file_name_is_absolute
221         Takes as argument a path and returns true, if it is an absolute path.
222         If the path has a leading ":", it's a relative path. Otherwise, it's
223         an absolute path, unless the path doesn't contain any colons, i.e.
224         it's a name like "a". In this particular case, the path is considered
225         to be relative (i.e. it is considered to be a filename). Use ":" in
226         the appropriate place in the path if you want to distinguish
227         unambiguously. As a special case, the filename '' is always
228         considered to be absolute. Note that with version 1.2 of
229         File::Spec::Mac, this does no longer consult the local filesystem.
230
231         E.g.
232
233             File::Spec->file_name_is_absolute("a");             # false (relative)
234             File::Spec->file_name_is_absolute(":a:b:");         # false (relative)
235             File::Spec->file_name_is_absolute("MacintoshHD:");  # true (absolute)
236             File::Spec->file_name_is_absolute("");              # true (absolute)
237
238       path
239         Returns the null list for the MacPerl application, since the concept
240         is usually meaningless under Mac OS. But if you're using the MacPerl
241         tool under MPW, it gives back $ENV{Commands} suitably split, as is
242         done in :lib:ExtUtils:MM_Mac.pm.
243
244       splitpath
245             ($volume,$directories,$file) = File::Spec->splitpath( $path );
246             ($volume,$directories,$file) = File::Spec->splitpath( $path, $no_file );
247
248         Splits a path into volume, directory, and filename portions.
249
250         On Mac OS, assumes that the last part of the path is a filename
251         unless $no_file is true or a trailing separator ":" is present.
252
253         The volume portion is always returned with a trailing ":". The
254         directory portion is always returned with a leading (to denote a
255         relative path) and a trailing ":" (to denote a directory). The file
256         portion is always returned without a leading ":".  Empty portions are
257         returned as empty string ''.
258
259         The results can be passed to "catpath()" to get back a path
260         equivalent to (usually identical to) the original path.
261
262       splitdir
263         The opposite of "catdir()".
264
265             @dirs = File::Spec->splitdir( $directories );
266
267         $directories should be only the directory portion of the path on
268         systems that have the concept of a volume or that have path syntax
269         that differentiates files from directories. Consider using
270         "splitpath()" otherwise.
271
272         Unlike just splitting the directories on the separator, empty
273         directory names ("") can be returned. Since "catdir()" on Mac OS
274         always appends a trailing colon to distinguish a directory path from
275         a file path, a single trailing colon will be ignored, i.e. there's no
276         empty directory name after it.
277
278         Hence, on Mac OS, both
279
280             File::Spec->splitdir( ":a:b::c:" );    and
281             File::Spec->splitdir( ":a:b::c" );
282
283         yield:
284
285             ( "a", "b", "::", "c")
286
287         while
288
289             File::Spec->splitdir( ":a:b::c::" );
290
291         yields:
292
293             ( "a", "b", "::", "c", "::")
294
295       catpath
296             $path = File::Spec->catpath($volume,$directory,$file);
297
298         Takes volume, directory and file portions and returns an entire path.
299         On Mac OS, $volume, $directory and $file are concatenated.  A ':' is
300         inserted if need be. You may pass an empty string for each portion.
301         If all portions are empty, the empty string is returned. If $volume
302         is empty, the result will be a relative path, beginning with a ':'.
303         If $volume and $directory are empty, a leading ":" (if any) is
304         removed form $file and the remainder is returned. If $file is empty,
305         the resulting path will have a trailing ':'.
306
307       abs2rel
308         Takes a destination path and an optional base path and returns a
309         relative path from the base path to the destination path:
310
311             $rel_path = File::Spec->abs2rel( $path ) ;
312             $rel_path = File::Spec->abs2rel( $path, $base ) ;
313
314         Note that both paths are assumed to have a notation that
315         distinguishes a directory path (with trailing ':') from a file path
316         (without trailing ':').
317
318         If $base is not present or '', then the current working directory is
319         used.  If $base is relative, then it is converted to absolute form
320         using "rel2abs()".  This means that it is taken to be relative to the
321         current working directory.
322
323         If $path and $base appear to be on two different volumes, we will not
324         attempt to resolve the two paths, and we will instead simply return
325         $path.  Note that previous versions of this module ignored the volume
326         of $base, which resulted in garbage results part of the time.
327
328         If $base doesn't have a trailing colon, the last element of $base is
329         assumed to be a filename.  This filename is ignored.  Otherwise all
330         path components are assumed to be directories.
331
332         If $path is relative, it is converted to absolute form using
333         "rel2abs()".  This means that it is taken to be relative to the
334         current working directory.
335
336         Based on code written by Shigio Yamaguchi.
337
338       rel2abs
339         Converts a relative path to an absolute path:
340
341             $abs_path = File::Spec->rel2abs( $path ) ;
342             $abs_path = File::Spec->rel2abs( $path, $base ) ;
343
344         Note that both paths are assumed to have a notation that
345         distinguishes a directory path (with trailing ':') from a file path
346         (without trailing ':').
347
348         If $base is not present or '', then $base is set to the current
349         working directory. If $base is relative, then it is converted to
350         absolute form using "rel2abs()". This means that it is taken to be
351         relative to the current working directory.
352
353         If $base doesn't have a trailing colon, the last element of $base is
354         assumed to be a filename.  This filename is ignored.  Otherwise all
355         path components are assumed to be directories.
356
357         If $path is already absolute, it is returned and $base is ignored.
358
359         Based on code written by Shigio Yamaguchi.
360

AUTHORS

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

SEE ALSO

372       See File::Spec and File::Spec::Unix.  This package overrides the
373       implementation of these methods, not the semantics.
374
375
376
377perl v5.10.1                      2009-05-10              File::Spec::Mac(3pm)
Impressum