Introduction

       The path: module provides functions for manipulating and testing filesystem paths.

       Function  usages  are  given  in  the  same format as in the reference doc for the builtin
       module.

Functions

   path:abs {#path:abs}
              path:abs $path

       Outputs $path converted to an absolute path.

              ~> cd ~
              ~> path:abs bin
              ▶ /home/user/bin

   path:base {#path:base}
              path:base $path

       Outputs the last element of $path.  This is analogous to the POSIX basename command.   See
       the Go documentation (https://pkg.go.dev/path/filepath#Base) for more details.

              ~> path:base ~/bin
              ▶ bin

   path:clean {#path:clean}
              path:clean $path

       Outputs  the  shortest  version of $path equivalent to $path by purely lexical processing.
       This is most useful for eliminating unnecessary relative path elements such as  .  and  ..
       without   asking   the   OS   to  evaluate  the  path  name.   See  the  Go  documentation
       (https://pkg.go.dev/path/filepath#Clean) for more details.

              ~> path:clean ./../bin
              ▶ ../bin

   path:dir {#path:dir}
              path:dir $path

       Outputs all but the last element of $path, typically the path’s enclosing directory.   See
       the  Go  documentation  (https://pkg.go.dev/path/filepath#Dir)  for more details.  This is
       analogous to the POSIX dirname command.

              ~> path:dir /a/b/c/something
              ▶ /a/b/c

   path:eval-symlinks {#path:eval-symlinks}
              ~> mkdir bin
              ~> ln -s bin sbin
              ~> path:eval-symlinks ./sbin/a_command
              ▶ bin/a_command

       Outputs $path after resolving any symbolic links.  If $path is relative the result will be
       relative  to  the  current directory, unless one of the components is an absolute symbolic
       link.  This function calls path:clean  on  the  result  before  outputting  it.   This  is
       analogous  to the external realpath or readlink command found on many systems.  See the Go
       documentation (https://pkg.go.dev/path/filepath#EvalSymlinks) for more details.

   path:ext {#path:ext}
              ext $path

       Outputs the file name extension used by $path (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.

              ~> path:ext hello.elv
              ▶ .elv

   path:is-abs {#path:is-abs}
              is-abs $path

       Outputs $true 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.

              ~> path:is-abs hello.elv
              ▶ false
              ~> path:is-abs /hello.elv
              ▶ true

   path:is-dir {#path:is-dir}
              is-dir &follow-symlink=$false $path

       Outputs $true 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 $false since a symlink is not
       a directory.  Setting option &follow-symlink to true will cause the last  element  of  the
       path, if it is a symlink, to be resolved before doing the test.

              ~> touch not-a-dir
              ~> path:is-dir not-a-dir
              ▶ false
              ~> path:is-dir /tmp
              ▶ true

       See also path:is-regular.

   path:is-regular {#path:is-regular}
              is-regular &follow-symlink=$false $path

       Outputs $true 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 $false since a symlink is
       not a regular file.  Setting option &follow-symlink to true will cause the last element of
       the path, if it is a symlink, to be resolved before doing the test.

       Note: This isn’t named is-file because a UNIX file may be a “bag of bytes”  or  may  be  a
       named pipe, device special file (e.g.  /dev/tty), etc.

              ~> touch not-a-dir
              ~> path:is-regular not-a-dir
              ▶ true
              ~> path:is-dir /tmp
              ▶ false

       See also path:is-dir.

   path:temp-dir {#path:temp-dir}
              temp-dir &dir='' $pattern?

       Creates a new directory and outputs its name.

       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  $pattern  argument  determines the name of the directory, where the last star
       will be replaced by a random string; it defaults to elvish-*.

       It is the caller’s responsibility to  remove  the  directory  if  it  is  intended  to  be
       temporary.

              ~> path:temp-dir
              ▶ /tmp/elvish-RANDOMSTR
              ~> path:temp-dir x-
              ▶ /tmp/x-RANDOMSTR
              ~> path:temp-dir 'x-*.y'
              ▶ /tmp/x-RANDOMSTR.y
              ~> path:temp-dir &dir=.
              ▶ elvish-RANDOMSTR
              ~> path:temp-dir &dir=/some/dir
              ▶ /some/dir/elvish-RANDOMSTR

   path:temp-file {#path:temp-file}
              temp-file &dir='' $pattern?

       Creates a new file and outputs a file object opened for reading and writing.

       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  $pattern  argument  determines  the  name  of  the  file, where the last star will be
       replaced by a random string; it defaults to elvish-*.

       It is the caller’s responsibility to close the file with file:close.   The  caller  should
       also remove the file if it is intended to be temporary (with rm $f[name]).

              ~> f = path:temp-file
              ~> put $f[name]
              ▶ /tmp/elvish-RANDOMSTR
              ~> echo hello > $f
              ~> cat $f[name]
              hello
              ~> f = path:temp-file x-
              ~> put $f[name]
              ▶ /tmp/x-RANDOMSTR
              ~> f = path:temp-file 'x-*.y'
              ~> put $f[name]
              ▶ /tmp/x-RANDOMSTR.y
              ~> f = path:temp-file &dir=.
              ~> put $f[name]
              ▶ elvish-RANDOMSTR
              ~> f = path:temp-file &dir=/some/dir
              ~> put $f[name]
              ▶ /some/dir/elvish-RANDOMSTR