dymokomi/luce-base
Source of release 0.41.0
#==============================================================================================
#
# 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)