core.io

FileDesc : struct {
    handle : os.FileHandle
    mode   : FileMode
    path   : string
}

Owns an open file descriptor and records the mode and borrowed path used to
open it. Call close(^FileDesc) exactly once to close the handle and release
the descriptor.

DirEntry : struct {
    name : string
    path : string
    // These flags describe the entry itself and never follow a link target.
    is_file : bool
    is_dir : bool
    is_symbolic_link : bool
    is_directory_link : bool
}

Describes one entry returned by list_dir.

The name and path strings in a successful list_dir result are owned by the
result's allocator. The classification flags describe the entry itself and
never follow a link target.

open : func(path : string, options : FileMode) -> [^FileDesc, IoStatus]

Opens a file using the requested mode.

Parameters:
  path    : string       - borrowed filesystem path.
  options : FileMode - requested access and creation mode.

Returns:
  [^FileDesc, IoStatus] - owned descriptor and operation status. The
                          descriptor is null on failure.

Notes:
  - The returned descriptor owns its OS handle.
  - The path header is borrowed; its backing storage must remain valid while
    the descriptor is in use.
  - Call close(^FileDesc) exactly once to close and release the descriptor.

open_read : func(path : string) -> [^FileDesc, IoStatus]

Opens an existing file for reading.

Parameters:
  path : string - borrowed filesystem path.

Returns:
  [^FileDesc, IoStatus] - owned descriptor and operation status.

open_write : func(path : string) -> [^FileDesc, IoStatus]

Creates or truncates a file and opens it for writing.

Parameters:
  path : string - borrowed filesystem path.

Returns:
  [^FileDesc, IoStatus] - owned descriptor and operation status.

seek : func(file : ^FileDesc, offset : i64, origin : SeekOrigin) -> [i64, IoStatus]

Moves the position of an open file descriptor.

Parameters:
  file   : ^FileDesc - descriptor to reposition.
  offset : i64       - signed byte offset relative to origin.
  origin : SeekOrigin - reference position used to interpret offset.

Returns:
  [i64, IoStatus] - new absolute position with IoStatus.Ok on success, or
                    -1 with an error status on failure.

close : func(file : ^FileDesc) -> [bool, IoStatus]

Closes and releases an owned file descriptor.

Parameters:
  file : ^FileDesc - descriptor returned by open, open_read, or open_write.

Returns:
  [bool, IoStatus] - true with IoStatus.Ok on success; false with an error
                     status when the descriptor or handle is invalid or the
                     OS close operation fails.

Notes:
  - The descriptor pointer is invalid after this call, even when the OS
    close operation reports an error.

file_length : func(path : string ) -> [i64, IoStatus]

Returns the size in bytes of the file at `path` through the portable
OS metadata API.

Parameters:
  path : string - filesystem path to the file to query.

Returns:
  [i64, IoStatus]
    - On success: [<file size in bytes>, IoStatus.Ok]
    - On failure: [-1, IoStatus.InvalidFile] when metadata lookup fails
      (e.g. file missing, permission denied, broken path).

Notes:
  - Does not open or read the file; only its metadata is inspected.

length : func(file : ^FileDesc) -> i64

Returns the size in bytes of the file backing a FileDesc.

Parameters:
  file : ^FileDesc - descriptor whose underlying file size is queried.

Returns:
  i64 - size of the file in bytes, or -1 when metadata lookup fails.

position : func(file : ^FileDesc) -> [i64, IoStatus]

Returns the current byte offset of a FileDesc within its underlying
file.

Parameters:
  file : ^FileDesc - descriptor whose current position is queried.
                     Must be non-null and seekable.

Returns:
  [i64, IoStatus] - current byte offset and an error status.
                   On success returns the current position and IoStatus.Ok.
                   On failure returns -1 and:
                     IoStatus.InvalidFile      - `file` was null.
                     IoStatus.DontSupportSeek  - file is not seekable.
                     IoStatus.CannotSeek       - underlying OS seek failed.

Notes:
  - This queries the underlying OS file handle using SEEK_CUR without
    moving the cursor.

opened : func(file : ^FileDesc) -> [bool, IoStatus]

Reports whether a FileDesc's underlying handle is currently valid
and open.

Parameters:
  file : ^FileDesc - descriptor to query. Must be non-null.

Returns:
  [bool, IoStatus] - the open state of the file and an error status.
                    On success returns the validity of the handle and
                    the IoStatus reported by the platform check.
                    On failure returns:
                      IoStatus.InvalidFile - `file` was null.

read_all_text : func(path : string, allocator : ^Allocator ) -> [string, IoStatus]

Reads the entire contents of the file at `path` into a single
`string`, allocated through the caller-supplied allocator.

Parameters:
  path      : string      - filesystem path to the file to read.
  allocator : ^Allocator  - allocator used to back the returned
                            string's buffer. Must be non-null.

Returns:
  [string, IoStatus]
    - On success: [<file contents>, IoStatus.Ok]
    - On failure: [string{}, IoStatus.InvalidFile] when the file
      does not exist or its size cannot be determined.
    - On failure: [string{}, IoStatus.InvalidAllocator] when
      `allocator` is null.
    - Other IoStatus values may propagate from opening or reading the file.

Notes:
  - Opens and closes a FileDesc internally.
  - The returned string is owned by the caller and must be released with
    the supplied allocator.

read_all_text : func(file : ^FileDesc) -> [string, IoStatus]

Reads the entire contents of a FileDesc into a newly allocated
string.

Parameters:
  file : ^FileDesc - descriptor to read from. Must be non-null and readable.

Returns:
  [string, IoStatus] - the file contents and an error status.
                      On success returns the full file contents and
                      IoStatus.Ok.
                      On failure returns an empty string and:
                        IoStatus.InvalidFile      - `file` was null.
                        IoStatus.InvalidAllocator - context.allocator was null.
                        IoStatus.CannotRead       - file is not readable.
                        IoStatus.ReadError        - underlying read failed.

Notes:
  - The returned string is allocated with context.allocator; the caller is
    responsible for releasing it with that allocator.

read : func(file : ^FileDesc, size : i64, buffer : ^[]i8) -> [i64, IoStatus]

Reads up to `size` bytes from a FileDesc into the caller's signed-byte
buffer.

Parameters:
  file   : ^FileDesc - descriptor to read from. Must be non-null and readable.
  size   : i64       - maximum number of bytes to read. Must fit in buffer.
  buffer : ^[]i8     - destination byte slice.

Returns:
  [i64, IoStatus] - number of bytes read and operation status.
                   On failure returns -1 and:
                     IoStatus.InvalidFile - `file` was null.
                     IoStatus.InvalidArg  - `buffer` was null, `size` or the
                                            buffer length was negative,
                                            `size` exceeded the buffer length,
                                            or a positive read had null data.
                     IoStatus.CannotRead  - file mode is not readable.
                     IoStatus.ReadError   - underlying OS read failed.
                   A zero size returns [0, IoStatus.Ok].

read_bytes : func(file : ^FileDesc, buffer : ^[]u8) -> [i64, IoStatus]

Reads up to `buffer.length` bytes from a FileDesc into the caller's
byte buffer.

Parameters:
  file   : ^FileDesc - descriptor to read from. Must be non-null and readable.
  buffer : ^[]u8     - destination byte slice; the slice's `length`
                       dictates how many bytes are requested.

Returns:
  [i64, IoStatus] - number of bytes read and an error status.
                   On success returns the byte count and IoStatus.Ok.
                   On failure returns -1 and:
                     IoStatus.InvalidFile      - `file` was null.
                     IoStatus.InvalidArg       - `buffer` was null, its
                                                 length was negative, or a
                                                 positive-length slice had
                                                 null data.
                     IoStatus.CannotRead       - file is not readable.
                     IoStatus.ReadError        - underlying OS read failed.
                   A zero-length buffer returns [0, IoStatus.Ok].

read_line : func(file : ^FileDesc) -> [string, IoStatus]

Reads a single line of text from a FileDesc into a newly allocated
string.

Parameters:
  file : ^FileDesc - descriptor to read from. Must be non-null and readable.

Returns:
  [string, IoStatus] - line contents and an error status.
                      On success returns the line without the trailing
                      newline character and IoStatus.Ok.
                      On failure returns an empty string and:
                        IoStatus.InvalidFile      - `file` was null.
                        IoStatus.InvalidAllocator - context.allocator was null.
                        IoStatus.CannotRead       - file is not readable.
                        IoStatus.AllocatorFailed  - line buffer allocation failed.
                        IoStatus.ReadError        - underlying read failed.

Notes:
  - The returned string is allocated with context.allocator; the caller is
    responsible for releasing it with that allocator.
  - The returned string does not include the '\n' line terminator.
  - EOF before any bytes returns an empty string with IoStatus.Ok.
  - EOF after partial data returns that partial line with IoStatus.Ok.

write_bytes : func(file : ^FileDesc, buffer : []u8) -> [i64, IoStatus]

Writes the complete contents of `buffer` to a FileDesc.

Parameters:
  file   : ^FileDesc - descriptor to write to. Must be non-null and writable.
  buffer : []u8     - source byte slice to write.

Returns:
  [i64, IoStatus] - number of bytes written and operation status.
                   On failure, the byte count reports any successfully
                   written prefix.
                   Validation failures return -1 and:
                     IoStatus.InvalidFile      - `file` was null.
                     IoStatus.InvalidArg       - `buffer.length` was negative
                                                 or positive with null data.
                     IoStatus.CannotWrite      - file mode is not writable.
                     IoStatus.WriteError       - an OS write failed.

write_string : func(file : ^FileDesc, str : string) -> [i64, IoStatus]

Writes the contents of `str` to a FileDesc.

Parameters:
  file : ^FileDesc - descriptor to write to. Must be non-null and writable.
  str  : string    - source string whose bytes are written to the file.

Returns:
  [i64, IoStatus] - number of bytes written and operation status.
                   On failure returns the error propagated from
                   write_bytes.

Notes:
  - This is a convenience wrapper around write_bytes(str.to_slice()).

write : func(file : ^FileDesc, value : i8) -> [i64, IoStatus]

Writes the native in-memory byte representation of an i8 value.

Returns:
  [i64, IoStatus] - 1 and IoStatus.Ok on success, or the result propagated
                    from write_bytes on failure.

write : func(file : ^FileDesc, value : i16) -> [i64, IoStatus]

Writes the native-endian, in-memory byte representation of an i16 value.

Returns:
  [i64, IoStatus] - 2 and IoStatus.Ok on success, or the result propagated
                    from write_bytes on failure.

write : func(file : ^FileDesc, value : i32) -> [i64, IoStatus]

Writes the native-endian, in-memory byte representation of an i32 value.

Returns:
  [i64, IoStatus] - 4 and IoStatus.Ok on success, or the result propagated
                    from write_bytes on failure.

write : func(file : ^FileDesc, value : i64) -> [i64, IoStatus]

Writes the native-endian, in-memory byte representation of an i64 value.

Returns:
  [i64, IoStatus] - 8 and IoStatus.Ok on success, or the result propagated
                    from write_bytes on failure.

write : func(file : ^FileDesc, value : bool) -> [i64, IoStatus]

Writes the native in-memory byte representation of a bool value.

Returns:
  [i64, IoStatus] - sizeof(bool) and IoStatus.Ok on success, or the result
                    propagated from write_bytes on failure.

write_all_bytes : func(path : string, data : []byte) -> [i64, IoStatus]

Creates or truncates the file at `path` and writes all bytes from `data`.

Parameters:
  path : string - borrowed destination path.
  data : []byte - borrowed byte slice to write.

Returns:
  [i64, IoStatus] - bytes written and operation status. An open failure
                    returns -1. A write failure reports any completed prefix.

write_all_text : func(path : string, data : string) -> [i64, IoStatus]

Creates or truncates the file at `path` and writes all bytes from `data`.

Parameters:
  path : string - borrowed destination path.
  data : string - borrowed text to write without an added terminator.

Returns:
  [i64, IoStatus] - bytes written and operation status.

write_lines : func(path : string, lines : []string) -> [i64, IoStatus]

Creates or truncates the file at `path` and writes each string followed by
a newline byte.

Parameters:
  path  : string   - borrowed destination path.
  lines : []string - borrowed lines to write in order.

Returns:
  [i64, IoStatus] - total bytes written and operation status. The count
                    includes newline bytes and any prefix completed before
                    a write failure.

Notes:
  - Every input element receives a trailing '\n', including the last one.
  - An empty slice creates an empty file.

DeinitDirEntries : func(entries : ^containers.ArrayList<DirEntry>)

Releases a directory listing and all storage owned by it.

Parameters:
  entries : ^containers.ArrayList<DirEntry> - list returned by list_dir.

Returns:
  void

Notes:
  - Frees every entry name, every entry path, and the ArrayList backing
    buffer with the allocator stored in the list.
  - After this call, the list is deinitialized and must not be used until it
    is initialized again.
  - A null list or a list without an allocator is left unchanged.

does_path_exist : func(path : string) -> bool

Reports whether a filesystem entry exists at a path.

Parameters:
  path_value : string - borrowed filesystem path to query.

Returns:
  bool - true when the entry exists; otherwise false.

is_file : func(path_value : string) -> bool

Reports whether a path resolves to a regular file.

Parameters:
  path_value : string - borrowed filesystem path to query.

Returns:
  bool - true when metadata lookup succeeds and the entry is a regular
         file; otherwise false.

is_dir : func(path_value : string) -> bool

Reports whether a path resolves to a directory.

Parameters:
  path_value : string - borrowed filesystem path to query.

Returns:
  bool - true when metadata lookup succeeds and the entry is a directory;
         otherwise false.

create_dir_all : func(path_value : string) -> FsStatus

Creates a directory and any missing parent directories in its path.

Parameters:
  path_value : string - borrowed filesystem path to create.

Returns:
  FsStatus - FsStatus.Ok when the directory exists after the operation, or
             an error status when validation, allocation, or creation fails.

Notes:
  - Returns FsStatus.Ok when the path already names a directory.
  - Returns FsStatus.NotDirectory when the path already names another entry
    type.
  - Temporary path storage is allocated and released internally.

remove_file : func(path_value : string) -> FsStatus

Removes the filesystem entry at a path using file-removal semantics.

Parameters:
  path_value : string - borrowed filesystem path to remove.

Returns:
  FsStatus - operation status mapped from the underlying OS result.

list_dir : func(path : string) -> [containers.ArrayList<DirEntry>, FsStatus]

Lists the direct entries in a directory using the context allocator.

Parameters:
  path : string - borrowed path of the directory to list.

Returns:
  [containers.ArrayList<DirEntry>, FsStatus]
    - On success: a context-allocator-owned list and FsStatus.Ok.
    - On failure: an empty list that owns no storage and an error status.

Notes:
  - Returns FsStatus.InvalidAllocator when context.allocator is null.
  - The caller owns every DirEntry.name, every DirEntry.path, and the
    ArrayList backing buffer in a successful result.
  - Release a successful result with DeinitDirEntries.
  - Entry classification does not follow symbolic links or Windows
    directory links; link flags are preserved and is_dir remains false for
    links.
  - The special `.` and `..` entries are omitted.

list_dir : func(path_value : string, allocator : ^Allocator) -> [containers.ArrayList<DirEntry>, FsStatus]

Lists the direct entries in a directory.

Parameters:
  path_value : string     - borrowed path of the directory to list.
  allocator  : ^Allocator - allocator used for entry strings and list
                            storage. Must be non-null.

Returns:
  [containers.ArrayList<DirEntry>, FsStatus]
    - On success: an allocator-owned list and FsStatus.Ok.
    - On failure: an empty list that owns no storage and an error status.

Notes:
  - The caller owns every DirEntry.name, every DirEntry.path, and the
    ArrayList backing buffer in a successful result.
  - Release a successful result with DeinitDirEntries.
  - Entry classification does not follow symbolic links or Windows
    directory links; link flags are preserved and is_dir remains false for
    links.
  - The special `.` and `..` entries are omitted.

remove_dir_all : func(path_value : string) -> FsStatus

Recursively removes a directory tree without traversing link targets.

Parameters:
  path_value : string - borrowed path of the directory tree to remove.

Returns:
  FsStatus - FsStatus.Ok when the entry and its descendants are removed, or
             the first error status encountered.

Notes:
  - Symbolic links are unlinked with remove_file.
  - Windows directory links and junctions are removed with remove_dir.
  - Link targets are never recursively visited.
  - Temporary traversal storage is allocated and released internally.

copy_file : func(from : string, to : string) -> FsStatus

Copies the contents of a regular source file to a destination path.

Parameters:
  from : string - borrowed path of the source file.
  to   : string - borrowed path of the destination file.

Returns:
  FsStatus - FsStatus.Ok when the copy completes, FsStatus.SameFile when
             both paths identify the same file, or an error status.

Notes:
  - The source is validated before the destination is opened.
  - The destination is opened without truncation, compared against the
    source by opened-handle identity, and truncated only after the files are
    proven distinct.
  - Same spelling, symbolic-link aliases, and hard-link aliases return
    FsStatus.SameFile without changing file contents.

join_path : func(a : string, b : string, allocator : ^Allocator) -> string

Joins two path values into a newly allocated, NUL-terminated string.

Parameters:
  a         : string     - borrowed base path.
  b         : string     - borrowed path to append.
  allocator : ^Allocator - allocator used for the returned string. Must be
                           non-null.

Returns:
  string - allocator-owned joined path, or an empty string when an argument
           is invalid or allocation fails.

Notes:
  - The caller must release a non-empty result with free_string and the
    supplied allocator.
  - When exactly one input is empty, the result is an allocated copy of the
    other value. Two empty inputs return an empty string.
  - When `b` begins with a path separator, it replaces `a`.
  - Inserts `/` only when `a` does not already end with a path separator.
  - This function joins path text without normalizing it.

join_path : func(a : string, b : string) -> string

Joins two path values using the context allocator.

Parameters:
  a : string - borrowed base path.
  b : string - borrowed path to append.

Returns:
  string - context-allocator-owned joined path, or an empty string when an
           argument is invalid or allocation fails.

Notes:
  - Requires context.allocator to be non-null.
  - The caller must release a non-empty result with free_string and
    context.allocator.

join_path : func(a : string, b : string, c : string) -> string

Joins three path values using the context allocator.

Parameters:
  a : string - borrowed base path.
  b : string - borrowed second path component.
  c : string - borrowed third path component.

Returns:
  string - context-allocator-owned, NUL-terminated joined path, or an empty
           string when all inputs are empty, an input is invalid, the result
           is too large, or allocation fails.

Notes:
  - Requires context.allocator to be non-null.
  - The caller must release a non-empty result with free_string and
    the allocator used by context.allocator for this call.
  - Allocates only the returned string; no intermediate strings are created.
  - Empty components are skipped.
  - Each join inserts `/` only when the preceding path does not already
    end with a path separator.
  - A component beginning with a path separator replaces the preceding
    path.
  - This function joins path text without normalizing it.

join_path : func(a : string, b : string, c : string, allocator : ^Allocator) -> string

Joins three path values using a caller-provided allocator.

Parameters:
  a         : string     - borrowed base path.
  b         : string     - borrowed second path component.
  c         : string     - borrowed third path component.
  allocator : ^Allocator - allocator used for the returned string. Must be
                           non-null.

Returns:
  string - allocator-owned, NUL-terminated joined path, or an empty string
           when all inputs are empty, an input or allocator is invalid,
           the result is too large, or allocation fails.

Notes:
  - The caller must release a non-empty result with free_string and the
    supplied allocator.
  - Allocates only the returned string; no intermediate strings are created.
  - Empty components are skipped.
  - Each join inserts `/` only when the preceding path does not already
    end with a path separator.
  - A component beginning with a path separator replaces the preceding
    path.
  - This function joins path text without normalizing it.

parent : func(value : string, allocator : ^Allocator) -> string

Copies the parent portion of a path into a newly allocated,
NUL-terminated string.

Parameters:
  value     : string     - borrowed path to inspect.
  allocator : ^Allocator - allocator used for the returned string. Must be
                           non-null.

Returns:
  string - allocator-owned parent path, or an empty string when the path is
           empty, has no parent, the allocator is null, or allocation fails.

Notes:
  - Trailing path separators are ignored except for a root separator.
  - The caller must release a non-empty result with free_string and the
    supplied allocator.

parent : func(value : string) -> string

Copies the parent portion of a path using the context allocator.

Parameters:
  value : string - borrowed path to inspect.

Returns:
  string - context-allocator-owned parent path, or an empty string when the
           path has no parent or allocation fails.

Notes:
  - Requires context.allocator to be non-null.
  - The caller must release a non-empty result with free_string and
    context.allocator.

get_filename : func(path : string, allocator : ^Allocator) -> string

Copies the final component of a path into a newly allocated,
NUL-terminated string.

Parameters:
  path      : string     - borrowed path to inspect.
  allocator : ^Allocator - allocator used for the returned string. Must be
                           non-null.

Returns:
  string - allocator-owned final component, or an empty string when the path
           is empty, the allocator is null, or allocation fails.

Notes:
  - Trailing path separators are ignored except for a root separator.
  - The caller must release a non-empty result with free_string and the
    supplied allocator.

get_filename : func(value : string) -> string

Copies the final component of a path using the context allocator.

Parameters:
  value : string - borrowed path to inspect.

Returns:
  string - context-allocator-owned final component, or an empty string when
           the path is empty or allocation fails.

Notes:
  - Requires context.allocator to be non-null.
  - The caller must release a non-empty result with free_string and
    context.allocator.

extension : func(value : string, allocator : ^Allocator) -> string

Copies the final component's extension into a newly allocated,
NUL-terminated string.

Parameters:
  value     : string     - borrowed path to inspect.
  allocator : ^Allocator - allocator used for the returned string. Must be
                           non-null.

Returns:
  string - allocator-owned extension including its leading `.`, or an empty
           string when the path is empty, no extension exists, the allocator
           is null, or allocation fails.

Notes:
  - Trailing path separators are ignored.
  - A leading dot on the final component does not by itself count as an
    extension.
  - The caller must release a non-empty result with free_string and the
    supplied allocator.

extension : func(value : string) -> string

Copies the final component's extension using the context allocator.

Parameters:
  value : string - borrowed path to inspect.

Returns:
  string - context-allocator-owned extension including its leading `.`, or
           an empty string when no extension exists or allocation fails.

Notes:
  - Requires context.allocator to be non-null.
  - The caller must release a non-empty result with free_string and
    context.allocator.

normalize : func(value : string, allocator : ^Allocator) -> string

Normalizes path separators and components into a newly allocated,
NUL-terminated string.

Parameters:
  value     : string     - borrowed path to normalize.
  allocator : ^Allocator - allocator used for temporary storage and the
                           returned string. Must be non-null.

Returns:
  string - allocator-owned normalized path, or an empty string when an
           argument is invalid or allocation fails.

Notes:
  - Converts path separators to `/` in the result.
  - Removes empty and `.` components and resolves `..` components.
  - An absolute path cannot ascend above its root; leading `..` components
    are preserved for relative paths.
  - An empty relative result is represented as `.`.
  - The caller must release a non-empty result with free_string and the
    supplied allocator.

absolute : func(value : string, allocator : ^Allocator) -> [string, IoStatus]

Produces a normalized absolute path in newly allocated storage.

Parameters:
  value     : string     - borrowed path to resolve.
  allocator : ^Allocator - allocator used for temporary storage and the
                           returned string. Must be non-null.

Returns:
  [string, IoStatus]
    - On success: an allocator-owned absolute path and IoStatus.Ok.
    - On failure: an empty string and IoStatus.InvalidAllocator when
      `allocator` is null.
    - On failure: an empty string and IoStatus.AllocatorFailed when path
      allocation fails.
    - Errors from querying the current directory are mapped to IoStatus.

Notes:
  - Absolute input is normalized directly.
  - Relative input is joined to the current directory before normalization.
  - The caller must release a successful result with free_string and the
    supplied allocator.