elvish-file(7)

💖 elvish-file — the file: module, but make it make sense 💖

elvish-file(7) · Miscellaneous Information Manual · bestie edition 🎀

---

🌸 Introduction 🌸

Okay so the file: module? It's the whole toolbox for manipulating file objects. That's it, that's the vibe. 🫶

And fr fr, function usages in here are written in the exact same format as the reference doc for the builtin module — so if you already know that format, you're already slaying. No cap. ✨

---

🔥 Functions 🔥

✨ file:close {#file:close} ✨

file:close $file

Closes a file that was opened with open. Simple. Clean. Closure. 💅

See also file:open.

---

🦋 file:open {#file:open} 🦋

file:open $filename

Opens a file, bestie. But heads up: currently open only supports opening a file for reading — that's the whole menu right now, no writing, no appending, nothing extra. 👑

And not me reminding you that the file must be closed with close explicitly — it will not do it for you, no auto-cleanup, no vibes-based garbage collection. 🙈

Example, because seeing it is believing:

~> cat a.txt
This is
a file.
~> use file
~> f = (file:open a.txt)
~> cat < $f
This is
a file.
~> close $f

See also file:close.

---

🧚 file:pipe {#file:pipe} 🧚

file:pipe

Creates a brand new pipe that you can use in redirections. A pipe's got two ends, iconic duo behavior: a read-end and a write-end. And every pipe object is a pseudo-map with these fields:

• r — the read-end file object 📖
• w — the write-end ✍️

So when you redirect command input from a pipe with <, it's the read-end that gets used. When you redirect command output to a pipe with >, it's the write-end that gets used. And redirecting both input and output with <> to a pipe? Not supported. Don't try it, it's giving broken. 💀

Pipes have an OS-dependent buffer, so writing to a pipe without an active reader does not necessarily block — it might just vibe on through. And pipes must be explicitly closed with file:close. Periodt.

Also, putting values into pipes will cause those values to be discarded. Gone. Poof. They do not pass go. 😭

Examples (assuming the pipe has a large enough buffer):

~> p = (file:pipe)
~> echo 'lorem ipsum' > $p
~> head -n1 < $p
lorem ipsum
~> put 'lorem ipsum' > $p
~> file:close $p[w] # close the write-end
~> head -n1 < $p # blocks unless the write-end is closed
~> file:close $p[r] # close the read-end

See also file:close.

---

⭐ file:truncate {#file:truncate} ⭐

file:truncate $filename $size

Changes the size of the named file. And if that file is a symbolic link? Then it changes the size of the link's target, not the link itself — iykyk. 🌈

The size has to be an integer between 0 and 2^64-1. That's the range. Respect it. 💜

---

And that's the whole page, bestie!! This was Elvish 0.17.0, dated Nov 18, 2024 — go forth and manipulate those file objects responsibly, mwah 💅✨🫶