.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "PathConvert 3pm" .TH PathConvert 3pm "2018-11-02" "perl v5.28.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" abs2rel \- convert an absolute path to a relative path .PP rel2abs \- convert a relative path to an absolute path .PP realpath \- convert a logical path to a physical path (resolve symlinks) .PP splitpath \- split a path in to volume, directory and filename components .PP joinpath \- join volume, directory, and filename components to form a path .PP splitdirs \- split directory specification in to component names .PP joindirs \- join component names in to a directory specification .PP setfstype \- set the file system type .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use File::PathConvert qw(realpath abs2rel rel2abs setfstype splitpath \& joinpath splitdirs joindirs $resolved); \& \& $relpath = abs2rel($abspath); \& $abspath = abs2rel($abspath, $base); \& \& $abspath = rel2abs($relpath); \& $abspath = rel2abs($relpath, $base); \& \& $path = realpath($logpath) || die "resolution stopped at $resolved"; \& \& ( $volume, $directory, $filename )= splitpath( $path ) ; \& ( $volume, $directory, $filename )= splitpath( $path, \*(Aqnofile\*(Aq ) ; \& \& $path= joinpath( $volume, $directory, $filename ) ; \& \& @directories= splitdirs( $directory ) ; \& $directory= joindirs( @directories ) ; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" File::PathConvert provides functions to convert between absolute and relative paths, and from logical paths to physical paths on a variety of filesystems, including the \s-1URL\s0 'filesystem'. .PP Paths are decomposed internally in to volume, directory, and, sometimes filename portions as appropriate to the operation and filesystem, then recombined. This preserves the volume and filename portions so that they may be returned, and prevents them from interfering with the path conversions. .PP Here are some examples of path decomposition. A '****' in a column indicates the column is not used in \f(CW\*(C`abs2rel\*(C'\fR and \f(CW\*(C`rel2abs\*(C'\fR functions for that filesystem type. .PP .Vb 5 \& FS VOLUME Directory filename \& ======= ======================= =============== ============= \& URL http: /a/b/ c?query \& http://fubar.com /a/b/ c?query \& //p.d.q.com /a/b/c/ ?query \& \& VMS Server::Volume: [a.b] c \& Server"access spec":: [a.b] c \& Volume: [a.b] c \& \& Win32 A: \ea\eb\ec **** \& \e\eserver\eVolume \ea\eb\ec **** \& \e\eserver\eVolume \ea/b/c **** \& \& Unix **** \ea\eb\ec **** \& \& MacOS Volume:: a:b:c **** .Ve .PP Many more examples abound in the test.pl included with this module. .PP Only the \s-1VMS\s0 and \s-1URL\s0 filesystems indicate if the last name in a path is a directory or file. For other filesystems, all non-volume names are assumed to be directory names. For URLs, the last name in a path is assumed to be a filename unless it ends in '/', '/.', or '/..'. .PP Other assumptions are made as well, especially MacOS and \s-1VMS. THESE MAY CHANGE BASED ON PROGRAMMER FEEDBACK\s0! .PP The conversion routines \f(CW\*(C`abs2rel\*(C'\fR, \f(CW\*(C`rel2abs\*(C'\fR, and \f(CW\*(C`realpath\*(C'\fR are the main focus of this package. \f(CW\*(C`splitpath\*(C'\fR and \f(CW\*(C`joinpath\*(C'\fR are provided to allow volume oriented filesystems (almost anything non-unixian, actually) to be accomodated. \f(CW\*(C`splitdirs\*(C'\fR and \f(CW\*(C`joindirs\*(C'\fR provide directory path grammar parsing and encoding, which is especially useful for \s-1VMS.\s0 .IP "setfstype" 4 .IX Item "setfstype" This is called automatically on module load to set the filesystem type according to $^O. The user can call this later set the filesystem type manually. If the name is not recognized, unix defaults are used. Names matching /^URL$/i, /^VMS$/i, /^MacOS$/i, or /^(ms)?(win|dos)/32|nt)?$/i yield the appropriate (hopefully) filesystem settings. These strings may be generalized in the future. .Sp Examples: .Sp .Vb 3 \& File::PathConvert::setfstype( \*(Aqurl\*(Aq ) ; \& File::PathConvert::setfstype( \*(AqWin32\*(Aq ) ; \& File::PathConvert::setfstype( \*(AqHAL9000\*(Aq ) ; # Results in Unix default .Ve .IP "abs2rel" 4 .IX Item "abs2rel" \&\f(CW\*(C`abs2rel\*(C'\fR converts an absolute path name to a relative path: converting /1/2/3/a/b/c relative to /1/2/3 returns a/b/c .Sp .Vb 2 \& $relpath= abs2rel( $abspath ) ; \& $relpath= abs2rel( $abspath, $base ) ; .Ve .Sp If \f(CW$abspath\fR is already relative, it is returned unchanged. Otherwise the relative path from \f(CW$base\fR to \f(CW$abspath\fR is returned. If \f(CW$base\fR is undefined the current directory is used. .Sp The volume and filename portions of \f(CW$base\fR are ignored if present. If \f(CW$abspath\fR and \f(CW$base\fR are on different volumes, the volume from \f(CW$abspath\fR is used. .Sp No filesystem calls are made except for getting the current working directory if \f(CW$base\fR is undefined, so symbolic links are not checked for or resolved, and no check is done for existence. .Sp Examples .Sp .Vb 3 \& # Unix \& \*(Aqa/b/c\*(Aq == abs2rel( \*(Aqa/b/c\*(Aq, $anything ) \& \*(Aqa/b/c\*(Aq == abs2rel( \*(Aq/1/2/3/a/b/c\*(Aq, \*(Aq/1/2/3\*(Aq ) \& \& # DOS \& \*(Aqa\e\eb/c\*(Aq == abs2rel( \*(Aqa\e\eb/c\*(Aq, $anything ) \& \*(Aqa\e\eb/c\*(Aq == abs2rel( \*(Aq/1\e\e2/3/a\e\eb/c\*(Aq, \*(Aq/1/2/3\*(Aq ) \& \& # URL \& \*(Aqhttp:a/b/c\*(Aq == abs2rel( \*(Aqhttp:a/b/c\*(Aq, $anything ) \& \*(Aqhttp:a/b/c\*(Aq == abs2rel( \*(Aqhttp:/1/2/3/a/b/c\*(Aq, \& \*(Aqftp://t.org/1/2/3/?z\*(Aq ) \& \*(Aqhttp:a/b/c?q\*(Aq == abs2rel( \*(Aqhttp:/1/2/3/a/b/c/?q\*(Aq, \& \*(Aqftp://t.org/1/2/3?z\*(Aq ) \& \*(Aqhttp://s.com/a/b/c?q\*(Aq == abs2rel( \*(Aqhttp://s.com/1/2/3/a/b/c?q\*(Aq, \& \*(Aqftp://t.org/1/2/3/?z\*(Aq) .Ve .IP "rel2abs" 4 .IX Item "rel2abs" \&\f(CW\*(C`rel2abs\*(C'\fR makes converts a relative path name to an absolute path: converting a/b/c relative to /1/2/3 returns /1/2/3/a/b/c. .Sp .Vb 2 \& $abspath= rel2abs( $relpath ) ; \& $abspath= rel2abs( $relpath, $base ) ; .Ve .Sp If \f(CW$relpath\fR is already absolute, it is returned unchanged. Otherwise \f(CW$relpath\fR is taken to be relative to \f(CW$base\fR and the resulting absolute path is returned. If \f(CW$base\fR is not supplied, the current working directory is used. .Sp The volume portion of \f(CW$relpath\fR is ignored. The filename portion of \f(CW$base\fR is also ignored. The volume from \f(CW$base\fR is returned if present. The filename portion of \f(CW$abspath\fR is returned if present. .Sp No filesystem calls are made except for getting the current working directory if \f(CW$base\fR is undefined, so symbolic links are not checked for or resolved, and no check is done for existence. .Sp \&\f(CW\*(C`rel2abs\*(C'\fR will not return a path of the form \*(L"./file\*(R". .Sp Examples .Sp .Vb 3 \& # Unix \& \*(Aq/a/b/c\*(Aq == rel2abs( \*(Aq/a/b/c\*(Aq, $anything ) \& \*(Aq/1/2/3/a/b/c\*(Aq == rel2abs( \*(Aqa/b/c\*(Aq, \*(Aq/1/2/3\*(Aq ) \& \& # DOS \& \*(Aq\e\ea\e\eb/c\*(Aq == rel2abs( \*(Aq\e\ea\e\eb/c\*(Aq, $anything ) \& \*(Aq/1\e\e2/3\e\ea\e\eb/c\*(Aq == rel2abs( \*(Aqa\e\eb/c\*(Aq, \*(Aq/1\e\e2/3\*(Aq ) \& \*(AqC:/1\e\e2/3\e\ea\e\eb/c\*(Aq == rel2abs( \*(AqD:a\e\eb/c\*(Aq, \*(AqC:/1\e\e2/3\*(Aq ) \& \*(Aq\e\e\e\es\e\ev/1\e\e2/3\e\ea\e\eb/c\*(Aq == rel2abs( \*(AqD:a\e\eb/c\*(Aq, \*(Aq\e\e\e\es\e\ev/1\e\e2/3\*(Aq ) \& \& # URL \& \*(Aqhttp:/a/b/c?q\*(Aq == rel2abs( \*(Aqhttp:/a/b/c?q\*(Aq, $anything ) \& \*(Aqftp://t.org/1/2/3/a/b/c?q\*(Aq== rel2abs( \*(Aqhttp:a/b/c?q\*(Aq, \& \*(Aqftp://t.org/1/2/3?z\*(Aq ) .Ve .IP "realpath" 4 .IX Item "realpath" \&\f(CW\*(C`realpath\*(C'\fR makes a canonicalized absolute pathname and resolves all symbolic links, extra ``/'' characters, and references to /./ and /../ in the path. \&\f(CW\*(C`realpath\*(C'\fR resolves both absolute and relative paths. It returns the resolved name on success, otherwise it returns undef and sets the valiable \f(CW$File::PathConvert::resolved\fR to the pathname that caused the problem. .Sp All but the last component of the path must exist. .Sp This implementation is based on 4.4BSD \fBrealpath\fR\|(3). It is not tested under other operating systems at this time. .Sp If '/sys' is a symbolic link to '/usr/src/sys': .Sp .Vb 3 \& chdir(\*(Aq/usr\*(Aq); \& \*(Aq/usr/src/sys/kern\*(Aq == realpath(\*(Aq../sys/kern\*(Aq); \& \*(Aq/usr/src/sys/kern\*(Aq == realpath(\*(Aq/sys/kern\*(Aq); .Ve .IP "splitpath" 4 .IX Item "splitpath" To be written... .IP "joinpath" 4 .IX Item "joinpath" To be written... .Sp Note that \f(CW\*(C`joinpath( splitpath( $path ) )\*(C'\fR usually yields path. URLs with directory components ending in '/.' or '/..' will be fixed up to end in '/./' and '/../'. .IP "splitdirs" 4 .IX Item "splitdirs" To be written... .IP "joindirs" 4 .IX Item "joindirs" .SH "BUGS" .IX Header "BUGS" \&\f(CW\*(C`realpath\*(C'\fR is not fully multiplatform. .SH "LIMITATIONS" .IX Header "LIMITATIONS" .IP "\(bu" 4 In URLs, paths not ending in '/' are split such that the last name in the path is a filename. This is not intuitive: many people use such URLs for directories, and most servers send a redirect. This may cause programmers using this package to code in bugs, it may be more pragmatic to always assume all names are directory names. (Note that the query portion is always part of the filename). .IP "\(bu" 4 If the relative and base paths are on different volumes, no error is returned. A silent, hopefully reasonable assumption is made. .IP "\(bu" 4 No detection of unix style paths is done when other filesystems are selected, like File::Basename does. .SH "AUTHORS" .IX Header "AUTHORS" Barrie Slaymaker Shigio Yamaguchi