Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-base

Source of release 0.42.0

0.42.0 / src / std / io.lucb

#==============================================================================================
#
#   io - Byte streams
#
#   DESCRIPTION:
#       Readers and writers over bytes, buffered wrappers, the standard output and error
#       streams, the user's home directory, and the stream error codes.
#
#==============================================================================================

import c
import core
import memory
import platform
import os
import strings
extern func fwrite(data: const void*, size: usize, count: usize, stream: void*) -> usize
extern func fflush(stream: void*?) -> i32
extern func flockfile(stream: void*)
extern func funlockfile(stream: void*)
extern func win_lock_file as "_lock_file"(stream: void*)
extern func win_unlock_file as "_unlock_file"(stream: void*)
extern func posix_read as "read"(descriptor: i32, buffer: void*, count: usize) -> isize
extern func windows_read as "_read"(descriptor: i32, buffer: void*, count: u32) -> i32

func c_read(descriptor: i32, buffer: void*, count: usize) -> isize:
    if platform.windows:
        return (isize)windows_read(descriptor, buffer, (u32)(count if count < 2147483647 else 2147483647))
    return posix_read(descriptor, buffer, count)

## A borrowed byte source. A successful read returns at most the buffer length;
## zero for a nonempty buffer means EOF. Empty reads return zero without consuming
## input. Errors are distinct from EOF. The implementing object owns its lifetime.
pub interface Reader:
    func read(buffer: u8[]) -> usize!

## A borrowed byte sink (§14.4). A write may accept fewer bytes than supplied;
## callers needing the whole payload use `write_all`. Empty writes return zero.
## A failure may follow earlier successful writes; the view never owns the sink.
pub interface Writer:
    func write(data: const u8[]) -> usize!

## A stream ended before the expected bytes arrived.
pub let unexpected_eof: ErrorCode = ErrorCode.package(14)
## A stream made no progress and cannot continue.
pub let no_progress: ErrorCode = ErrorCode.package(15)
## A read or write was asked for an invalid count.
pub let invalid_count: ErrorCode = ErrorCode.package(16)
## A read or write was given an invalid buffer.
pub let invalid_buffer: ErrorCode = ErrorCode.package(17)

## Fill `buffer`, or fail at EOF or on a source error. Optional `transferred` is
## reset to zero on entry and updated after each successful read, including before
## a later failure. It must not overlap the buffer or the source's state. No call
## reaches the source for an empty buffer. The source remains borrowed and open.
pub func read_exact(source: Reader, buffer: u8[], transferred: usize*? = none) -> !:
    var done: usize = 0
    if let progress = transferred:
        *progress = 0
    while done < buffer.length:
        let count = try source.read(buffer[done..])
        if count > buffer.length - done:
            error(invalid_count, "the reader returned more bytes than requested")
        if count == 0:
            error(unexpected_eof, "the reader ended before the buffer was filled")
        done += count
        if let progress = transferred:
            *progress = done

## Write all bytes, preserving confirmed progress through `transferred` on error.
## The progress pointer must not overlap the data or sink state. A zero-length
## successful write on nonempty input fails with `no_progress` instead of spinning.
## This does not flush or close the borrowed sink. Empty input makes no sink call.
pub func write_all(destination: Writer, data: const u8[], transferred: usize*? = none) -> !:
    var done: usize = 0
    if let progress = transferred:
        *progress = 0
    while done < data.length:
        let count = try destination.write(data[done..])
        if count > data.length - done:
            error(invalid_count, "the writer returned more bytes than supplied")
        if count == 0:
            error(no_progress, "the writer accepted no bytes")
        done += count
        if let progress = transferred:
            *progress = done

## Copy at most `limit` bytes through caller-owned scratch storage; stop earlier
## at EOF. Reads never consume beyond the limit. `transferred` counts confirmed
## destination bytes, including before a failure; source consumption can be ahead
## by one scratch buffer if writing fails. Scratch and progress must not overlap
## either endpoint's state/data or each other. No allocation, flush or close occurs.
pub func copy_limit(source: Reader, destination: Writer, buffer: u8[], limit: usize, transferred: usize*? = none) -> usize!:
    var done: usize = 0
    if let progress = transferred:
        *progress = 0
    if limit == 0:
        return 0
    if buffer.length == 0:
        error(invalid_buffer, "copying requires a nonempty scratch buffer")
    while done < limit:
        let available = limit - done
        let requested = buffer.length if buffer.length < available else available
        let count = try source.read(buffer[..<requested])
        if count > requested:
            error(invalid_count, "the reader returned more bytes than requested")
        if count == 0:
            break
        var written: usize = 0
        write_all(destination, buffer[..<count], &written) catch failure:
            if let progress = transferred:
                *progress = done + written
            error(failure)
        done += written
        if let progress = transferred:
            *progress = done
    return done

## A cursor over borrowed bytes. Copying the reader copies its position, not its
## data. The backing storage must outlive the reader and every read using it.
pub struct SliceReader: Reader:
    var data: const u8[]
    var position: usize

    ## A reader over `data`.
    pub static func over(data: const u8[]) -> SliceReader:
        return SliceReader(data = data, position = 0)

    ## The number of bytes not yet read.
    pub func remaining() -> usize:
        return self.data.length - self.position

    ## Copy up to the buffer length; zero means no bytes remain (or an empty read).
    pub func read(buffer: u8[]) -> usize!:
        let left = self.remaining()
        let count = buffer.length if buffer.length < left else left
        memory.move(buffer, self.data[self.position..], count)
        self.position += count
        return count

## A writer into fixed borrowed storage. Copying it copies the cursor and aliases
## storage. Writes may be short; once full, a nonempty write fails with `full`.
pub struct SliceWriter: Writer:
    var data: u8[]
    var used: usize

    ## A writer into `data`.
    pub static func over(data: u8[]) -> SliceWriter:
        return SliceWriter(data = data, used = 0)

    ## View of confirmed written bytes, borrowed from the caller's storage.
    pub func written() -> const u8[]:
        return self.data[..<self.used]

    ## Write `data`; the number of bytes written.
    pub func write(data: const u8[]) -> usize!:
        if data.length == 0:
            return 0
        let left = self.data.length - self.used
        if left == 0:
            error(full, "the destination buffer is full")
        let count = data.length if data.length < left else left
        memory.move(self.data[self.used..], data, count)
        self.used += count
        return count

## Buffered input over a borrowed source and nonempty caller-owned storage. Both
## must outlive this adapter. Storage must not overlap source state or read buffers.
## Construct with `over`; serialize access and do not use copied adapters together.
## Reads may prefetch beyond the requested bytes. The adapter never closes its source.
pub struct BufferedReader: Reader:
    var source: Reader
    var storage: u8[]
    var position: usize
    var used: usize

    ## A buffered reader over `source`, using `storage`.
    pub static func over(source: Reader, storage: u8[]) -> BufferedReader!:
        if storage.length == 0:
            error(invalid_buffer, "buffered input requires nonempty storage")
        return BufferedReader(source = source, storage = storage, position = 0, used = 0)

    ## Unread bytes already fetched. No source operation occurs.
    pub func buffered() -> usize:
        return self.used - self.position

    ## Return buffered bytes first, otherwise perform one source read. Empty reads
    ## do not call the source. EOF is not cached, allowing a growing source to resume.
    pub func read(buffer: u8[]) -> usize!:
        if buffer.length == 0:
            return 0
        if self.position == self.used:
            let count = try self.source.read(self.storage)
            if count > self.storage.length:
                error(invalid_count, "the reader returned more bytes than requested")
            self.position = 0
            self.used = count
        let available = self.buffered()
        let count = buffer.length if buffer.length < available else available
        memory.copy(buffer, self.storage[self.position..], count)
        self.position += count
        return count

## Buffered output over a borrowed sink and nonempty caller-owned storage. Both
## must outlive this adapter; storage must not overlap sink state or write input.
## Construct with `over`; serialize access and do not use copied adapters together.
## Explicitly flush before discarding the adapter. There is no implicit flush/close.
pub struct BufferedWriter: Writer:
    var destination: Writer
    var storage: u8[]
    var used: usize

    ## A buffered writer over `destination`, using `storage`.
    pub static func over(destination: Writer, storage: u8[]) -> BufferedWriter!:
        if storage.length == 0:
            error(invalid_buffer, "buffered output requires nonempty storage")
        return BufferedWriter(destination = destination, storage = storage, used = 0)

    ## Bytes accepted by this adapter but not yet confirmed by the destination.
    pub func buffered() -> usize:
        return self.used

    ## Drain this buffer, preserving the unconfirmed suffix if the sink fails.
    ## Retrying does not resend bytes confirmed by earlier successful sink writes.
    ## This neither flushes downstream buffers nor requests filesystem durability.
    pub func flush() -> !:
        var written: usize = 0
        write_all(self.destination, self.storage[..<self.used], &written) catch failure:
            self.used -= written
            memory.move(self.storage, self.storage[written..], self.used)
            error(failure)
        self.used = 0

    ## Accept up to the remaining capacity. A full buffer is drained before any
    ## new input is accepted; a failure accepts none of this call's input. Empty
    ## writes do not drain the buffer. Use write_all to accept an entire payload.
    pub func write(data: const u8[]) -> usize!:
        if data.length == 0:
            return 0
        if self.used == self.storage.length:
            try self.flush()
        let available = self.storage.length - self.used
        let count = data.length if data.length < available else available
        memory.copy(self.storage[self.used..], data, count)
        self.used += count
        return count

## A compile-time source position, the value of `luce.location`.
pub struct Location:
    ## The source file of the location.
    pub var file: str
    ## The source line of the location.
    pub var line: u32
    ## The enclosing function of the location.
    pub var function: str

## The stream is closed.
pub let closed: ErrorCode = ErrorCode.package(3)
## The underlying stream operation failed.
pub let failed: ErrorCode = ErrorCode.package(24)
## A non-blocking stream has no data ready.
pub let would_block: ErrorCode = ErrorCode.package(28)

## Borrowed standard output stream. Each nonempty write uses the existing libc
## stream and flushes only that stream, making completed output visible before a
## following print. The libc stream lock serializes each write with other libc
## users; concurrent direct descriptor writes may interleave. No stream is created
## or owned here. A write/flush failure can follow partial output.
pub struct File: Writer:
    var descriptor: i32

    func stream() -> void*!:
        if self.descriptor == 1:
            return c.stdout()
        if self.descriptor == 2:
            return c.stderr()
        error(closed, "the standard output stream is unavailable")

    ## Flush this C stream, without closing it or requesting filesystem durability.
    pub func flush() -> !:
        let stream = try self.stream()
        if fflush(stream) != 0:
            error(closed, "the stream could not be flushed")

    ## Write `data`; the number of bytes written.
    pub func write(data: const u8[]) -> usize!:
        if data.length == 0:
            return 0
        let stream = try self.stream()
        lock_stream(stream)
        defer unlock_stream(stream)
        let written = fwrite(data.data, 1, data.length, stream)
        let flushed = fflush(stream)
        if written != data.length or flushed != 0:
            error(closed, "the stream refused the bytes")
        return written

func lock_stream(stream: void*):
    if platform.windows:
        win_lock_file(stream)
    else:
        flockfile(stream)

func unlock_stream(stream: void*):
    if platform.windows:
        win_unlock_file(stream)
    else:
        funlockfile(stream)

var out_file: File = File(descriptor = 1)
var err_file: File = File(descriptor = 2)

## Unbuffered input borrows descriptor zero. It retries interrupted calls, reports
## would-block separately, and never owns or closes the process's descriptor.
struct StandardInput: Reader:
    var descriptor: i32

    ## Read into `buffer`; the number of bytes read.
    pub func read(buffer: u8[]) -> usize!:
        if buffer.length == 0:
            return 0
        let requested = 1073741824 if buffer.length > 1073741824 else buffer.length
        while true:
            let count = c_read(self.descriptor, buffer.data, requested)
            if count >= 0:
                return (usize)count
            let number = c.errno()
            if number == c.interrupted:
                continue
            if number == (35 if platform.macos else 11):
                error(would_block, "standard input would block")
            if number == 9:
                error(closed, "standard input is closed")
            error(failed, "standard input could not be read")

var in_file: StandardInput = StandardInput(descriptor = 0)

## Borrowed unbuffered standard input. Reads may block; concurrent readers compete
## for bytes. Do not mix with buffered C stdin reads, which may have prefetched data.
pub func stdin() -> Reader:
    return &in_file

## The process's standard output stream.
# mark: Standard streams ======================================================================

## A writer over the process's standard output.
pub func stdout() -> Writer:
    return &out_file

## The process's standard error stream.
pub func stderr() -> Writer:
    return &err_file

## Explicitly flush C stdout, including bytes written through C interop.
pub func flush_stdout() -> !:
    try out_file.flush()

## Explicitly flush C stderr, including bytes written through C interop.
pub func flush_stderr() -> !:
    try err_file.flush()

## A fixed writer has no room left.
pub let full: ErrorCode = ErrorCode.package(4)

## The sink a formatted string offers a `Display` value (§14.4): it appends to the buffer
## the compiler is filling, and fails once that buffer is full, as `format` then does.
pub struct FormatSink: Writer:
    var buffer: core.FormatBuffer*

    ## Write `data`; the number of bytes written.
    pub func write(data: const u8[]) -> usize!:
        if core.format_put(self.buffer, data.data, data.length) != 0:
            error(full, "the buffer is full")
        return data.length

## The process's directories (§16.6): `from io import path`, then `path.user()`. Each is
## a `str` view of environment storage the system owns, or fresh storage from the current
## allocator where one has to be built.
pub struct path:
    var unused: u8

    ## The user's home directory: USERPROFILE on Windows, HOME on POSIX.
    pub static func user() -> str!:
        let home = os.env("USERPROFILE" if platform.windows else "HOME") else error(io_path_failed, "no home directory")
        return home

    ## The current user's home directory.
    pub static func home() -> str!:
        return try path.user()

    ## Where temporary files go: `$TMPDIR`, else `/tmp`.
    pub static func temp() -> str:
        if platform.windows:
            if let dir = os.env("TEMP"):
                if dir.length > 0: return dir
            if let dir = os.env("TMP"):
                if dir.length > 0: return dir
            return "."
        let dir = os.env("TMPDIR") else return "/tmp"
        return dir

    ## Where configuration lives: `$XDG_CONFIG_HOME`, else `$HOME/.config`.
    pub static func config() -> str!:
        if platform.windows:
            if let set = os.env("APPDATA"):
                if set.length > 0: return set
            let home = try path.user()
            let buffer = try new u8[home.length + 17] ---
            return try strings.format(buffer, f"{home}/AppData/Roaming")
        if let set = os.env("XDG_CONFIG_HOME"):
            return set
        let home = try path.user()
        let buffer = try new u8[home.length + 9] ---
        return try strings.format(buffer, f"{home}/.config")

## The home directory could not be determined.
pub let io_path_failed: ErrorCode = ErrorCode.package(13)