tecs.io#

Input, output, and cooperative network transport.

A Stream describes binary storage without keeping a cursor. A Reader and Writer are the caller-owned directional endpoints opened from it. Strings, buffers, borrowed bytes, paths, and handles all use that one descriptor contract.

A Lua FILE is also a basic reader and writer. transfer accepts files directly and uses readInto or writeFrom accelerators when an endpoint provides them. Transform constructors take ownership of either a Tecs endpoint or a file and close it with the wrapper.

Readers, writers, transforms, and whole-source operations return their result directly. A memory operation completes inline. An unresolved file, socket, or process operation suspends a normal system and resumes at the call; the same call blocks its caller outside a world update. They return nil and a reason when an endpoint cannot be opened, read, written, flushed, or closed:

tecs.scoped(
    "read save",
    function(scope: tecs.Scope)
        local save <const> = scope:own(
            tecs.io.newFileStream("save.bin")
        )
        local bytes <const> = assert(save:transferToBuffer())
        scope:own(bytes)

        print(bytes:length())
    end
)

TCP is an ordered byte stream: one write may take several reads to receive, several writes may arrive in one read, and message framing belongs to the caller. UDP preserves one send as one datagram, but the network may lose, duplicate, or reorder it. General immutable URIs live under tecs.io.URI; HTTP and HTTPS live under tecs.io.http; the MCP debug server lives under tecs.io.mcp.

Hot TCP loops can reuse a Buffer. TCPSocket:readInto lets the native socket fill its FFI allocation directly, and TCPSocket:writeFrom queues a buffer range without constructing an intermediate Lua string. UDPSocket:receiveInto is the datagram form: it fills a reused buffer, reports its sender through sourceHost and sourcePort, and allocates no packet, address, or payload string. UDPSocket:source builds an owned address from the recorded sender when a reply needs one. Buffer:view retains an immutable zero-copy snapshot. writeView on sockets, writers, and writable streams consumes that retained range directly, while ByteView:newStream gives it replayable stream behavior without copying payload bytes.

Transform readers and writers compose those endpoints without materializing a whole source. newInflateReader, newBase64DecodeReader, newHexDecodeReader, and newTranscodeReader pull transformed bytes as their consumer asks. The corresponding deflate, encode, and transcode writers push transformed chunks toward a destination and finish format trailers or partial character state on close. Each wrapper owns the endpoint it wraps. Memory endpoints lend source pointers and reserve destination ranges directly; other endpoints reuse pooled chunks, so a warmed transfer allocates no intermediate payload storage.

Ownership is explicit at construction boundaries. A stream over a buffer or Lua file handle borrows that resource and never closes it. A stream over a byte view retains its own immutable view. Transform readers and writers take ownership of the endpoint they wrap and close it with themselves. Opening a buffer or byte-view reader retains an immutable snapshot that outlives later closure; opening a buffer writer borrows the mutable buffer, clears its logical length, and requires it to remain open through the writer's close.

Network operations return their values directly. Inside a system, resolution, connection, acceptance, socket reads, and datagram receives transparently suspend only while the requested operation cannot make progress:

world:addSystem({
    name = "game.ReceiveCommand",
    phase = tecs.ecs.phases.Update,
    run = function()
        tecs.scoped(
            "serve client",
            function(scope)
                local client <const> = scope:own(
                    assert(listener:accept())
                )
                local command <const> = assert(client:read())
                applyCommand(command)
            end
        )
    end,
})

The Application owns progress; there is no public pump to drive. Resolution, connection, reads, acceptance, sends, and receives all block appropriately for their context. A call never changes into a WouldBlock result merely because it ran outside a system. The explicit wait methods remain timeout and readiness checks rather than a second transfer API.

One endpoint permits one suspended readiness operation at a time. Do not park both read and drain on one TCP socket, both accept and wait on one listener, or both receive and wait on one UDP socket. Use one owner to serialize operations on an endpoint; a second overlapping wait fails at that call instead of replacing the first waiter.

The ready path performs the native operation immediately. Only a native WouldBlock arms a one-shot watch in the process-wide mio reactor. The reactor never calls Lua; the Application drains its tokens on the main thread and the scheduler resumes the same system. Socket writes finish when their bounded local queue accepts the bytes; drain is the explicit transport delivery boundary.

Every address, TCP socket, listener, UDP socket, and UDP packet owns a resource. Close it explicitly. A GC finalizer releases an abandoned network handle as a last resort, but cannot report a close error. Closing is idempotent; using a closed value returns a failure.

Naming tecs.io loads none of its children. Reading files, http, mcp, Path, Process, URI, or watcher loads only that child.

Declares the directional binary interfaces published by tecs.io.

This module is the cycle-safe home of Reader, Writer, and the stream descriptor interfaces. It is not a second public namespace: tecs.io re-exports the contracts, while resource modules require them without requiring their public parent.

Module contents#

Submodules#

Constructors#

Types#

Functions#

Constructors#

tecs.io.newBase64DecodeReader Static#

Creates a reader that incrementally decodes RFC 4648 Base64 text.

The reader owns source and retains at most one undecoded quantum between source reads.

function tecs.io.newBase64DecodeReader(
    source: types.Reader | FILE
): types.Reader

Arguments#

Returns#

Examples#

tecs.scoped(
    "decode base64",
    function(scope: tecs.Scope)
        local reader <const> = scope:own(
            tecs.io.newBase64DecodeReader(
                tecs.io.newStringReader("c25hcHNob3QgYnl0ZXM=")
            )
        )
        local decoded <const>, reason = reader:read(1024)

        assert(decoded, reason)
        assert(decoded == "snapshot bytes")
    end
)

tecs.io.newBase64EncodeWriter Static#

Creates a writer that incrementally encodes bytes as RFC 4648 Base64.

The writer owns destination. close emits padding for the final partial quantum before closing the destination.

function tecs.io.newBase64EncodeWriter(
    destination: types.Writer | FILE
): types.Writer

Arguments#

Returns#

Examples#

tecs.scoped(
    "encode base64",
    function(scope: tecs.Scope)
        local encoded <const> = scope:own(tecs.io.newBuffer())
        local writer <const> = scope:own(
            tecs.io.newBase64EncodeWriter(encoded:newWriter())
        )

        assert(writer:write("snapshot bytes"))
        assert(writer:close())
        assert(encoded:getString() == "c25hcHNob3QgYnl0ZXM=")
    end
)

tecs.io.newBuffer Static#

Creates an owned growable byte buffer.

function tecs.io.newBuffer(initial: integer | string): IOBuffer

Arguments#

Returns#

Examples#

local bytes <const> = tecs.io.newBuffer("save data")
print(bytes:length())

bytes:close()

tecs.io.newByteReader Static#

Creates a reader over borrowed FFI memory.

The reader never frees or modifies the allocation. The caller keeps its owner reachable and the bytes unchanged until the reader closes.

function tecs.io.newByteReader(
    pointer: loader.CValue, length: integer
): types.Reader

Arguments#

Returns#

Examples#

local ffi <const> = require("ffi")

local bytes <const> = "borrowed bytes"
local pointer <const> = ffi.cast("const uint8_t *", bytes)
local reader <const> = tecs.io.newByteReader(pointer as any, #bytes)

assert(reader:read(1024) == bytes)

reader:close()

tecs.io.newByteStream Static#

Creates a replayable read-only stream over borrowed FFI bytes.

Closing the stream or its readers never frees the allocation.

function tecs.io.newByteStream(
    pointer: loader.CValue, length: integer, contentType: string
): types.ReadableStream

Arguments#

Returns#

Examples#

local ffi <const> = require("ffi")

local bytes <const> = "borrowed bytes"
local pointer <const> = ffi.cast("const uint8_t *", bytes)
local source <const> = tecs.io.newByteStream(pointer as any, #bytes)
print(source:readAll())

source:close()

tecs.io.newDeflateWriter Static#

Creates a writer that incrementally deflates bytes into a destination.

The writer owns destination. flush emits a synchronization point without ending the compressed stream, and close emits its trailer before closing the destination.

function tecs.io.newDeflateWriter(
    destination: types.Writer | FILE,
    options: types.DeflateWriterOptions
): types.Writer

Arguments#

Returns#

Examples#

tecs.scoped(
    "deflate save",
    function(scope: tecs.Scope)
        local compressed <const> = scope:own(tecs.io.newBuffer())
        local writer <const> = scope:own(
            tecs.io.newDeflateWriter(compressed:newWriter())
        )

        assert(writer:write("snapshot "))
        assert(writer:write("bytes"))
        assert(writer:close())
        assert(compressed:length() > 0)
    end
)

tecs.io.newEmptyStream Static#

Creates a replayable readable empty stream.

function tecs.io.newEmptyStream(
    contentType: string
): types.ReadableStream

Arguments#

Returns#

Examples#

local source <const> = tecs.io.newEmptyStream(
    "application/octet-stream"
)
print(source:readAll())

source:close()

tecs.io.newFileStream Static#

Creates a replayable file stream.

Readers open the current path through tecs.io.files; writers replace it. A descriptor keeps no open file between endpoints. HTTP uploads on the SDL storage backend reopen the path directly on the native HTTP lane and stream it without retaining the complete file in Lua.

function tecs.io.newFileStream(
    path: string | Path, contentType: string
): types.ReadWriteStream

Arguments#

Returns#

Examples#

local path <const> = tecs.io.Path.new("save.bin")
local save <const> = tecs.io.newFileStream(
    path, "application/octet-stream"
)

assert(save:writeAll("save data"))
print(save:readAll())

save:close()

tecs.io.newHandleStream Static#

Creates a one-shot stream over a borrowed Lua file handle.

The first reader or writer claims its current cursor. Closing the stream or endpoint does not close the caller's handle.

function tecs.io.newHandleStream(
    handle: FILE, length: integer, contentType: string
): types.ReadWriteStream

Arguments#

Returns#

Examples#

local handle <const> = assert(io.open("save.bin", "rb"))
local source <const> = tecs.io.newHandleStream(handle)
print(source:readAll())

source:close()
handle:close()

tecs.io.newHexDecodeReader Static#

Creates a reader that incrementally decodes hexadecimal text.

The reader owns source and carries one unmatched nibble across source reads.

function tecs.io.newHexDecodeReader(
    source: types.Reader | FILE
): types.Reader

Arguments#

Returns#

Examples#

tecs.scoped(
    "decode hexadecimal",
    function(scope: tecs.Scope)
        local reader <const> = scope:own(
            tecs.io.newHexDecodeReader(
                tecs.io.newStringReader("73617665")
            )
        )
        local decoded <const>, reason = reader:read(1024)

        assert(decoded, reason)
        assert(decoded == "save")
    end
)

tecs.io.newHexEncodeWriter Static#

Creates a writer that incrementally encodes bytes as lowercase hexadecimal text.

The writer owns destination and forwards each encoded chunk without retaining input bytes.

function tecs.io.newHexEncodeWriter(
    destination: types.Writer | FILE
): types.Writer

Arguments#

Returns#

Examples#

tecs.scoped(
    "encode hexadecimal",
    function(scope: tecs.Scope)
        local encoded <const> = scope:own(tecs.io.newBuffer())
        local writer <const> = scope:own(
            tecs.io.newHexEncodeWriter(encoded:newWriter())
        )

        assert(writer:write("save"))
        assert(writer:close())
        assert(encoded:getString() == "73617665")
    end
)

tecs.io.newInflateReader Static#

Creates a reader that incrementally inflates a compressed source.

The reader owns source and closes it when the wrapper closes. Reads retain only bounded compressed and decompressed chunks. A raw stream has no zlib header, trailer, or checksum.

function tecs.io.newInflateReader(
    source: types.Reader | FILE, options: types.InflateReaderOptions
): types.Reader

Arguments#

Returns#

Examples#

tecs.scoped(
    "inflate save",
    function(scope: tecs.Scope)
        local compressed <const> = scope:own(tecs.io.newBuffer())
        local restored <const> = scope:own(tecs.io.newBuffer())
        local compressor <const> = scope:own(
            tecs.io.newDeflateWriter(compressed:newWriter())
        )

        assert(compressor:write("snapshot bytes"))
        assert(compressor:close())

        local reader <const> = scope:own(
            tecs.io.newInflateReader(compressed:newReader())
        )
        local sink <const> = scope:own(restored:newWriter())
        local count <const>, reason = tecs.io.transfer(reader, sink)

        assert(count, reason)
        assert(restored:getString() == "snapshot bytes")
    end
)

tecs.io.newStringReader Static#

Creates a reader over an immutable Lua string.

The reader retains bytes without copying it. Closing the reader drops that retained reference; there is no separate resource to close.

function tecs.io.newStringReader(bytes: string): types.Reader

Arguments#

Returns#

Examples#

local reader <const> = tecs.io.newStringReader("snapshot bytes")

assert(reader:read(1024) == "snapshot bytes")

reader:close()

tecs.io.newStringStream Static#

Creates a replayable read-only string stream.

The stream retains the immutable string without copying it.

function tecs.io.newStringStream(
    bytes: string, contentType: string
): types.ReadableStream

Arguments#

Returns#

Examples#

local source <const> = tecs.io.newStringStream("hello", "text/plain")
print(source:readAll())

source:close()

tecs.io.newTranscodeReader Static#

Creates a reader that incrementally converts character encodings.

The reader owns source. It preserves conversion state and carries an incomplete multibyte character across source reads.

function tecs.io.newTranscodeReader(
    source: types.Reader | FILE,
    fromEncoding: string,
    toEncoding: string
): types.Reader

Arguments#

Returns#

Examples#

tecs.scoped(
    "transcode input",
    function(scope: tecs.Scope)
        local reader <const> = scope:own(
            tecs.io.newTranscodeReader(
                tecs.io.newStringReader("A\0\233\0"),
                "UTF-16LE",
                "UTF-8"
            )
        )
        local utf8 <const>, reason = reader:read(1024)

        assert(utf8, reason)
        assert(utf8 == "A\195\169")
    end
)

tecs.io.newTranscodeWriter Static#

Creates a writer that incrementally converts character encodings.

The writer owns destination. It preserves conversion state and carries an incomplete multibyte character across writes; close rejects a truncated final character and emits any target shift state.

function tecs.io.newTranscodeWriter(
    destination: types.Writer | FILE,
    fromEncoding: string,
    toEncoding: string
): types.Writer

Arguments#

Returns#

Examples#

tecs.scoped(
    "transcode output",
    function(scope: tecs.Scope)
        local utf16 <const> = scope:own(tecs.io.newBuffer())
        local writer <const> = scope:own(
            tecs.io.newTranscodeWriter(
                utf16:newWriter(), "UTF-8", "UTF-16LE"
            )
        )

        assert(writer:write("A\195"))
        assert(writer:write("\169"))
        assert(writer:close())
        assert(utf16:getString() == "A\0\233\0")
    end
)

Types#

tecs.io.Address record#

An Address owns one resolved network address. Closing it releases the address and remains safe to repeat.

record tecs.io.Address is Closeable
    host: string
    text: string

    close: function(self): boolean, string
    isClosed: function(self): boolean
end

Interfaces#

tecs.io.Address.host field#

Read-only. Networking sets host at resolution or peer lookup. It contains the requested hostname or numeric peer address.

tecs.io.Address.host: string

tecs.io.Address.text field#

Read-only. Networking sets text to the printable numeric address when it creates the object.

tecs.io.Address.text: string

tecs.io.Address:close Instance#

function tecs.io.Address.close(self): boolean, string

Arguments

Returns

tecs.io.Address:isClosed Instance#

Returns whether close has released this address.

function tecs.io.Address.isClosed(self): boolean

Arguments

Returns

tecs.io.Buffer interface#

A Buffer is owned growable FFI-backed byte storage.

interface tecs.io.Buffer is Closeable
    interface WriteRange is Closeable
        capacity: function(self): integer
        commit: function(self, used: integer)
        getFFIPointer: function(self): loader.BytePointer
    end

    capacity: function(self): integer
    clear: function(self)
    ensureCapacity: function(self, minimum: integer)
    getFFIPointer: function(self): loader.BytePointer
    getString: function(self, offset: integer, count: integer): string
    isReleased: function(self): boolean
    length: function(self): integer
    newReader: function(self): Reader
    newStream: function(self, contentType: string): ReadWriteStream
    newWriter: function(self): Writer
    reserveRange: function(
        self, offset: integer, minimum: integer
    ): WriteRange
    resize: function(self, length: integer)
    setString: function(self, bytes: string, offset: integer)
    view: function(self, offset: integer, count: integer): ByteView
end

Interfaces#

tecs.io.Buffer.WriteRange interface#

An exclusive, zero-copy writable range reserved from a Buffer. Closing abandons the range without changing the buffer's logical length.

interface tecs.io.Buffer.WriteRange is Closeable
    capacity: function(self): integer
    commit: function(self, used: integer)
    getFFIPointer: function(self): loader.BytePointer
end

Interfaces

tecs.io.Buffer.WriteRange:capacity Instance

Returns the maximum byte count the native writer may fill.

function tecs.io.Buffer.WriteRange.capacity(self): integer

Arguments

Returns

tecs.io.Buffer.WriteRange:commit Instance

Commits bytes written through the borrowed pointer.

The call closes the range. A gap before the committed bytes is zero-filled.

function tecs.io.Buffer.WriteRange.commit(self, used: integer)

Arguments

Returns

None.

tecs.io.Buffer.WriteRange:getFFIPointer Instance

Borrows the reserved range's writable address.

function tecs.io.Buffer.WriteRange.getFFIPointer(
    self
): loader.BytePointer

Arguments

Returns

tecs.io.Buffer:capacity Instance#

Returns the allocated byte capacity.

function tecs.io.Buffer.capacity(self): integer

Arguments

Returns

Examples#

local bytes <const> = tecs.io.newBuffer("data")

assert(bytes:capacity() >= bytes:length())

bytes:close()

tecs.io.Buffer:clear Instance#

Removes every logical byte without releasing the allocation.

function tecs.io.Buffer.clear(self)

Arguments

Returns

None.

Examples#

local bytes <const> = tecs.io.newBuffer("reusable")
local capacity <const> = bytes:capacity()
bytes:clear()

assert(bytes:length() == 0)
assert(bytes:capacity() == capacity)

bytes:close()

tecs.io.Buffer:ensureCapacity Instance#

Ensures at least minimum bytes fit without another allocation.

Growth is geometric. A call at or below the current capacity leaves pointers returned by getFFIPointer valid.

function tecs.io.Buffer.ensureCapacity(self, minimum: integer)

Arguments

Returns

None.

Examples#

local bytes <const> = tecs.io.newBuffer("data")
bytes:ensureCapacity(1024)

assert(bytes:capacity() >= 1024)
assert(bytes:length() == 4)

bytes:close()

tecs.io.Buffer:getFFIPointer Instance#

Borrows the address of the first byte.

The pointer is invalid after capacity grows or close runs. The buffer must remain reachable for the whole native call that uses it.

function tecs.io.Buffer.getFFIPointer(self): loader.BytePointer

Arguments

Returns

Examples#

local bytes <const> = tecs.io.newBuffer("native bytes")
local pointer <const> = bytes:getFFIPointer()
print(pointer)

bytes:close()

tecs.io.Buffer:getString Instance#

Copies a range into a Lua string.

function tecs.io.Buffer.getString(
    self, offset: integer, count: integer
): string

Arguments

Returns

Examples#

local bytes <const> = tecs.io.newBuffer("headerpayload")
print(bytes:getString(6, 7))

bytes:close()

tecs.io.Buffer:isReleased Instance#

Returns whether close has given up the allocation.

function tecs.io.Buffer.isReleased(self): boolean

Arguments

Returns

Examples#

local bytes <const> = tecs.io.newBuffer()

assert(not bytes:isReleased())

bytes:close()

assert(bytes:isReleased())

tecs.io.Buffer:length Instance#

Returns the number of logical bytes.

function tecs.io.Buffer.length(self): integer

Arguments

Returns

Examples#

local bytes <const> = tecs.io.newBuffer("four")
print(bytes:length())

bytes:close()

tecs.io.Buffer:newReader Instance#

Opens a reader over an immutable snapshot of the current bytes.

The reader retains the allocation independently, so the caller may close or mutate the buffer after this call. Its cursor starts at zero.

function tecs.io.Buffer.newReader(self): Reader

Arguments

Returns

Examples#

local bytes <const> = tecs.io.newBuffer("snapshot")
local reader <const> = bytes:newReader()

bytes:close()

assert(reader:read(1024) == "snapshot")

reader:close()

tecs.io.Buffer:newStream Instance#

Creates a stream sharing this buffer.

The stream borrows this buffer. The caller keeps it open while using the stream and closes it separately. Closing the stream never closes the buffer. transferToBuffer returns this same borrowed object without transferring ownership.

function tecs.io.Buffer.newStream(
    self, contentType: string
): ReadWriteStream

Arguments

Returns

Examples#

local bytes <const> = tecs.io.newBuffer("old")
local stream <const> = bytes:newStream()

assert(stream:writeAll("new"))
print(bytes:getString())

stream:close()
bytes:close()

tecs.io.Buffer:newWriter Instance#

Opens a writer that replaces the current bytes.

The call clears the logical length while retaining capacity. The caller keeps the buffer open until the writer closes.

function tecs.io.Buffer.newWriter(self): Writer

Arguments

Returns

Examples#

local bytes <const> = tecs.io.newBuffer("old")
local writer <const> = bytes:newWriter()

assert(writer:write("new"))
assert(writer:close())
assert(bytes:getString() == "new")

bytes:close()

tecs.io.Buffer:reserveRange Instance#

Reserves an exclusive range for a native writer without an intermediate string.

The buffer detaches from retained views before exposing mutable storage.

function tecs.io.Buffer.reserveRange(
    self, offset: integer, minimum: integer
): WriteRange

Arguments

Returns

tecs.io.Buffer:resize Instance#

Changes the logical length.

Expansion fills every newly visible byte with zero. Shrinking keeps the allocation for reuse.

function tecs.io.Buffer.resize(self, length: integer)

Arguments

Returns

None.

Examples#

local bytes <const> = tecs.io.newBuffer("data")
bytes:resize(6)

assert(bytes:getString() == "data\0\0")
bytes:resize(2)

assert(bytes:getString() == "da")

bytes:close()

tecs.io.Buffer:setString Instance#

Copies a Lua string into the buffer.

The write extends the logical length as needed. A gap between the old end and offset is zero-filled.

function tecs.io.Buffer.setString(self, bytes: string, offset: integer)

Arguments

Returns

None.

Examples#

local bytes <const> = tecs.io.newBuffer("abcdefgh")
bytes:setString("XY", 3)

assert(bytes:getString() == "abcXYfgh")
bytes:setString("!", 10)

assert(bytes:getString(8, 3) == "\0\0!")

bytes:close()

tecs.io.Buffer:view Instance#

Returns a zero-copy immutable snapshot of a byte range.

function tecs.io.Buffer.view(
    self, offset: integer, count: integer
): ByteView

Arguments

Returns

tecs.io.ByteView interface#

A ByteView retains an immutable zero-copy range from a buffer.

interface tecs.io.ByteView is Closeable
    getFFIPointer: function(self): loader.BytePointer
    getString: function(self): string
    isReleased: function(self): boolean
    length: function(self): integer
    newReader: function(self): Reader
    newStream: function(self, contentType: string): ReadableStream
    view: function(self, offset: integer, count: integer): ByteView
end

Interfaces#

tecs.io.ByteView:getFFIPointer Instance#

Borrows the retained range's read-only address.

LuaJIT FFI cannot enforce constness. Writing through a cast pointer is unsafe and breaks the snapshot guarantee.

function tecs.io.ByteView.getFFIPointer(self): loader.BytePointer

Arguments

Returns

tecs.io.ByteView:getString Instance#

Copies the retained range into a Lua string.

function tecs.io.ByteView.getString(self): string

Arguments

Returns

tecs.io.ByteView:isReleased Instance#

Returns whether the view has released its retained allocation.

function tecs.io.ByteView.isReleased(self): boolean

Arguments

Returns

tecs.io.ByteView:length Instance#

Returns the retained range's byte length.

function tecs.io.ByteView.length(self): integer

Arguments

Returns

tecs.io.ByteView:newReader Instance#

Opens a reader over this immutable range.

The reader retains the allocation independently, so the caller may close this view immediately after the call. Its cursor starts at zero.

function tecs.io.ByteView.newReader(self): Reader

Arguments

Returns

Examples#

local bytes <const> = tecs.io.newBuffer("headerpayload")
local payload <const> = bytes:view(6)
local reader <const> = payload:newReader()

payload:close()
bytes:close()

assert(reader:read(1024) == "payload")

reader:close()

tecs.io.ByteView:newStream Instance#

Creates a replayable read-only stream retaining this view.

The stream retains its own view, so the caller may close this view immediately after construction. Closing the stream closes its retained view after already-open readers close theirs.

function tecs.io.ByteView.newStream(
    self, contentType: string
): ReadableStream

Arguments

Returns

Examples#

local bytes <const> = tecs.io.newBuffer("headerpayload")
local payload <const> = bytes:view(6)
local source <const> = payload:newStream("application/octet-stream")

payload:close()
bytes:close()

assert(source:readAll() == "payload")

source:close()

tecs.io.ByteView:view Instance#

Retains a zero-copy subrange.

function tecs.io.ByteView.view(
    self, offset: integer, count: integer
): ByteView

Arguments

Returns

tecs.io.DeflateWriterOptions record#

Options control an incremental deflate writer.

record tecs.io.DeflateWriterOptions
    raw: boolean
    level: integer
end

tecs.io.DeflateWriterOptions.raw field#

Caller-writable. Selects raw DEFLATE when true and zlib framing when false or omitted.

tecs.io.DeflateWriterOptions.raw: boolean

tecs.io.DeflateWriterOptions.level field#

Caller-writable. Sets zlib's compression level from minus one through nine or uses its default when omitted.

tecs.io.DeflateWriterOptions.level: integer

tecs.io.InflateReaderOptions record#

Options control an incremental inflate reader.

record tecs.io.InflateReaderOptions
    raw: boolean
    maxBytes: integer
end

tecs.io.InflateReaderOptions.raw field#

Caller-writable. Selects raw DEFLATE when true and zlib framing when false or omitted.

tecs.io.InflateReaderOptions.raw: boolean

tecs.io.InflateReaderOptions.maxBytes field#

Caller-writable. Sets the hard decompressed-byte ceiling or uses 268,435,456 bytes when omitted.

tecs.io.InflateReaderOptions.maxBytes: integer

tecs.io.ReadableStream interface#

A ReadableStream opens readers and supplies whole-source transfers.

interface tecs.io.ReadableStream is Stream, Closeable
    discard: function(self): integer, string
    newReader: function(self): Reader, string
    readAll: function(self, maxBytes: integer): string, string
    transferTo: function(
        self, destination: WritableStream
    ): integer, string
    transferToBuffer: function(self, maxBytes: integer): Buffer, string
    transferToFile: function(self, path: string): integer, string
end

Interfaces#

tecs.io.ReadableStream:discard Instance#

Reads and discards every source byte.

The operation opens, consumes, and closes one reader. On a non-replayable stream, this claims its one endpoint.

function tecs.io.ReadableStream.discard(self): integer, string

Arguments

Returns

Examples#

local source <const> = tecs.io.newFileStream("download.tmp")
local count <const> = source:discard()
print(count)

source:close()

tecs.io.ReadableStream:newReader Instance#

Opens a reader with a new cursor.

function tecs.io.ReadableStream.newReader(self): Reader, string

Arguments

Returns

Examples#

local source <const> = tecs.io.newStringStream("data")
local reader <const> = assert(source:newReader())
print(reader:read(4))

reader:close()
source:close()

tecs.io.ReadableStream:readAll Instance#

Reads the complete source into a Lua string.

The operation opens, consumes, and closes one reader. On a non-replayable stream, this claims its one endpoint.

function tecs.io.ReadableStream.readAll(
    self, maxBytes: integer
): string, string

Arguments

Returns

Examples#

local source <const> = tecs.io.newStringStream("data")
local bytes <const> = source:readAll(1024)
print(bytes)

source:close()

tecs.io.ReadableStream:transferTo Instance#

Copies every source byte into destination.

The operation opens and closes one source reader and one destination writer. Either non-replayable descriptor is claimed by the call.

function tecs.io.ReadableStream.transferTo(
    self, destination: WritableStream
): integer, string

Arguments

Returns

Examples#

local source <const> = tecs.io.newStringStream("data")
local output <const> = tecs.io.newBuffer()
local destination <const> = output:newStream()
local count <const> = source:transferTo(destination)
print(count, output:getString())

source:close()
destination:close()
output:close()

tecs.io.ReadableStream:transferToBuffer Instance#

Transfers the complete source into an owned buffer.

A stream created by Buffer:newStream returns that same borrowed buffer without copying and does not transfer ownership. Other streams return a newly allocated buffer owned by the caller. The operation opens, consumes, and closes one reader when it must copy. On a non-replayable stream, this claims its one endpoint.

function tecs.io.ReadableStream.transferToBuffer(
    self, maxBytes: integer
): Buffer, string

Arguments

Returns

Examples#

local source <const> = tecs.io.newFileStream("save.bin")
local bytes <const> = source:transferToBuffer(1024 * 1024)
print(bytes:length())

bytes:close()
source:close()

tecs.io.ReadableStream:transferToFile Instance#

Copies every source byte into a file.

The operation opens and closes one source reader. On a non-replayable stream, this claims its one endpoint.

function tecs.io.ReadableStream.transferToFile(
    self, path: string
): integer, string

Arguments

Returns

Examples#

local source <const> = tecs.io.newStringStream("save data")
local count <const> = source:transferToFile("save.bin")
print(count)

source:close()

tecs.io.Reader interface#

A Reader supplies bytes in order and releases its owned state on close.

interface tecs.io.Reader is Closeable
    read: function(self, count: integer): string, string
    readInto: function(
        self, destination: Buffer, offset: integer, count: integer
    ): integer, string
end

Interfaces#

tecs.io.Reader:read Instance#

Caller-writable. Supplies the operation that reads the next bytes.

function tecs.io.Reader.read(self, count: integer): string, string

Arguments

Returns

Examples#

local source <const> = tecs.io.newStringStream("abcdefgh")
local reader <const> = assert(source:newReader())
local chunk <const>, reason = reader:read(4)

assert(chunk, reason)
print(chunk)

reader:close()
source:close()

tecs.io.Reader:readInto Instance#

Reads bytes directly into a buffer and advances the cursor.

The operation grows the destination as needed and preserves bytes outside the written range. It returns zero after the source is exhausted.

function tecs.io.Reader.readInto(
    self, destination: Buffer, offset: integer, count: integer
): integer, string

Arguments

Returns

Examples#

local source <const> = tecs.io.newStringStream("abcdefgh")
local reader <const> = assert(source:newReader())
local bytes <const> = tecs.io.newBuffer("prefix:")
local count <const>, reason = reader:readInto(bytes, bytes:length(), 4)

assert(count, reason)
print(bytes:getString())

reader:close()
source:close()
bytes:close()

tecs.io.ReadWriteStream interface#

A ReadWriteStream supports both directional interfaces.

interface tecs.io.ReadWriteStream is ReadableStream, Stream, Closeable, WritableStream
end

Interfaces#

tecs.io.Seekable interface#

Seekable supplies random-access cursor operations shared by readers and writers.

interface tecs.io.Seekable
    enum Origin
        "current"
        "end"
        "start"
    end

    seek: function(
        self, origin: Origin, offset: integer
    ): integer, string
    size: function(self): integer, string
    tell: function(self): integer, string
end

tecs.io.Seekable.Origin enum#

Origin selects the reference point for a seek.

enum tecs.io.Seekable.Origin
    "current"
    "end"
    "start"
end

tecs.io.Seekable:seek Instance#

Repositions the cursor and returns its new absolute position.

"start" measures offset from byte zero, "current" measures it from the cursor, and "end" measures it from the current byte length. The offset defaults to zero and may be negative for the latter two origins. A result before byte zero or past the current end fails without moving the cursor.

function tecs.io.Seekable.seek(
    self, origin: Origin, offset: integer
): integer, string

Arguments

Returns

tecs.io.Seekable:size Instance#

Returns the storage's current byte length.

The result includes every write already accepted even when buffered bytes have not reached the underlying destination yet.

function tecs.io.Seekable.size(self): integer, string

Arguments

Returns

tecs.io.Seekable:tell Instance#

Returns the current zero-based cursor position.

function tecs.io.Seekable.tell(self): integer, string

Arguments

Returns

tecs.io.SeekableReader interface#

A SeekableReader supplies bytes through a repositionable cursor.

interface tecs.io.SeekableReader is Reader, Closeable, Seekable
end

Interfaces#

tecs.io.SeekableWriter interface#

A SeekableWriter patches a destination through a repositionable cursor.

interface tecs.io.SeekableWriter is Writer, Closeable, Seekable
end

Interfaces#

tecs.io.Stream interface#

A Stream describes binary storage without retaining a cursor.

interface tecs.io.Stream is Closeable
    contentLength: function(self): integer | nil
    contentType: function(self): string | nil
    isReadable: function(self): boolean
    isReplayable: function(self): boolean
    isWritable: function(self): boolean
    withMetadata: function<T is Stream>(
        self,
        contentType: string,
        contentLength: integer,
        isReplayable: boolean
    ): T
end

Interfaces#

tecs.io.Stream:contentLength Instance#

Returns the byte length when it is known.

function tecs.io.Stream.contentLength(self): integer | nil

Arguments

Returns

Examples#

local source <const> = tecs.io.newStringStream("four")
local length <const> = source:contentLength()
if length ~= nil then
    print(length)
end

source:close()

tecs.io.Stream:contentType Instance#

Returns the media type supplied at construction.

function tecs.io.Stream.contentType(self): string | nil

Arguments

Returns

Examples#

local source <const> = tecs.io.newStringStream("{}", "application/json")
print(source:contentType())

source:close()

tecs.io.Stream:isReadable Instance#

Returns whether the descriptor can open a reader.

function tecs.io.Stream.isReadable(self): boolean

Arguments

Returns

Examples#

local source <const> = tecs.io.newStringStream("data")
print(source:isReadable())

source:close()

tecs.io.Stream:isReplayable Instance#

Returns whether each reader starts from the beginning.

True means the descriptor can open independent readers repeatedly. False means opening an endpoint or running a whole-source operation may claim the descriptor permanently; newReader reports when it can no longer open one.

function tecs.io.Stream.isReplayable(self): boolean

Arguments

Returns

Examples#

local source <const> = tecs.io.newStringStream("data")
print(source:isReplayable())

source:close()

tecs.io.Stream:isWritable Instance#

Returns whether the descriptor can open a writer.

function tecs.io.Stream.isWritable(self): boolean

Arguments

Returns

Examples#

local save <const> = tecs.io.newFileStream("save.bin")
print(save:isWritable())

save:close()

tecs.io.Stream:withMetadata Instance#

Creates a lazy view that overrides this descriptor's metadata.

Nil inherits each value from the receiver. The view retains and delegates to the receiver, preserves its static and runtime directional interface, and closes the receiver when it closes. If every supplied value already matches, this returns the receiver.

function tecs.io.Stream.withMetadata<T is Stream>(
    self,
    contentType: string,
    contentLength: integer,
    isReplayable: boolean
): T