.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "elvish-path" "7" "Jul 18, 2021" "Elvish 0.15.0" "Miscellaneous Information Manual"
.hy
.SH Introduction
.PP
The \f[C]path:\f[R] module provides functions for manipulating and
testing filesystem paths.
.PP
Function usages are given in the same format as in the reference doc for
the builtin module.
.SH Functions
.SS path:abs
.IP
.nf
\f[C]
path:abs $path
\f[R]
.fi
.PP
Outputs \f[C]$path\f[R] converted to an absolute path.
.IP
.nf
\f[C]
\[ti]> cd \[ti]
\[ti]> path:abs bin
\[u25B6] /home/user/bin
\f[R]
.fi
.SS path:base
.IP
.nf
\f[C]
path:base $path
\f[R]
.fi
.PP
Outputs the last element of \f[C]$path\f[R].
This is analogous to the POSIX \f[C]basename\f[R] command.
See the Go documentation (https://pkg.go.dev/path/filepath#Base) for
more details.
.IP
.nf
\f[C]
\[ti]> path:base \[ti]/bin
\[u25B6] bin
\f[R]
.fi
.SS path:clean
.IP
.nf
\f[C]
path:clean $path
\f[R]
.fi
.PP
Outputs the shortest version of \f[C]$path\f[R] equivalent to
\f[C]$path\f[R] by purely lexical processing.
This is most useful for eliminating unnecessary relative path elements
such as \f[C].\f[R] and \f[C]..\f[R] without asking the OS to evaluate
the path name.
See the Go documentation (https://pkg.go.dev/path/filepath#Clean) for
more details.
.IP
.nf
\f[C]
\[ti]> path:clean ./../bin
\[u25B6] ../bin
\f[R]
.fi
.SS path:dir
.IP
.nf
\f[C]
path:dir $path
\f[R]
.fi
.PP
Outputs all but the last element of \f[C]$path\f[R], typically the
path\[cq]s enclosing directory.
See the Go documentation (https://pkg.go.dev/path/filepath#Dir) for more
details.
This is analogous to the POSIX \f[C]dirname\f[R] command.
.IP
.nf
\f[C]
\[ti]> path:dir /a/b/c/something
\[u25B6] /a/b/c
\f[R]
.fi
.SS path:eval-symlinks
.IP
.nf
\f[C]
\[ti]> mkdir bin
\[ti]> ln -s bin sbin
\[ti]> path:eval-symlinks ./sbin/a_command
\[u25B6] bin/a_command
\f[R]
.fi
.PP
Outputs \f[C]$path\f[R] after resolving any symbolic links.
If \f[C]$path\f[R] is relative the result will be relative to the
current directory, unless one of the components is an absolute symbolic
link.
This function calls \f[C]path:clean\f[R] on the result before outputing
it.
This is analogous to the external \f[C]realpath\f[R] or
\f[C]readlink\f[R] command found on many systems.
See the Go documentation (https://pkg.go.dev/path/filepath#EvalSymlinks)
for more details.
.SS path:ext
.IP
.nf
\f[C]
ext $path
\f[R]
.fi
.PP
Outputs the file name extension used by \f[C]$path\f[R] (including the
separating period).
If there is no extension the empty string is output.
See the Go documentation (https://pkg.go.dev/path/filepath#Ext) for more
details.
.IP
.nf
\f[C]
\[ti]> path:ext hello.elv
\[u25B6] .elv
\f[R]
.fi
.SS path:is-abs
.IP
.nf
\f[C]
is-abs $path
\f[R]
.fi
.PP
Outputs \f[C]$true\f[R] if the path is an abolute path.
Note that platforms like Windows have different rules than UNIX like
platforms for what constitutes an absolute path.
See the Go documentation (https://pkg.go.dev/path/filepath#IsAbs) for
more details.
.IP
.nf
\f[C]
\[ti]> path:is-abs hello.elv
\[u25B6] false
\[ti]> path:is-abs /hello.elv
\[u25B6] true
\f[R]
.fi
.SS path:is-dir
.IP
.nf
\f[C]
is-dir $path
\f[R]
.fi
.PP
Outputs \f[C]$true\f[R] if the path resolves to a directory.
If the final element of the path is a symlink, even if it points to a
directory, it still outputs \f[C]$false\f[R] since a symlink is not a
directory.
Use \f[C]eval-symlinks\f[R] on the path first if you don\[cq]t care if
the final element is a symlink.
.IP
.nf
\f[C]
\[ti]> touch not-a-dir
\[ti]> path:is-dir not-a-dir
\[u25B6] false
\[ti]> path:is-dir /tmp
\[u25B6] true
\f[R]
.fi
.SS path:is-regular
.IP
.nf
\f[C]
is-regular $path
\f[R]
.fi
.PP
Outputs \f[C]$true\f[R] if the path resolves to a regular file.
If the final element of the path is a symlink, even if it points to a
regular file, it still outputs \f[C]$false\f[R] since a symlink is not a
regular file.
Use \f[C]eval-symlinks\f[R] on the path first if you don\[cq]t care if
the final element is a symlink.
.IP
.nf
\f[C]
\[ti]> touch not-a-dir
\[ti]> path:is-regular not-a-dir
\[u25B6] true
\[ti]> path:is-dir /tmp
\[u25B6] false
\f[R]
.fi