• Modes
• With Blocks
• Methods

A file object, file, is a wrapper around a readable or writable byte stream.

$file(path: str) -> file
$file(path: str, mode: str) -> file

Creates a new file object. Opens the underlying file stream using the C function fopen(). Panics on failure.

If mode is not specified, it defaults to "r" — i.e. open an existing file for reading.

Modes

Mode options:

With Blocks

File objects have builtin support for with blocks, e.g.

with file = $file("data.txt") {
    do_stuff();
}

The file object's close() method will be called when the with block exits, even if the code inside the with block panics or returns early.

Methods

:close()

Closes the file stream. You can safely call close() on a file multiple times.

If the file hasn't been explicitly closed by calling this method, it will be automatically closed by the garbage collector before the file object is destroyed.

:flush()

Flushes the file stream.

:lines() -> iter[str]

Returns an iterator over the files's lines as strings. Recognised line breaks are \n and \r\n. Strips the line breaks from the returned strings.

If this method is called on an empty file, the iterator will be empty, i.e. will return zero elements.

:read() -> buf

Reads the content of the file into a new byte buffer, buf.

Returns the new buffer. Returns an empty buffer if the file was empty or if the end of the file had already been reached before the method was called.

Panics if an I/O read error occurs or if sufficient memory cannot be allocated for the buffer.

:read_byte() -> i64?

Reads the next byte value from the file. Returns the byte value as an integer in the range [0, 255], or null if the end of the file had already been reached before the method was called. Panics if an I/O read error occurs.

:read_bytes(n: i64) -> buf

Attempts to read n bytes from the file into a new byte buffer. May read less than n bytes if the end of the file is reached first.

Returns the new byte buffer. Returns an empty buffer if the end of the file had already been reached before the method was called.

Panics if an I/O read error occurs, if the argument is invalid, or if sufficient memory cannot be allocated for the buffer.

:read_line() -> str?

Reads the next line of input from the file and returns it as a string. Recognised line breaks are \n and \r\n. Strips the line break from the returned string.

Returns null if the end of the file had already been reached before the method was called.

Panics if an I/O read error occurs or if sufficient memory cannot be allocated for the string.

:read_string() -> str

Reads the content of the file into a string, str.

Returns the new string. Returns an empty string if the file was empty or if the end of the file had already been reached before the method was called.

Panics if an I/O read error occurs or if sufficient memory cannot be allocated for the string.

:seek_from_current(offset: i64) -> i64

Seeks to the specified offset from the current position. Returns the value of the file position indicator after the seek operation.

Panics if the file is not seekable.

:seek_from_end(offset: i64) -> i64

Seeks to the specified offset from the end of the file. Returns the value of the file position indicator after the seek operation.

Panics if the file is not seekable.

:seek_from_start(offset: i64) -> i64

Seeks to the specified offset from the start of the file. Returns the value of the file position indicator after the seek operation.

Panics if the file is not seekable.

:tell() -> i64

Returns the current value of the file position indicator.

:write(arg: any) -> i64
:write(format_string: str, *args: any) -> i64

Writes a string or buffer to the file.

• If arg is a str or buf, its content will be written to the file directly.
• Otherwise, calling this method with a single argument is equivalent to calling $str() on that argument first and writing the resulting string.
• Calling this method with more than one argument is equivalent to calling $fmt() on those arguments first and writing the resulting string.

Returns the number of bytes written.

Panics if an I/O write error occurs or if an error occurs while formatting the output string.

:write_byte(byte: i64|char)

Writes a single byte to the file, where byte is an integer in the range [0, 255]. Panics if an I/O write error occurs or if the argument is an invalid type or is out of range.