File

Standard library namespace · Always available, with no import

File reads and writes files. Most programs need only a few things: read a whole file as text, write text to one, and ask whether one exists.

File.write("notes.txt", "Buy milk\nCall Ada\n")
print(File.read("notes.txt"))
print(File.read_lines("notes.txt"))

Output

Buy milk
Call Ada

["Buy milk", "Call Ada"]

A path is a String. A relative one, such as "notes.txt", is looked up from the folder the program was run in. Text files are read and written as UTF-8, and a file that isn’t valid UTF-8 is an error rather than garbled text; read it as Bytes instead.

When a file operation fails, because the file isn’t there or can’t be written, it raises a FileError. Use File.exists? first when a missing file is something the program expects:

if File.exists?("settings.txt") {
    print(File.read("settings.txt"))
}
else {
    print("No settings yet.")
}

Output

No settings yet.

For a file too large to hold in memory, or one you want to read a line at a time, open it with open or create. To work with folders, see Directory, and for file names, Path.

At a glance

Whole files as text
File.read(path)	The whole file as a String
File.read_lines(path)	The file as a List[String], one item per line
File.write(path, contents)	Create the file, or replace what it holds
File.write_lines(path, lines)	Write a list of lines, each followed by a line break
File.append(path, contents)	Add text to the end of the file

Whole files as bytes
File.read_binary(path)	The whole file as Bytes
File.write_binary(path, bytes)	Create the file, or replace what it holds

Managing files
File.exists?(path)	Whether there is a file at the path
File.copy(source, destination)	Make a copy of a file
File.move(source, destination)	Move or rename a file
File.delete(path)	Remove a file

Streaming
File.open(path), File.with_open(path)	Read a file piece by piece
File.create(path), File.with_writer(path)	Write a file piece by piece

Whole files as text

File.read(path: String): String

The whole file as one String, line breaks included.

Raises a FileError when the file doesn’t exist or can’t be read, or when its contents aren’t valid UTF-8 text.

File.read_lines(path: String): List[String]

The file as a list with one item for each line, without the line breaks.

File.write("scores.txt", "90\n85\n\n70\n")
const lines = File.read_lines("scores.txt")
print(lines.count)
print(lines)

Output

4
["90", "85", "", "70"]

File.write("windows.txt", "one\r\ntwo\r\n")
print(File.read_lines("windows.txt"))

Output

["one", "two"]

Every line break ends a line, so a blank line stays in the list as "". A Windows line break, which is two characters, counts as one and is removed whole, so a file reads the same whichever computer wrote it. A line break at the very end of the file adds no extra line, and a file with nothing in it gives an empty list.

Raises a FileError in the same cases as read.

File.write(path: String, contents: String)

Puts contents in the file, creating it if it isn’t there. If the file already holds something, it is replaced, so use append to keep what is there.

File.write("greeting.txt", "Hello")
File.write("greeting.txt", "Goodbye")
print(File.read("greeting.txt"))

Output

Goodbye

The folder the file goes in must already exist; make it with Directory.create.

Raises a FileError when the file can’t be written, such as when its folder doesn’t exist.

File.write_lines(path: String, lines: List[String])

Writes each item of lines followed by a line break, including the last one, so the file ends the way a text file normally does. Like write, it replaces what the file held.

File.write_lines("todo.txt", ["Buy milk", "Call Ada"])
print(File.read("todo.txt").count)
print(File.read_lines("todo.txt"))

Output

18
["Buy milk", "Call Ada"]

Raises a FileError in the same cases as write.

File.append(path: String, contents: String)

Adds contents to the end of the file, creating the file if it isn’t there. Nothing is added between the old text and the new, so include a line break when you want one.

File.write("log.txt", "started\n")
File.append("log.txt", "finished\n")
print(File.read_lines("log.txt"))

Output

["started", "finished"]

Raises a FileError when the file can’t be read or written.

Whole files as bytes

File.read_binary(path: String): Bytes

The whole file as Bytes, with no check that it is text. Use it for images, archives, and any other file that isn’t plain text.

Raises a FileError when the file doesn’t exist or can’t be read.

File.write_binary(path: String, bytes: Bytes)

Puts bytes in the file, creating it if it isn’t there, and replacing what it held.

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

Output

Bytes[3: 01 02 ff]

Raises a FileError when the file can’t be written.

Managing files

File.exists?(path: String): Bool

Whether there is a file at path. A folder is not a file, so for a folder this is false; ask Directory.exists? instead.

File.copy(source: String, destination: String)

Makes a copy of the file at source at destination, leaving the original where it is.

Raises a FileError when source doesn’t exist or the copy can’t be made.

File.move(source: String, destination: String)

Moves the file at source to destination. Moving a file to another name in the same folder renames it.

File.write("draft.txt", "text")
File.move("draft.txt", "final.txt")
print(File.exists?("draft.txt"), File.exists?("final.txt"))

Output

false true

Raises a FileError when source doesn’t exist or the move can’t be made.

File.delete(path: String)

Removes the file at path. To remove a folder, see Directory.delete.

Raises a FileError when the file doesn’t exist or can’t be removed.

Streaming

File.open(path: String): FileHandle

Opens a text file for reading and gives back a FileHandle, which reads it a line at a time. Close the handle when you’re done, or use with_open, which does it for you.

Raises a FileError when the file doesn’t exist or can’t be read.

File.with_open(path: String) { handle: FileHandle => ... }

Opens the file, gives the open FileHandle to the block, and closes it afterwards, whether the block finishes normally, returns early, or raises an error.

File.write_lines("names.txt", ["Ada", "Grace"])
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!

Prefer this to open for most work, since the file is closed even when something goes wrong.

Raises a FileError when the file doesn’t exist or can’t be read.

File.create(path: String): FileWriter

Creates a text file for writing, replacing it if it already exists, and gives back a FileWriter, which writes to it a piece at a time. Close the writer when you’re done, or use with_writer.

Raises a FileError when the file can’t be created.

File.with_writer(path: String) { writer: FileWriter => ... }

Creates the file, gives the open FileWriter to the block, and closes it afterwards, whether the block finishes normally, returns early, or raises an error.

File.with_writer("count.txt", { writer =>
    for n in 1..3 {
        writer.write("#{n}\n")
    }
})
print(File.read_lines("count.txt"))

Output

["1", "2", "3"]

Raises a FileError when the file can’t be created or written.