@eryx/stdio Module

Standard I/O module -- read/write access to stdin, stdout, and stderr.

Provides both synchronous (blocking) and asynchronous (yielding) APIs for interacting with the process's standard streams.

Quick start

local stdio = require("@eryx/stdio")

-- Prompt the user
stdio.write("Enter your name: ")
stdio.flush()
local name = stdio.readline()
stdio.write("Hello, " .. (name or "stranger") .. "!\n")

-- Check if running in a terminal
local tty = stdio.isatty()
if tty.stdin then
	print("stdin is a terminal")
end

Summary

Functions

stdio.read(bytes: number?) → string
stdio.readSync(bytes: number?) → string
stdio.readBuffer(bytes: number?) → buffer
stdio.readBufferSync(bytes: number?) → buffer
stdio.readall(chunkSize: number?) → string
stdio.readline(options: ReadLineOptions?) → string
stdio.write(data: string | buffer) → number
stdio.writeerr(data: string | buffer) → number
stdio.flush() → ()
stdio.flusherr() → ()
stdio.writeSync(data: string | buffer) → number
stdio.writeerrSync(data: string | buffer) → number
stdio.flushSync() → ()
stdio.flusherrSync() → ()
stdio.isatty() → TtyInfo
stdio.terminalSize() → TerminalSize?
stdio.setRawMode(enabled: boolean) → boolean
stdio.isRawMode() → boolean

API Reference

Functions

stdio.read

⚠ Yields

Yields the current coroutine until data is available on stdin, then returns up to bytes bytes (default 4096). Returns "" on EOF. Passing 0 also returns "". Only one read may be pending at a time.

stdio.read(bytes: number?) → string

stdio.readSync

Reads up to bytes bytes from stdin (default 4096). Returns "" on EOF. Passing 0 also returns "".

stdio.readSync(bytes: number?) → string

stdio.readBuffer

⚠ Yields

Yields and reads from stdin as a buffer. Returns an empty buffer on EOF.

stdio.readBuffer(bytes: number?) → buffer

stdio.readBufferSync

Reads from stdin synchronously as a buffer. Returns an empty buffer on EOF.

stdio.readBufferSync(bytes: number?) → buffer

stdio.readall

Reads stdin in chunks until EOF and returns all data as one string.

stdio.readall(chunkSize: number?) → string

stdio.readline

Reads one line from stdin.

By default this reads until "\n" and strips the terminator. Use options.terminator to change the delimiter and options.keepTerminator=true to keep it.

Returns "" on EOF.

stdio.readline(options: ReadLineOptions?) → string

stdio.write

⚠ Yields

Yields, writes a string to stdout, and returns bytes written.

stdio.write(data: string | buffer) → number

stdio.writeerr

⚠ Yields

Yields, writes a string to stderr, and returns bytes written.

stdio.writeerr(data: string | buffer) → number

stdio.flush

⚠ Yields

Yields and flushes the stdout buffer.

stdio.flush() → ()

stdio.flusherr

⚠ Yields

Yields and flushes the stderr buffer.

stdio.flusherr() → ()

stdio.writeSync

Writes a string to stdout synchronously. Returns the number of bytes written.

stdio.writeSync(data: string | buffer) → number

stdio.writeerrSync

Writes a string to stderr synchronously. Returns the number of bytes written.

stdio.writeerrSync(data: string | buffer) → number

stdio.flushSync

Flushes the stdout buffer synchronously.

stdio.flushSync() → ()

stdio.flusherrSync

Flushes the stderr buffer synchronously.

stdio.flusherrSync() → ()

stdio.isatty

Returns a table indicating whether each standard stream is connected to a terminal (TTY).

stdio.isatty() → TtyInfo

stdio.terminalSize

Returns the visible terminal size for stdout, when available.

stdio.terminalSize() → TerminalSize?

stdio.setRawMode

Enables or disables terminal raw mode for stdin.

Raw mode is only available when stdin is a TTY. Returns the active raw-mode state after applying the change.

stdio.setRawMode(enabled: boolean) → boolean

stdio.isRawMode

Returns whether stdin raw mode is currently enabled.

stdio.isRawMode() → boolean

Types

TtyInfo

Result of isatty() -- indicates which streams are connected to a terminal.

type TtyInfo = { stdin: boolean, stdout: boolean, stderr: boolean }
stdin: boolean
stdout: boolean
stderr: boolean

TerminalSize
type TerminalSize = { columns: number, rows: number }
columns: number
rows: number

StandardStreamControl
type StandardStreamControl = { setBinaryMode: ((self: StandardStreamControl, enabled: boolean) → boolean), flush: ((self: StandardStreamControl) → ()) }
StandardStreamControl:setBinaryMode(enabled: boolean) → boolean

Sets whether this standard stream uses binary mode.

On Windows this controls CRT newline translation. On other platforms text and binary mode are equivalent, so this returns the requested state.

StandardStreamControl:flush() → ()

ReadLineOptions
type ReadLineOptions = { terminator: string?, keepTerminator: boolean? }
terminator: string?

Line terminator sequence to stop at. Defaults to "\n".

keepTerminator: boolean?

Whether to keep the matched terminator in the returned value. Defaults to false.