Streams

Streams provide incremental I/O for HTTP, filesystem, and other modules. The modules that own the underlying data create stream objects. This page is an API reference; the scanner loop uses an application-defined process(token) callback.

Obtaining a Stream

-- From HTTP request body
local stream, err = req:stream()
if err then return nil, err end

-- From filesystem
local fs = require("fs")
local volume, err = fs.get("app:data")
if err then return nil, err end

local stream, err = volume:open("/file.txt", "r")
if err then return nil, err end

Reading

local chunk, err = stream:read(size)

Returns: string, error — nil, nil on EOF

Writing

local bytes, err = stream:write(data)

Returns: integer, error — bytes written

Seeking

local pos, err = stream:seek(whence, offset)

Returns: integer, error — new position

Flushing

local ok, err = stream:flush()

flush writes buffered data to the underlying destination.

Stream Information

local info, err = stream:stat()

Closing

local ok, err = stream:close()

close releases the stream's resources and can be called more than once.

Scanner

Create a scanner that tokenizes stream content:

local scanner, err = stream:scanner(split)

Scanner Methods

local has_more, err = scanner:scan()  -- advance to next token
local token = scanner:text()           -- current token
local err_msg = scanner:err()          -- scanner error if any

while true do
    local has_token, err = scanner:scan()
    if err then return nil, err end
    if not has_token then
        local scan_err = scanner:err()
        if scan_err then return nil, scan_err end  -- raw scanner error string
        break  -- clean EOF
    end
    process(scanner:text())
end

When scan() returns false, check scanner:err() before treating the result as EOF. Tokenization and underlying read failures are stored on the scanner and do not appear in scan()'s second return value.

Errors