@io

Import this module with import @io.

File Reading

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 (E3150).

Standard Input

Function	Signature	Description
read_stdin_all	() -> string	Read all of standard input to EOF as one string
read_stdin_bytes	() -> [u8]	Read all of standard input to EOF as a packed byte array

File Writing

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

File Operations

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 below)
delete_file	(path string) -> bool	Delete file
rename_file	(old_path string, new_path string) -> bool	Rename file
copy_file	(src string, dst string) -> bool	Copy file
move_file	(src string, dst string) -> bool	Move file

Directory Operations

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; returns empty array on no match

Temporary Files

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

Path Manipulation

Function	Signature	Description
path_join	(parts [string]) -> string	Join path segments; an absolute segment replaces the accumulated path
dirname	(path string) -> string	Parent directory of path
basename	(path string) -> string	Filename component of path
extension	(path string) -> string	File extension including dot (e.g. ".txt"); empty string if none
is_absolute	(path string) -> bool	Check if path is absolute
normalize	(path string) -> string	Clean and normalize path

import @io

do main() {
    mut p string = io.path_join({"/home", "user", "docs"})  // "/home/user/docs"
    mut q string = io.path_join({"a/b", "/abs"})            // "/abs", absolute replaces
    println(p)
    println(q)
}

Fallible Functions

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, _ = ...) — single-variable assignment is a compile-time error (E3089). See Return Value Handling.

Function	Full signature returns
read_file	(string, Error)
read_bytes	([u8], Error)
read_lines	([string], Error)
file_size	(i64, Error)
write_file	(bool, Error)
append_file	(bool, Error)
delete_file	(bool, Error)
rename_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() {
    // Always use destructuring; single-variable assignment is a compile error
    mut content, err = io.read_file("data.txt")
    if err != nil {
        println("read failed: ${err.message}")
    }

    // Discard the error with _
    mut other, _ = io.read_file("data.txt")

    mut lines, lines_err = io.read_lines("data.txt")
    for_each line in lines {
        println(line)
    }

    mut sz, size_err = io.file_size("data.txt")
}

OpenFlag Enum

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 { }
    is .O_WRONLY { }
    is .O_RDWR   { }
    default      { }
}
}

Path Resolution

All relative paths passed to @io functions (and any other stdlib function that accepts a file path, including csv.read_file, csv.write_file, and 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
}