FileHandle

Standard library class · Made with File.open

A FileHandle is a text file that is open for reading. Unlike File.read, which brings the whole file into the program at once, a handle reads it a piece at a time, so a program can work through a large file, or stop partway.

File.write_lines("names.txt", ["Ada", "Grace", "Katherine"])

const handle = File.open("names.txt")
print(handle.read_line())
print(handle.read_line())
handle.close()

Output

Ada
Grace

A handle remembers where it has read up to, and each read carries on from there. It only reads; to write a file a piece at a time, use a FileWriter.

Make a handle with File.open, and close it when you are done. Better still, let File.with_open do both, so the file is closed even if something goes wrong:

File.write_lines("names.txt", ["Ada", "Grace", "Katherine"])

File.with_open("names.txt", { handle =>
    var line = handle.read_line()
    while line != nothing {
        print("Hello, #{line}!")
        line = handle.read_line()
    }
})

Output

Hello, Ada!
Hello, Grace!
Hello, Katherine!

At a glance

Reading text
read_line()	The next line, or nothing at the end
read()	Everything left, as one String

Reading bytes
read_bytes(count)	Up to count of the bytes left, or nothing at the end
read_all_bytes()	Every byte left

Finishing
close()	Let go of the file

Reading text

read_line(): String?

The next line, without its line break, or nothing once there are no more lines. Use it in a loop that stops at nothing, as above.

It splits lines the same way File.read_lines does: a Windows line break is removed whole, a blank line comes back as "", a line break at the very end of the file adds no extra line, and a final line with no line break is still returned.

Raises a FileError when the handle has been closed.

read(): String

Everything not yet read, as one String. Right after File.open that is the whole file; after a few read_lines it is the rest.

File.write_lines("names.txt", ["Ada", "Grace", "Katherine"])

const handle = File.open("names.txt")
print(handle.read_line())
print(handle.read())
handle.close()

Output

Ada
Grace
Katherine

Raises a FileError when the handle has been closed, or when the text left isn’t valid UTF-8.

Reading bytes

read_bytes(count: Int): Bytes?

Up to count of the bytes not yet read, as Bytes, or nothing when there are none left. Fewer than count come back when the file ends first.

File.write_binary("data.bin", Bytes.from_list([1, 2, 255]))

const handle = File.open("data.bin")
print(handle.read_bytes(2))
print(handle.read_bytes(2))
print(handle.read_bytes(2))
handle.close()

Output

Bytes[2: 01 02]
Bytes[1: ff]
nothing

Raises a FileError when the handle has been closed.

read_all_bytes(): Bytes

Every byte not yet read.

Raises a FileError when the handle has been closed.

Finishing

close()

Lets go of the file. Closing a handle that is already closed does nothing, so it is safe to close one twice. Reading from a closed handle is an error:

File.write("note.txt", "hi")

const handle = File.open("note.txt")
handle.close()
print(handle.read_line())

Output

note.em:5:7: FileError: cannot read from a closed file
  print(handle.read_line())
        ^^^^^^^^^^^^^^^^^^
Check that the path exists and that this program may access it.