Skip to content

@io

Import this module with import @io.

Function Signature Description
read_file (path string) -> string Read entire file as a string
read_bytes (path string) -> [u8] Read entire file as a byte array
read_lines (path string, limit i64 = 0) -> [string] Read the file line by line (strips \r\n). limit caps how many lines are returned — a count, like range(0, N); 0 reads to EOF. A negative literal limit is a compile error.
Function Signature Description
read_stdin_all () -> string Read all of standard input to EOF as one string
stdin_at_eof () -> bool true when standard input has no more data; waits for input on an interactive stdin
read_stdin_bytes () -> [u8] Read all of standard input to EOF as a packed byte array
Function Signature Description
write_file (path string, content string) -> bool Write file
append_file (path string, content string) -> bool Append to file
write_bytes (path string, data [u8]) -> bool Write byte array to file
append_bytes (path string, data [u8]) -> bool Append byte array to file
Function Signature Description
file_exists (path string) -> bool Check if file exists
is_file (path string) -> bool Check if path is a regular file
is_directory (path string) -> bool Check if path is a directory
file_size (path string) -> i64 Get file size in bytes (fallible; see Fallible Functions)
chmod (path string, mode i64) -> bool Set permission bits; on Windows only the read-only bit (fallible; see Fallible Functions)
stat (path string) -> FileInfo Get file metadata without following a final symlink (fallible; see Fallible Functions)
delete_file (path string) -> bool Delete file
copy_file (src string, dst string) -> bool Copy file
move_file (src string, dst string) -> bool Move file
Function Signature Description
list_dir (path string) -> [string] List directory entries
make_dir (path string) -> bool Create directory
make_dir_all (path string) -> bool Create directory and all parents
remove_dir (path string) -> bool Remove empty directory
remove_dir_all (path string) -> bool Remove directory and all contents
walk (path string) -> [string] Recursively list all files
glob (pattern string) -> [string] Match files by glob pattern; ? and a bracket expression match one character (a codepoint), not one byte; returns empty array on no match
Function Signature Description
temp_file () -> string Create a temporary file; returns its path. Automatically deleted on exit
temp_dir () -> string Create a temporary directory; returns its path. Automatically deleted on exit

The functions below are fallible: they return (T, Error), and the tables above show only the success type T. Always use destructuring (mut v, err = ... or mut v, _ = ...) See Return Value Handling.

Function Full signature returns
read_file (string, Error)
read_bytes ([u8], Error)
read_lines ([string], Error)
file_size (i64, Error)
chmod (bool, Error)
stat (FileInfo, Error)
write_file (bool, Error)
append_file (bool, Error)
delete_file (bool, Error)
copy_file (bool, Error)
move_file (bool, Error)
list_dir ([string], Error)
make_dir (bool, Error)
make_dir_all (bool, Error)
remove_dir (bool, Error)
remove_dir_all (bool, Error)
walk ([string], Error)
glob ([string], Error)
write_bytes (bool, Error)
append_bytes (bool, Error)
temp_file (string, Error)
temp_dir (string, Error)
import @io
do main() {
mut info, err = io.stat("data.txt")
if err == nil {
println("${info.size} bytes, symlink: ${info.is_symlink}")
}
}

stat returns a FileInfo: size i64 (bytes), mode i64 (permission bits, also on Windows), mod_time i64 (seconds since the Unix epoch), and is_dir, is_file, is_symlink (all bool). stat does not follow a final symlink, so is_symlink is accurate. A missing path returns an Error. FileInfo is reserved as a type name only while @io is imported.

import @io
do main() {
mut info, err = io.stat("data.txt")
if err == nil {
println("${info.size} bytes, symlink: ${info.is_symlink}")
}
}

io provides the OpenFlag enum for the mutually-exclusive open modes. Reachable as io.O_RDONLY or OpenFlag.O_RDONLY (both denote the same value). Underlying values: O_RDONLY 0, O_WRONLY 1, O_RDWR 2. OpenFlag is reserved as a type name only while @io is imported.

import @io
do main() {
mut mode OpenFlag = io.O_RDWR
when mode {
is .O_RDONLY { println("read only") }
is .O_WRONLY { println("write only") }
is .O_RDWR { println("read and write") }
default { println("other") }
}
}

All relative paths passed to @io functions (and any other stdlib function that accepts a file path, including sqlite.open) are resolved relative to the current working directory of the process, the directory from which the program was launched. They are not resolved relative to the source file that contains the call.

project/
import @io
// Given project layout:
// main.gray
// src/cli.gray
// data/config.json
// Running from project/: gray main.gray
// All of these resolve from project/, regardless of which .gray file calls them:
do main() {
mut a, _ = io.read_file("data/config.json") // project/data/config.json
mut b, _ = io.read_file("./data/config.json") // same thing
mut c, _ = io.read_file("/etc/hosts") // absolute path, unaffected by cwd
println(a)
println(b)
println(c)
}