Module `fs/file`

fs/file

Async file I/O operations with Exception-based error handling.

Wraps a file descriptor with typed async I/O operations. Uses the Exception effect for error handling.

Example

{ File, read_string, write_file, OpenMode } :: import "std/fs/file";

main :: (fn(using(io : IO)) -> unit)({
  given(exn) := Exception(
    throw : (fn(forall(T : Type), error: AnyError) -> T)(
      { println(error); panic("Exception found."); }
    )
  );

  // Write a file
  io.await(write_file(Path.new(`test.txt`), `hello world`));

  // Read it back
  content := io.await(read_string(Path.new(`test.txt`)));
  println(content);

  // Open with OpenMode
  f := io.await(File.open(Path.new(`test.txt`), .Read));
});

Types

File object

File

An open file handle with async read/write operations.

Provides methods for reading, writing, seeking, and querying file metadata. Files are automatically closed when disposed.

Fields

Name	Type	Description
`_fd`	i32
`_path`	Path
`_is_closed`	bool

Trait Implementations

Dispose

impl(File, ...)

open_with : (File) fn(path : Path, mode : OpenMode, perm : FilePermission, using(io : IO)) -> Impl(Future(File, IO, Exception))

Open a file at path with the given mode and custom permissions.

Parameters

Name	Type	Description
`path`	Path	Get the path this file was opened with.
`mode`	OpenMode
`perm`	FilePermission

Returns: Impl(Future(File, IO, Exception))

open_with_str : (File) fn(path : str, mode : OpenMode, perm : FilePermission, using(io : IO)) -> Impl(Future(File, IO, Exception))

Open a file from a str path with the given mode and custom permissions.

Parameters

Name	Type	Description
`path`	str	Get the path this file was opened with.
`mode`	OpenMode
`perm`	FilePermission

Returns: Impl(Future(File, IO, Exception))

open_with_cstr : (File) fn(path : *(u8), mode : OpenMode, perm : FilePermission, using(io : IO)) -> Impl(Future(File, IO, Exception))

Open a file from a C string path with the given mode and custom permissions.

Parameters

Name	Type	Description
`path`	*(u8)	Get the path this file was opened with.
`mode`	OpenMode
`perm`	FilePermission

Returns: Impl(Future(File, IO, Exception))

open : (File) fn(path : Path, mode : OpenMode, using(io : IO)) -> Impl(Future(File, IO, Exception))

Open a file at path with the given mode and default permissions (0o644).

Parameters

Name	Type	Notes	Description
`path`	Path		Get the path this file was opened with.
`mode`	OpenMode

Returns: Impl(Future(File, IO, Exception))

open_str : (File) fn(path : str, mode : OpenMode, using(io : IO)) -> Impl(Future(File, IO, Exception))

Open a file from a str path with the given mode and default permissions.

Parameters

Name	Type	Notes	Description
`path`	str		Get the path this file was opened with.
`mode`	OpenMode

Returns: Impl(Future(File, IO, Exception))

open_cstr : (File) fn(path : *(u8), mode : OpenMode, using(io : IO)) -> Impl(Future(File, IO, Exception))

Open a file from a C string path with the given mode and default permissions.

Parameters

Name	Type	Notes	Description
`path`	*(u8)		Get the path this file was opened with.
`mode`	OpenMode

Returns: Impl(Future(File, IO, Exception))

read : (File) fn(self : File, buf : *(u8), size : u32, using(io : IO)) -> Impl(Future(i32, IO, Exception))

Read up to size bytes into the buffer buf. Returns the number of bytes actually read.

Parameters

Name	Type	Description
`self`	File
`buf`	*(u8)
`size`	u32	Get the file size in bytes.

Returns: Impl(Future(i32, IO, Exception))

write_string : (File) fn(self : File, data : String, using(io : IO)) -> Impl(Future(i32, IO, Exception))

Write a String to the file. Returns the number of bytes written.

Parameters

Name	Type	Notes
`self`	File
`data`	String

Returns: Impl(Future(i32, IO, Exception))

write_bytes : (File) fn(self : File, data : ArrayList(u8), using(io : IO)) -> Impl(Future(i32, IO, Exception))

Write bytes to a file, creating or truncating it.

Parameters

Name	Type	Notes
`self`	File
`data`	ArrayList(u8)

Returns: Impl(Future(i32, IO, Exception))

read_bytes : (File) fn(self : File, using(io : IO)) -> Impl(Future(ArrayList(u8), IO, Exception))

Read the entire file contents into an ArrayList(u8).

Parameters

Name	Type	Notes
`self`	File

Returns: Impl(Future(ArrayList(u8), IO, Exception))

read_string : (File) fn(self : File, using(io : IO)) -> Impl(Future(String, IO, Exception))

Read an entire file into a String.

Parameters

Name	Type	Notes
`self`	File

Returns: Impl(Future(String, IO, Exception))

flush : (File) fn(self : File, using(io : IO)) -> Impl(Future(unit, IO, Exception))

Flush (fsync) file data to disk.

Parameters

Name	Type	Notes
`self`	File

Returns: Impl(Future(unit, IO, Exception))

seek : (File) fn(self : File, offset : i64, from : SeekFrom, using(exn : Exception)) -> i64

Seek to a position relative to from. Returns the new absolute byte offset.

Parameters

Name	Type	Notes
`self`	File
`offset`	i64
`from`	SeekFrom

Returns: i64

position : (File) fn(self : File) -> i64

Get the current file position (byte offset from the beginning).

Parameters

Name	Type	Notes
`self`	File

Returns: i64

size : (File) fn(self : File) -> i64

Get the file size in bytes.

Parameters

Name	Type	Notes
`self`	File

Returns: i64

close : (File) fn(self : File, using(io : IO)) -> Impl(Future(unit, IO, Exception))

Close the file descriptor. Safe to call multiple times.

Parameters

Name	Type	Notes
`self`	File

Returns: Impl(Future(unit, IO, Exception))

fd : (File) fn(self : File) -> i32

Get the underlying file descriptor.

Parameters

Name	Type	Notes
`self`	File

Returns: i32

path : (File) fn(self : File) -> Path

Get the path this file was opened with.

Parameters

Name	Type	Notes
`self`	File

Returns: Path

metadata : (File) fn(self : File, using(io : IO)) -> Impl(Future(Metadata, IO, Exception))

Get file metadata (size, permissions, timestamps).

Parameters

Name	Type	Notes
`self`	File

Returns: Impl(Future(Metadata, IO, Exception))

impl(File, Dispose(...))

dispose : (fn(self: Self) -> unit)

Returns: unit

OpenMode enum

OpenMode

Variants

Variant	Fields	Description
`Read`
`Write`
`Append`
`ReadWrite`
`CreateNew`

FilePermission newtype

FilePermission

Fields

Name	Type	Description
`mode`	u32

Methods

default : (FilePermission) fn() -> FilePermission

Returns: FilePermission

executable : (FilePermission) fn() -> FilePermission

Returns: FilePermission

readonly : (FilePermission) fn() -> FilePermission

Returns: FilePermission

private : (FilePermission) fn() -> FilePermission

Returns: FilePermission

SeekFrom enum

SeekFrom

Variants

Variant	Fields	Description
`Start`
`Current`
`End`

Functions

read_string function

fn(path : Path, using(io : IO)) -> Impl(Future(String, IO, Exception))

Read an entire file into a String.

Parameters

Name	Type	Notes	Description
`path`	Path		Get the path this file was opened with.

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(String, IO, Exception))

read_string_str function

fn(path : str, using(io : IO)) -> Impl(Future(String, IO, Exception))

Read an entire file into a String (str path variant).

Parameters

Name	Type	Notes	Description
`path`	str		Get the path this file was opened with.

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(String, IO, Exception))

read_string_cstr function

fn(path : *(u8), using(io : IO)) -> Impl(Future(String, IO, Exception))

Read an entire file into a String (C string path variant).

Parameters

Name	Type	Notes	Description
`path`	*(u8)		Get the path this file was opened with.

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(String, IO, Exception))

read_file function

fn(path : Path, using(io : IO)) -> Impl(Future(ArrayList(u8), IO, Exception))

Read an entire file into a byte list (ArrayList(u8)).

Parameters

Name	Type	Notes	Description
`path`	Path		Get the path this file was opened with.

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(ArrayList(u8), IO, Exception))

read_file_str function

fn(path : str, using(io : IO)) -> Impl(Future(ArrayList(u8), IO, Exception))

Read an entire file into bytes (str path variant).

Parameters

Name	Type	Notes	Description
`path`	str		Get the path this file was opened with.

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(ArrayList(u8), IO, Exception))

read_file_cstr function

fn(path : *(u8), using(io : IO)) -> Impl(Future(ArrayList(u8), IO, Exception))

Read an entire file into bytes (C string path variant).

Parameters

Name	Type	Notes	Description
`path`	*(u8)		Get the path this file was opened with.

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(ArrayList(u8), IO, Exception))

write_file function

fn(path : Path, data : String, using(io : IO)) -> Impl(Future(unit, IO, Exception))

Write a String to a file, creating or truncating it.

Parameters

Name	Type	Notes	Description
`path`	Path		Get the path this file was opened with.
`data`	String

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(unit, IO, Exception))

write_file_str function

fn(path : str, data : str, using(io : IO)) -> Impl(Future(unit, IO, Exception))

Write a str to a file, creating or truncating it (str path variant).

Parameters

Name	Type	Notes	Description
`path`	str		Get the path this file was opened with.
`data`	str

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(unit, IO, Exception))

write_file_cstr function

fn(path : *(u8), data : str, using(io : IO)) -> Impl(Future(unit, IO, Exception))

Write a str to a file, creating or truncating it (C string path variant).

Parameters

Name	Type	Notes	Description
`path`	*(u8)		Get the path this file was opened with.
`data`	str

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(unit, IO, Exception))

write_bytes function

fn(path : Path, data : ArrayList(u8), using(io : IO)) -> Impl(Future(unit, IO, Exception))

Write bytes to a file, creating or truncating it.

Parameters

Name	Type	Notes	Description
`path`	Path		Get the path this file was opened with.
`data`	ArrayList(u8)

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(unit, IO, Exception))

append_file function

fn(path : Path, data : String, using(io : IO)) -> Impl(Future(unit, IO, Exception))

Append a String to a file, creating it if it does not exist.

Parameters

Name	Type	Notes	Description
`path`	Path		Get the path this file was opened with.
`data`	String

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(unit, IO, Exception))

append_file_str function

fn(path : str, data : str, using(io : IO)) -> Impl(Future(unit, IO, Exception))

Append a str to a file (str path variant).

Parameters

Name	Type	Notes	Description
`path`	str		Get the path this file was opened with.
`data`	str

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(unit, IO, Exception))

exists function

fn(path : Path, using(io : IO)) -> Impl(Future(bool, IO))

Check if a path exists. Returns false for any error including file not found. Does not use the Exception effect.

Parameters

Name	Type	Notes	Description
`path`	Path		Get the path this file was opened with.

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(bool, IO))

exists_str function

fn(path : str, using(io : IO)) -> Impl(Future(bool, IO))

Check if a path exists (str path variant).

Parameters

Name	Type	Notes	Description
`path`	str		Get the path this file was opened with.

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(bool, IO))

exists_cstr function

fn(path : *(u8), using(io : IO)) -> Impl(Future(bool, IO))

Check if a path exists (C string path variant).

Parameters

Name	Type	Notes	Description
`path`	*(u8)		Get the path this file was opened with.

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(bool, IO))

is_file function

fn(path : Path, using(io : IO)) -> Impl(Future(bool, IO))

Check if a path is a regular file. Returns false for any error.

Parameters

Name	Type	Notes	Description
`path`	Path		Get the path this file was opened with.

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(bool, IO))

is_file_str function

fn(path : str, using(io : IO)) -> Impl(Future(bool, IO))

Check if a path is a regular file (str path variant).

Parameters

Name	Type	Notes	Description
`path`	str		Get the path this file was opened with.

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(bool, IO))

is_file_cstr function

fn(path : *(u8), using(io : IO)) -> Impl(Future(bool, IO))

Check if a path is a regular file (C string path variant).

Parameters

Name	Type	Notes	Description
`path`	*(u8)		Get the path this file was opened with.

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(bool, IO))

is_dir function

fn(path : Path, using(io : IO)) -> Impl(Future(bool, IO))

Check if a path is a directory. Returns false for any error.

Parameters

Name	Type	Notes	Description
`path`	Path		Get the path this file was opened with.

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(bool, IO))

is_dir_str function

fn(path : str, using(io : IO)) -> Impl(Future(bool, IO))

Check if a path is a directory (str path variant).

Parameters

Name	Type	Notes	Description
`path`	str		Get the path this file was opened with.

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(bool, IO))

is_dir_cstr function

fn(path : *(u8), using(io : IO)) -> Impl(Future(bool, IO))

Check if a path is a directory (C string path variant).

Parameters

Name	Type	Notes	Description
`path`	*(u8)		Get the path this file was opened with.

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(bool, IO))

canonical function

fn(path : Path, using(io : IO)) -> Impl(Future(Path, IO, Exception))

Resolve a path to its canonical absolute form (resolves symlinks, . and ..). Throws if the path does not exist.

Parameters

Name	Type	Notes	Description
`path`	Path		Get the path this file was opened with.

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(Path, IO, Exception))

canonical_str function

fn(path : str, using(io : IO)) -> Impl(Future(Path, IO, Exception))

Resolve a path to its canonical absolute form (str path variant).

Parameters

Name	Type	Notes	Description
`path`	str		Get the path this file was opened with.

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(Path, IO, Exception))

canonical_cstr function

fn(path : *(u8), using(io : IO)) -> Impl(Future(Path, IO, Exception))

Resolve a path to its canonical absolute form (C string path variant).

Parameters

Name	Type	Notes	Description
`path`	*(u8)		Get the path this file was opened with.

Effects

Name	Type	Notes
`io`	IO	comptime, implicit

Returns: Impl(Future(Path, IO, Exception))

Module fs/file

Example

Types

Fields

Trait Implementations

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Variants

Fields

Variants

Functions

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Parameters

Effects

Module `fs/file`