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(io : Io, exn : Exception) -> unit)({
  // Write a file
  io.await(write_file(Path.new(`test.txt`), `hello world`, io), { io, exn });

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

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

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, io : Io) -> Impl(Future(File, IoExn))

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
`io`	Io

Returns: Impl(Future(File, IoExn))

open_with_str : (File) fn(path : str, mode : OpenMode, perm : FilePermission, io : Io) -> Impl(Future(File, IoExn))

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
`io`	Io

Returns: Impl(Future(File, IoExn))

open_with_cstr : (File) fn(path : *(u8), mode : OpenMode, perm : FilePermission, io : Io) -> Impl(Future(File, IoExn))

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
`io`	Io

Returns: Impl(Future(File, IoExn))

open : (File) fn(path : Path, mode : OpenMode, io : Io) -> Impl(Future(File, IoExn))

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

Parameters

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

Returns: Impl(Future(File, IoExn))

open_str : (File) fn(path : str, mode : OpenMode, io : Io) -> Impl(Future(File, IoExn))

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

Parameters

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

Returns: Impl(Future(File, IoExn))

open_cstr : (File) fn(path : *(u8), mode : OpenMode, io : Io) -> Impl(Future(File, IoExn))

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

Parameters

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

Returns: Impl(Future(File, IoExn))

read : (File) fn(self : File, buf : *(u8), size : u32, io : Io) -> Impl(Future(i32, IoExn))

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.
`io`	Io

Returns: Impl(Future(i32, IoExn))

write_string : (File) fn(self : File, data : String, io : Io) -> Impl(Future(i32, IoExn))

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

Parameters

Name	Type	Notes
`self`	File
`data`	String
`io`	Io

Returns: Impl(Future(i32, IoExn))

write_bytes : (File) fn(self : File, data : ArrayList(u8), io : Io) -> Impl(Future(i32, IoExn))

Write bytes to a file, creating or truncating it.

Parameters

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

Returns: Impl(Future(i32, IoExn))

read_bytes : (File) fn(self : File, io : Io) -> Impl(Future(ArrayList(u8), IoExn))

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

Parameters

Name	Type	Notes
`self`	File
`io`	Io

Returns: Impl(Future(ArrayList(u8), IoExn))

read_string : (File) fn(self : File, io : Io) -> Impl(Future(String, IoExn))

Read an entire file into a String.

Parameters

Name	Type	Notes
`self`	File
`io`	Io

Returns: Impl(Future(String, IoExn))

flush : (File) fn(self : File, io : Io) -> Impl(Future(unit, IoExn))

Flush (fsync) file data to disk.

Parameters

Name	Type	Notes
`self`	File
`io`	Io

Returns: Impl(Future(unit, IoExn))

seek : (File) fn(self : File, offset : i64, from : SeekFrom, 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
`exn`	Exception

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, io : Io) -> Impl(Future(unit, IoExn))

Close the file descriptor. Safe to call multiple times.

Parameters

Name	Type	Notes
`self`	File
`io`	Io

Returns: Impl(Future(unit, IoExn))

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, io : Io) -> Impl(Future(Metadata, IoExn))

Get file metadata (size, permissions, timestamps).

Parameters

Name	Type	Notes
`self`	File
`io`	Io

Returns: Impl(Future(Metadata, IoExn))

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, io : Io) -> Impl(Future(String, IoExn))

Read an entire file into a String.

Parameters

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

Returns: Impl(Future(String, IoExn))

read_string_str function

fn(path : str, io : Io) -> Impl(Future(String, IoExn))

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.
`io`	Io

Returns: Impl(Future(String, IoExn))

read_string_cstr function

fn(path : *(u8), io : Io) -> Impl(Future(String, IoExn))

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.
`io`	Io

Returns: Impl(Future(String, IoExn))

read_file function

fn(path : Path, io : Io) -> Impl(Future(ArrayList(u8), IoExn))

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.
`io`	Io

Returns: Impl(Future(ArrayList(u8), IoExn))

read_file_str function

fn(path : str, io : Io) -> Impl(Future(ArrayList(u8), IoExn))

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

Parameters

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

Returns: Impl(Future(ArrayList(u8), IoExn))

read_file_cstr function

fn(path : *(u8), io : Io) -> Impl(Future(ArrayList(u8), IoExn))

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.
`io`	Io

Returns: Impl(Future(ArrayList(u8), IoExn))

write_file function

fn(path : Path, data : String, io : Io) -> Impl(Future(unit, IoExn))

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

Parameters

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

Returns: Impl(Future(unit, IoExn))

write_file_str function

fn(path : str, data : str, io : Io) -> Impl(Future(unit, IoExn))

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

Parameters

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

Returns: Impl(Future(unit, IoExn))

write_file_cstr function

fn(path : *(u8), data : str, io : Io) -> Impl(Future(unit, IoExn))

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

Parameters

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

Returns: Impl(Future(unit, IoExn))

write_bytes function

fn(path : Path, data : ArrayList(u8), io : Io) -> Impl(Future(unit, IoExn))

Write bytes to a file, creating or truncating it.

Parameters

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

Returns: Impl(Future(unit, IoExn))

append_file function

fn(path : Path, data : String, io : Io) -> Impl(Future(unit, IoExn))

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

Parameters

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

Returns: Impl(Future(unit, IoExn))

append_file_str function

fn(path : str, data : str, io : Io) -> Impl(Future(unit, IoExn))

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

Parameters

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

Returns: Impl(Future(unit, IoExn))

exists function

fn(path : Path, 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.