.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "elvish-path" "7" "Dec 07, 2021" "Elvish 0.17.0~rc4" "Miscellaneous Information Manual"
.hy
.PP
.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
.PP
.SS path:abs {#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
.PP
.SS path:base {#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
.PP
.SS path:clean {#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
.PP
.SS path:dir {#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
.PP
.SS path:eval-symlinks {#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 outputting
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.
.PP
.SS path:ext {#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
.PP
.SS path:is-abs {#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 absolute 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
.PP
.SS path:is-dir {#path:is-dir}
.IP
.nf
\f[C]
is-dir &follow-symlink=$false $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.
Setting option \f[C]&follow-symlink\f[R] to true will cause the last
element of the path, if it is a symlink, to be resolved before doing the
test.
.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
.PP
See also \f[C]path:is-regular\f[R].
.PP
.SS path:is-regular {#path:is-regular}
.IP
.nf
\f[C]
is-regular &follow-symlink=$false $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.
Setting option \f[C]&follow-symlink\f[R] to true will cause the last
element of the path, if it is a symlink, to be resolved before doing the
test.
.PP
\f[B]Note:\f[R] This isn\[cq]t named \f[C]is-file\f[R] because a UNIX
file may be a \[lq]bag of bytes\[rq] or may be a named pipe, device
special file (e.g.
\f[C]/dev/tty\f[R]), etc.
.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
.PP
See also \f[C]path:is-dir\f[R].
.PP
.SS path:temp-dir {#path:temp-dir}
.IP
.nf
\f[C]
temp-dir &dir=\[aq]\[aq] $pattern?
\f[R]
.fi
.PP
Creates a new directory and outputs its name.
.PP
The &dir option determines where the directory will be created; if it is
an empty string (the default), a system-dependent directory suitable for
storing temporary files will be used.
The \f[C]$pattern\f[R] argument determines the name of the directory,
where the last star will be replaced by a random string; it defaults to
\f[C]elvish-*\f[R].
.PP
It is the caller\[cq]s responsibility to remove the directory if it is
intended to be temporary.
.IP
.nf
\f[C]
\[ti]> path:temp-dir
\[u25B6] /tmp/elvish-RANDOMSTR
\[ti]> path:temp-dir x-
\[u25B6] /tmp/x-RANDOMSTR
\[ti]> path:temp-dir \[aq]x-*.y\[aq]
\[u25B6] /tmp/x-RANDOMSTR.y
\[ti]> path:temp-dir &dir=.
\[u25B6] elvish-RANDOMSTR
\[ti]> path:temp-dir &dir=/some/dir
\[u25B6] /some/dir/elvish-RANDOMSTR
\f[R]
.fi
.PP
.SS path:temp-file {#path:temp-file}
.IP
.nf
\f[C]
temp-file &dir=\[aq]\[aq] $pattern?
\f[R]
.fi
.PP
Creates a new file and outputs a file object opened for reading and
writing.
.PP
The &dir option determines where the file will be created; if it is an
empty string (the default), a system-dependent directory suitable for
storing temporary files will be used.
The \f[C]$pattern\f[R] argument determines the name of the file, where
the last star will be replaced by a random string; it defaults to
\f[C]elvish-*\f[R].
.PP
It is the caller\[cq]s responsibility to close the file with
\f[C]file:close\f[R].
The caller should also remove the file if it is intended to be temporary
(with \f[C]rm $f[name]\f[R]).
.IP
.nf
\f[C]
\[ti]> f = path:temp-file
\[ti]> put $f[name]
\[u25B6] /tmp/elvish-RANDOMSTR
\[ti]> echo hello > $f
\[ti]> cat $f[name]
hello
\[ti]> f = path:temp-file x-
\[ti]> put $f[name]
\[u25B6] /tmp/x-RANDOMSTR
\[ti]> f = path:temp-file \[aq]x-*.y\[aq]
\[ti]> put $f[name]
\[u25B6] /tmp/x-RANDOMSTR.y
\[ti]> f = path:temp-file &dir=.
\[ti]> put $f[name]
\[u25B6] elvish-RANDOMSTR
\[ti]> f = path:temp-file &dir=/some/dir
\[ti]> put $f[name]
\[u25B6] /some/dir/elvish-RANDOMSTR
\f[R]
.fi