Struct file 

pub struct file;

A handle to an open file.

File handles are full userdata values with a shared metatable, so every operation is available in method form (f:read(...)). When a file handle is collected without being closed, its finalizer closes the file.

Implementations

impl file

pub fn close(&self) -> boolean

Closes a file.

Return value

True on success. Note that files are automatically closed when their handles are garbage collected, but that takes an unpredictable amount of time to happen.

Examples

local f = assert(io.open("notes.txt"))
print(f:read("a"))
f:close()

pub fn flush(&self)

Flushes a file’s output buffer.

Description

Saves any written data to the file. Useful to make sure output is visible before the file is closed — for example, when writing a progress log that another process is watching.

Examples

log:write("step 3 done\n")
log:flush()

See also

setvbuf

pub fn lines(&self, formats: Repeatable<string>) -> function

Returns an iterator over the file’s contents.

Parameters

• ···: read formats, as in read (default "l", read a line).

Return value

An iterator function that, each time it is called, reads the file according to the given formats. When the iterator reaches the end of the file, it returns nil. Unlike io.lines, this form does not close the file when the loop ends.

Examples

local f = assert(io.open("data.txt"))
for line in f:lines() do
  print(line)
end
f:close()

pub fn read(&self, formats: Repeatable<string>) -> Repeatable<any>

Reads from a file.

Parameters

• ···: one or more read formats: "n" reads a numeral, "a" reads the whole file from the current position, "l" reads the next line dropping the newline (the default), "L" reads the next line keeping the newline, and a number reads that many bytes.

Return value

For each format, a string or a number with the characters read, or nil if it cannot read data with that format (e.g. at end of file).

Examples

local f = assert(io.open("data.txt"))
local first = f:read("l")     -- one line
local rest  = f:read("a")     -- everything else
local n     = io.stdin:read("n")   -- a number from stdin

See also

lines, io.read

pub fn seek( &self, whence: option<string>, offset: option<number>, ) -> option<number>

Sets and gets the file position.

Parameters

• whence: the base for the offset: "set" (the beginning of the file), "cur" (the current position — the default), or "end" (the end of the file).
• offset: an offset in bytes from the base (default 0).

Return value

The resulting file position, measured in bytes from the beginning of the file, or nil plus an error message on failure. The no-argument call f:seek() reads the current position without changing it, and f:seek("end") returns the file size.

Examples

local size = f:seek("end")    -- file size in bytes
f:seek("set")                 -- rewind to the start
f:seek("cur", 16)             -- skip 16 bytes

pub fn setvbuf(&self, mode: string, size: option<number>)

Sets the buffering mode for a file.

Parameters

• mode: "no" (no buffering: output appears immediately), "full" (output is flushed when the buffer fills or the file is closed), or "line" (output is buffered until a newline is written).
• size: a hint for the buffer size, in bytes.

Examples

log:setvbuf("line")    -- flush the log after every line

See also

flush

pub fn write(&self, values: Repeatable<any>) -> file

Writes to a file.

Parameters

• ···: strings or numbers to write. Other values must be converted first (with tostring or string.format).

Return value

The file itself, so write calls can be chained; on error, nil plus an error message.

Examples

f:write("x = "):write(42):write("\n")
io.stdout:write("no newline is added")

See also

io.write