From: Jarkko Hietaniemi Date: Wed, 17 Oct 2001 02:24:02 +0000 (+0000) Subject: Pod cleanup. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=5813de03908a5c339eb77089b45649e26152a902;p=p5sagit%2Fp5-mst-13.2.git Pod cleanup. p4raw-id: //depot/perl@12469 --- diff --git a/lib/File/Spec.pm b/lib/File/Spec.pm index 0f90a45..f177f68 100644 --- a/lib/File/Spec.pm +++ b/lib/File/Spec.pm @@ -75,14 +75,14 @@ forms of these methods. =over 2 -=item canonpath() +=item canonpath No physical check on the filesystem, but a logical cleanup of a path. $cpath = File::Spec->canonpath( $path ) ; -=item catdir() +=item catdir Concatenate two or more directory names to form a complete path ending with a directory. But remove the trailing slash from the resulting diff --git a/lib/File/Spec/Mac.pm b/lib/File/Spec/Mac.pm index bba21ee..dfce6a3 100644 --- a/lib/File/Spec/Mac.pm +++ b/lib/File/Spec/Mac.pm @@ -75,71 +75,77 @@ calls like the following are allowed. -Here are the rules that are used in C; note that we try to be as -compatible as possible to Unix: +Here are the rules that are used in C; note that we try to be as +compatible as possible to Unix: =over 2 - =item 1. -The resulting path is relative by default, i.e. the resulting path will have a -leading colon. +The resulting path is relative by default, i.e. the resulting path will have a +leading colon. =item 2. -A trailing colon is added automatically to the resulting path, to denote a -directory. +A trailing colon is added automatically to the resulting path, to denote a +directory. =item 3. -Generally, each argument has one leading ":" and one trailing ":" removed (if -any). They are then joined together by a ":". Special treatment applies for -arguments denoting updir paths like "::lib:", see (4), or arguments consisting -solely of colons ("colon paths"), see (5). +Generally, each argument has one leading ":" and one trailing ":" +removed (if any). They are then joined together by a ":". Special +treatment applies for arguments denoting updir paths like "::lib:", +see (4), or arguments consisting solely of colons ("colon paths"), +see (5). =item 4. -When an updir path like ":::lib::" is passed as argument, the number of -directories to climb up is handled correctly, not removing leading or trailing -colons when necessary. E.g. + +When an updir path like ":::lib::" is passed as argument, the number +of directories to climb up is handled correctly, not removing leading +or trailing colons when necessary. E.g. catdir(":::a","::b","c") = ":::a::b:c:" catdir(":::a::","::b","c") = ":::a:::b:c:" =item 5. -Adding a colon ":" or empty string "" to a path at I position doesn't -alter the path, i.e. these arguments are ignored. (When a "" is passed as -the first argument, it has a special meaning, see (6) ). This way, a colon -":" is handled like a "." (curdir) on Unix, while an empty string "" is -generally ignored (see Ccanonpath()> ). Likewise, a "::" is handled -like a ".." (updir), and a ":::" is handled like a "../.." etc. E.g. + +Adding a colon ":" or empty string "" to a path at I position +doesn't alter the path, i.e. these arguments are ignored. (When a "" +is passed as the first argument, it has a special meaning, see +(6)). This way, a colon ":" is handled like a "." (curdir) on Unix, +while an empty string "" is generally ignored (see +Ccanonpath()> ). Likewise, a "::" is handled like a ".." +(updir), and a ":::" is handled like a "../.." etc. E.g. catdir("a",":",":","b") = ":a:b:" catdir("a",":","::",":b") = ":a::b:" - =item 6. -If the first argument is an empty string "" or is a volume name, i.e. matches -the pattern /^[^:]+:/, the resulting path is B. + +If the first argument is an empty string "" or is a volume name, i.e. matches +the pattern /^[^:]+:/, the resulting path is B. =item 7. -Passing an empty string "" as the first argument to C is like passing -Crootdir()> as the first argument, i.e. + +Passing an empty string "" as the first argument to C is +like passingCrootdir()> as the first argument, i.e. catdir("","a","b") is the same as catdir(rootdir(),"a","b"). -This is true on Unix, where C yields "/a/b" and C is -"/". Note that C on Mac OS is the startup volume, which is the closest -in concept to Unix' "/". This should help to run existing scripts originally written -for Unix. +This is true on Unix, where C yields "/a/b" and +C is "/". Note that C on Mac OS is the startup +volume, which is the closest in concept to Unix' "/". This should help +to run existing scripts originally written for Unix. =item 8. -For absolute paths, some cleanup is done, to ensure that the volume name isn't -immediately followed by updirs. This is invalid, because this would go beyond -"root". Generally, these cases are handled like their Unix counterparts: + +For absolute paths, some cleanup is done, to ensure that the volume +name isn't immediately followed by updirs. This is invalid, because +this would go beyond "root". Generally, these cases are handled like +their Unix counterparts: Unix: Unix->catdir("","") = "/" @@ -152,20 +158,24 @@ immediately followed by updirs. This is invalid, because this would go beyond Mac->catdir("","::") = rootdir() # can't go beyond root Mac->catdir("",":","::","::","a") = rootdir() . "a:" # (e.g. "HD:a:") -However, this approach is limited to the first arguments following "root" (again, see -Ccanonpath()> ). If there are more arguments that move up the directory -tree, an invalid path going beyond root can be created. +However, this approach is limited to the first arguments following +"root" (again, see Ccanonpath()> ). If there are more +arguments that move up the directory tree, an invalid path going +beyond root can be created. =back -As you've seen, you can force C to create an absolute path by passing either -an empty string or a path that begins with a volume name as the first argument. However, -you are strongly encouraged not to do so, since this is done only for backward -compatibility. Newer versions of File::Spec come with a method called C (see -below), that is designed to offer a portable solution for the creation of absolute paths. -It takes volume, directory and file portions and returns an entire path. While -C is still suitable for the concatenation of I, you are -encouraged to use C to concatenate I and I. E.g. +As you've seen, you can force C to create an absolute path +by passing either an empty string or a path that begins with a volume +name as the first argument. However, you are strongly encouraged not +to do so, since this is done only for backward compatibility. Newer +versions of File::Spec come with a method called C (see +below), that is designed to offer a portable solution for the creation +of absolute paths. It takes volume, directory and file portions and +returns an entire path. While C is still suitable for the +concatenation of I, you are encouraged to use +C to concatenate I and I. E.g. $dir = File::Spec->catdir("tmp","sources"); $abs_path = File::Spec->catpath("MacintoshHD:", $dir,"");