file: File Utilities

Table of Content:


The file: module provides utilities for manipulating file objects.

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



file:close $file

Closes a file opened with open.

See also file:open.


file:open $filename

Opens a file. Currently, open only supports opening a file for reading. File must be closed with close explicitly. Example:

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

See also file:close.



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 r (the read-end file object) and w (the write-end).

When redirecting command input from a pipe with <, the read-end is used. When redirecting command output to a pipe with >, the write-end is used. Redirecting both input and output with <> to a pipe is not supported.

Pipes have an OS-dependent buffer, so writing to a pipe without an active reader does not necessarily block. Pipes must be explicitly closed with file:close.

Putting values into pipes will cause those values to be discarded.

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

~> var 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 $filename $size

changes the size of the named file. If the file is a symbolic link, it changes the size of the link’s target. The size must be an integer between 0 and 2^64-1.