1File::Spec::Mac(3) User Contributed Perl Documentation File::Spec::Mac(3)
2
6 File::Spec::Mac - File::Spec for Mac OS (Classic)
7
9 require File::Spec::Mac; # Done internally by File::Spec if needed
10
12 Methods for manipulating file specifications.
13
15 canonpath
16 On Mac OS, there's nothing to be done. Returns what it's given.
17 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 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 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 So, beside calls like
42 catdir("a") = ":a:"
44 catdir("a","b") = ":a:b:"
45 catdir() = "" (special case)
46 calls like the following
48 catdir(":a:") = ":a:"
50 catdir(":a","b") = ":a:b:"
51 catdir(":a:","b") = ":a:b:"
52 catdir(":a:",":b:") = ":a:b:"
53 catdir(":") = ":"
54 are allowed.
56 Here are the rules that are used in "catdir()"; note that we try to
58 be as compatible as possible to Unix:
59 1.
61 The resulting path is relative by default, i.e. the resulting path
62 will have a leading colon.
63 2.
65 A trailing colon is added automatically to the resulting path, to
66 denote a directory.
67 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 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 catdir(":::a","::b","c") = ":::a::b:c:"
81 catdir(":::a::","::b","c") = ":::a:::b:c:"
82 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 catdir("a",":",":","b") = ":a:b:"
93 catdir("a",":","::",":b") = ":a::b:"
94 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 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 catdir("","a","b") is the same as
104 catdir(rootdir(),"a","b").
106 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 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 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 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 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 $dir = File::Spec->catdir("tmp","sources");
150 $abs_path = File::Spec->catpath("MacintoshHD:", $dir,"");
151 yields
153 "MacintoshHD:tmp:sources:" .
155 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 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 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 catfile("") = ""
174 catfile("file") = "file"
175 but
177 catfile("","") = rootdir() # (e.g. "HD:")
179 catfile("","file") = rootdir() . file # (e.g. "HD:file")
180 catfile("HD:","file") = "HD:file"
181 This means that "catdir()" is called only when there are two or more
183 arguments, as one might expect.
184 Note that the leading ":" is removed from the filename, so that
186 catfile("a","b","file") = ":a:b:file" and
188 catfile("a","b",":file") = ":a:b:file"
190 give the same answer.
192 To concatenate volume names, directory paths and filenames, you are
194 encouraged to use "catpath()" (see below).
195 curdir
197 Returns a string representing the current directory. On Mac OS, this
198 is ":".
199 devnull
201 Returns a string representing the null device. On Mac OS, this is
202 "Dev:Null".
203 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 If Mac::Files could not be loaded, the empty string is returned.
212 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 updir
220 Returns a string representing the parent directory. On Mac OS, this
221 is "::".
222 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 E.g.
235 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 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 splitpath
249 ($volume,$directories,$file) = File::Spec->splitpath( $path );
250 ($volume,$directories,$file) = File::Spec->splitpath( $path,
251 $no_file );
252 Splits a path into volume, directory, and filename portions.
254 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 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 The results can be passed to "catpath()" to get back a path
265 equivalent to (usually identical to) the original path.
266 splitdir
268 The opposite of "catdir()".
269 @dirs = File::Spec->splitdir( $directories );
271 $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 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 Hence, on Mac OS, both
284 File::Spec->splitdir( ":a:b::c:" ); and
286 File::Spec->splitdir( ":a:b::c" );
287 yield:
289 ( "a", "b", "::", "c")
291 while
293 File::Spec->splitdir( ":a:b::c::" );
295 yields:
297 ( "a", "b", "::", "c", "::")
299 catpath
301 $path = File::Spec->catpath($volume,$directory,$file);
302 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 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 $rel_path = File::Spec->abs2rel( $path ) ;
317 $rel_path = File::Spec->abs2rel( $path, $base ) ;
318 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 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 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 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 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 Based on code written by Shigio Yamaguchi.
342 rel2abs
344 Converts a relative path to an absolute path:
345 $abs_path = File::Spec->rel2abs( $path ) ;
347 $abs_path = File::Spec->rel2abs( $path, $base ) ;
348 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 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 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 If $path is already absolute, it is returned and $base is ignored.
363 Based on code written by Shigio Yamaguchi.
365
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 This program is free software; you can redistribute it and/or modify it
374 under the same terms as Perl itself.
375
377 See File::Spec and File::Spec::Unix. This package overrides the
378 implementation of these methods, not the semantics.
379perl v5.16.3 2013-01-16 File::Spec::Mac(3)