elvish-path(7)

📦
version 0.17.0 · 2 versions
, in ubuntu jammy

💖 elvish-path(7) 💖

okay bestie, gather round, because this is the path: module and it is literally the main character of filesystem manipulation in Elvish ✨ It's from the Miscellaneous Information Manual, and it's here to give you functions for manipulating and testing filesystem paths. no cap.

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

🌸 Functions 🌸

🎀 path:abs {#path:abs}

path:abs $path

Outputs $path converted to an absolute path. it's giving "where am i actually" energy 💅

~> 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. it just wants the final crumb of the path, periodt 🍓

~> 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. lowkey it's just tidying up your mess without asking the filesystem anything 🙈

~> 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. it's the "who's your parent" of functions 🧚

~> path:dir /a/b/c/something
▶ /a/b/c
~> 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. it follows the plot twists (symlinks) all the way through 🔥

🎀 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. yes the dot is included, we don't gatekeep ✨

~> 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. vibe check: does it start at the root or not 👑

~> 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. a symlink is a symlink bestie, it doesn't get to pretend 💀

~> 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. iconic naming lore fr fr 🫶
~> 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. brand new directory just dropped 🎀

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. nobody's gonna clean up after you, bestie 😭
~> 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. a whole file, opened for both reading and writing, no big deal 💅

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]). two chores for the price of one, slay 🧹
~> 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

and that's the whole page bestie 🌈 go forth and manipulate some paths, you absolute icon 👑

Elvish 0.17.0 ✨ Nov 18, 2024 — that's the version and the date, mwah, take care of her 💖🦋🌸

📦 where this page comes from