.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "elvish-file" "7" "Dec 07, 2021" "Elvish 0.17.0~rc4" "Miscellaneous Information Manual"
.hy
.PP
.SH Introduction
.PP
The \f[C]file:\f[R] module provides utilities for manipulating file
objects.
.PP
Function usages are given in the same format as in the reference doc for
the builtin module.
.SH Functions
.PP
.SS file:close {#file:close}
.IP
.nf
\f[C]
file:close $file
\f[R]
.fi
.PP
Closes a file opened with \f[C]open\f[R].
.PP
See also \f[C]file:open\f[R].
.PP
.SS file:open {#file:open}
.IP
.nf
\f[C]
file:open $filename
\f[R]
.fi
.PP
Opens a file.
Currently, \f[C]open\f[R] only supports opening a file for reading.
File must be closed with \f[C]close\f[R] explicitly.
Example:
.IP
.nf
\f[C]
\[ti]> cat a.txt
This is
a file.
\[ti]> use file
\[ti]> f = (file:open a.txt)
\[ti]> cat < $f
This is
a file.
\[ti]> close $f
\f[R]
.fi
.PP
See also \f[C]file:close\f[R].
.PP
.SS file:pipe {#file:pipe}
.IP
.nf
\f[C]
file:pipe
\f[R]
.fi
.PP
Create a new pipe that can be used in redirections.
A pipe contains a read-end and write-end.
Each pipe object is a pseudo-map with fields \f[C]r\f[R] (the read-end
file object) and \f[C]w\f[R] (the write-end).
.PP
When redirecting command input from a pipe with \f[C]<\f[R], the
read-end is used.
When redirecting command output to a pipe with \f[C]>\f[R], the
write-end is used.
Redirecting both input and output with \f[C]<>\f[R] to a pipe is not
supported.
.PP
Pipes have an OS-dependent buffer, so writing to a pipe without an
active reader does not necessarily block.
Pipes \f[B]must\f[R] be explicitly closed with \f[C]file:close\f[R].
.PP
Putting values into pipes will cause those values to be discarded.
.PP
Examples (assuming the pipe has a large enough buffer):
.IP
.nf
\f[C]
\[ti]> p = (file:pipe)
\[ti]> echo \[aq]lorem ipsum\[aq] > $p
\[ti]> head -n1 < $p
lorem ipsum
\[ti]> put \[aq]lorem ipsum\[aq] > $p
\[ti]> file:close $p[w] # close the write-end
\[ti]> head -n1 < $p # blocks unless the write-end is closed
\[ti]> file:close $p[r] # close the read-end
\f[R]
.fi
.PP
See also \f[C]file:close\f[R].
.PP
.SS file:truncate {#file:truncate}
.IP
.nf
\f[C]
file:truncate $filename $size
\f[R]
.fi
.PP
changes the size of the named file.
If the file is a symbolic link, it changes the size of the link\[cq]s
target.
The size must be an integer between 0 and 2\[ha]64-1.