io module

File and directory primitives. Every blocking call has an async counterpart (*_async); for very large files use the streaming open_read / open_write.

import "io" as io;

io.write_file("greeting.txt", "Hello!");
print(io.read_file("greeting.txt"));

Sync file I/O

FunctionDescription
io.read_file(path) → stringRead the whole file into a string.
io.write_file(path, data)Overwrite the file with data.
io.append_file(path, data)Append data; creates the file if missing.

Async file I/O

*_async functions return a Future — pair with wait.

FunctionDescription
io.read_file_async(path) → Future<string>Read off the main thread; suitable for large files.
io.write_file_async(path, data) → Future<null>Write off the main thread.
function copy() {
    var data = wait io.read_file_async("big.bin");
    wait io.write_file_async("big.copy.bin", data);
}

Streaming

open_read / open_write return a stream object whose read / write are themselves Future-returning. The underlying callback-style methods are still available on the native _io module for low-level code.

FunctionDescription
io.open_read(path) → streamstream.read(size) returns Future<chunk>; chunk == null means EOF. stream.close() is sync.
io.open_write(path) → streamstream.write(data) returns Future<null>. stream.close() is sync — call it to flush.
function read_chunks(path) {
    var src = io.open_read(path);
    var chunk = wait src.read(4096);
    while (chunk != null) {
        print(chunk);
        chunk = wait src.read(4096);
    }
    src.close();
}

Native _io (advanced)

The native module is also available as _io for low-level callback-style code (used by the lib internally). User code should prefer import "io".

Metadata

FunctionDescription
io.exists(path) → boolTrue if the path exists.
io.is_file(path) → bool
io.is_dir(path) → bool
io.stat(path) → map{bytes, mtime, is_file, is_dir}. Throws if missing.

Directories

FunctionDescription
io.mkdir(path)Creates intermediate parents automatically.
io.list_dir(path) → listEntry names (no . / ..).
io.remove(path)File or directory; recursive for directories.
io.rename(from, to)
io.copy_file(from, to)

See also