vercel-labs--zerolang/docs/articles/modules/term.md

When To Use std.term

In Zerolang, use std.term when terminal code needs ANSI output sequences, hosted terminal metadata, nonblocking input reads, or key decoding for bytes already read from input.

Runnable today:

Helper	Returns	Notes
std.term.reset()	String	ANSI SGR reset.
std.term.bold()	String	ANSI SGR bold style.
std.term.dim()	String	ANSI SGR dim style.
std.term.underline()	String	ANSI SGR underline style.
std.term.inverse()	String	ANSI SGR inverse style.
std.term.fgDefault()	String	Reset foreground color.
std.term.fgBlack()	String	Black foreground color.
std.term.fgRed()	String	Red foreground color.
std.term.fgGreen()	String	Green foreground color.
std.term.fgYellow()	String	Yellow foreground color.
std.term.fgBlue()	String	Blue foreground color.
std.term.fgMagenta()	String	Magenta foreground color.
std.term.fgCyan()	String	Cyan foreground color.
std.term.fgWhite()	String	White foreground color.
std.term.bgDefault()	String	Reset background color.
std.term.bgBlack()	String	Black background color.
std.term.bgRed()	String	Red background color.
std.term.bgGreen()	String	Green background color.
std.term.bgYellow()	String	Yellow background color.
std.term.bgBlue()	String	Blue background color.
std.term.bgMagenta()	String	Magenta background color.
std.term.bgCyan()	String	Cyan background color.
std.term.bgWhite()	String	White background color.
std.term.clearScreen()	String	Clear the full terminal screen.
std.term.clearScreenDown()	String	Clear from the cursor through the end of the screen.
std.term.clearScreenUp()	String	Clear from the cursor through the start of the screen.
std.term.clearLine()	String	Clear the current terminal line.
std.term.clearLineRight()	String	Clear from the cursor through the end of the line.
std.term.clearLineLeft()	String	Clear from the cursor through the start of the line.
std.term.cursorHome()	String	Move the cursor to row 1, column 1.
std.term.cursorTo(buffer, row, column)	Maybe<Span<u8>>	Writes a 1-based ANSI cursor-position sequence into caller storage.
std.term.cursorUp(buffer, count)	Maybe<Span<u8>>	Writes an ANSI cursor-up sequence into caller storage; count 0 writes an empty span.
std.term.cursorDown(buffer, count)	Maybe<Span<u8>>	Writes an ANSI cursor-down sequence into caller storage; count 0 writes an empty span.
std.term.cursorRight(buffer, count)	Maybe<Span<u8>>	Writes an ANSI cursor-right sequence into caller storage; count 0 writes an empty span.
std.term.cursorLeft(buffer, count)	Maybe<Span<u8>>	Writes an ANSI cursor-left sequence into caller storage; count 0 writes an empty span.
std.term.saveCursor()	String	Save the current cursor position.
std.term.restoreCursor()	String	Restore the saved cursor position.
std.term.hideCursor()	String	Hide the terminal cursor.
std.term.showCursor()	String	Show the terminal cursor.
std.term.enterAltScreen()	String	Enter the alternate screen buffer.
std.term.leaveAltScreen()	String	Leave the alternate screen buffer.
std.term.enterBracketedPaste()	String	Enable bracketed paste markers in supporting terminals.
std.term.leaveBracketedPaste()	String	Disable bracketed paste markers in supporting terminals.
std.term.enterMouseCapture()	String	Enable SGR mouse tracking and drag/wheel capture in supporting terminals.
std.term.leaveMouseCapture()	String	Disable the SGR mouse tracking modes enabled by enterMouseCapture.
std.term.keyNone()	u32	Sentinel returned for incomplete or unsupported key bytes.
std.term.keyEscape()	u32	Escape key code.
std.term.keyEnter()	u32	Enter key code for \r or \n.
std.term.keyTab()	u32	Tab key code.
std.term.keyBackspace()	u32	Backspace key code for 0x7f or 0x08.
std.term.keyCtrlA()	u32	Ctrl-A key code.
std.term.keyCtrlC()	u32	Ctrl-C key code.
std.term.keyCtrlD()	u32	Ctrl-D key code.
std.term.keyCtrlE()	u32	Ctrl-E key code.
std.term.keyCtrlK()	u32	Ctrl-K key code.
std.term.keyCtrlL()	u32	Ctrl-L key code.
std.term.keyCtrlN()	u32	Ctrl-N key code.
std.term.keyCtrlP()	u32	Ctrl-P key code.
std.term.keyCtrlR()	u32	Ctrl-R key code.
std.term.keyCtrlU()	u32	Ctrl-U key code.
std.term.keyCtrlW()	u32	Ctrl-W key code.
std.term.keyArrowUp()	u32	Up-arrow key code above the Unicode scalar range.
std.term.keyArrowDown()	u32	Down-arrow key code above the Unicode scalar range.
std.term.keyArrowRight()	u32	Right-arrow key code above the Unicode scalar range.
std.term.keyArrowLeft()	u32	Left-arrow key code above the Unicode scalar range.
std.term.keyDelete()	u32	Delete key code above the Unicode scalar range.
std.term.keyHome()	u32	Home key code above the Unicode scalar range.
std.term.keyEnd()	u32	End key code above the Unicode scalar range.
std.term.keyPageUp()	u32	Page Up key code above the Unicode scalar range.
std.term.keyPageDown()	u32	Page Down key code above the Unicode scalar range.
std.term.keyInsert()	u32	Insert key code above the Unicode scalar range.
std.term.keyShiftTab()	u32	Shift-Tab key code above the Unicode scalar range.
std.term.keyF1()	u32	F1 key code above the Unicode scalar range.
std.term.keyF2()	u32	F2 key code above the Unicode scalar range.
std.term.keyF3()	u32	F3 key code above the Unicode scalar range.
std.term.keyF4()	u32	F4 key code above the Unicode scalar range.
std.term.keyF5()	u32	F5 key code above the Unicode scalar range.
std.term.keyF6()	u32	F6 key code above the Unicode scalar range.
std.term.keyF7()	u32	F7 key code above the Unicode scalar range.
std.term.keyF8()	u32	F8 key code above the Unicode scalar range.
std.term.keyF9()	u32	F9 key code above the Unicode scalar range.
std.term.keyF10()	u32	F10 key code above the Unicode scalar range.
std.term.keyF11()	u32	F11 key code above the Unicode scalar range.
std.term.keyF12()	u32	F12 key code above the Unicode scalar range.
std.term.keyPasteStart()	u32	Bracketed paste start marker code above the Unicode scalar range.
std.term.keyPasteEnd()	u32	Bracketed paste end marker code above the Unicode scalar range.
std.term.keyCode(bytes)	u32	Decodes one key from caller-provided bytes, returning Unicode scalar values for printable UTF-8 and named constants for control keys.
std.term.keyByteLen(bytes)	usize	Returns the decoded key width in bytes, or 0 for incomplete or unsupported input.
std.term.stdinIsTty()	Bool	Reports whether standard input is attached to a terminal.
std.term.stdoutIsTty()	Bool	Reports whether standard output is attached to a terminal.
std.term.widthOr(fallback)	usize	Returns terminal columns, or fallback when unavailable.
std.term.heightOr(fallback)	usize	Returns terminal rows, or fallback when unavailable.
std.term.enterRawMode()	Bool	Puts standard input into raw, nonblocking terminal mode when supported.
std.term.leaveRawMode()	Bool	Restores the terminal mode saved by enterRawMode().
std.term.readInput(buffer)	Maybe<usize>	Fills the caller buffer with currently available stdin bytes without blocking; returns null when no bytes are available or the input source is unsupported.

Metadata labels:

• effects: ANSI/key helpers are pure; TTY/size helpers read hosted terminal metadata; raw-mode helpers update the hosted terminal; readInput reads from hosted stdin
• allocation behavior: no allocation
• target support: ANSI/key helpers are target-neutral; TTY/size/raw-mode/input helpers require hosted runtime support
• error behavior: ANSI/key helpers are infallible; hosted helpers return fallbacks, false, or null when unavailable
• ownership notes: ANSI sequences are borrowed static byte views
• example: conformance/native/pass/std-term-ansi.graph

Example:

pub fn main(world: World) -> Void raises {
    check world.out.write(std.term.enterAltScreen())
    check world.out.write(std.term.enterMouseCapture())
    check world.out.write(std.term.clearScreen())
    check world.out.write(std.term.cursorHome())
    var cursor: [24]u8 = [0_u8; 24]
    let top: Maybe<Span<u8>> = std.term.cursorTo(cursor, 1_usize, 1_usize)
    if top.has {
        check world.out.write(top.value)
    }
    check world.out.write(std.term.bold())
    check world.out.write(std.term.fgCyan())
    let width: usize = std.term.widthOr(80_usize)
    let height: usize = std.term.heightOr(24_usize)
    let raw: Bool = std.term.enterRawMode()
    var input: [16]u8 = [0_u8; 16]
    let pending: Maybe<usize> = std.term.readInput(input)
    if pending.has {
        let bytes: Span<u8> = std.mem.prefix(input, pending.value)
        let key: u32 = std.term.keyCode(bytes)
        if key == std.term.keyCtrlC() {
            check world.out.write("cancel")
        }
    }
    check world.out.write("ready")
    if raw {
        let restored: Bool = std.term.leaveRawMode()
        if !restored {
            return
        }
    }
    check world.out.write(std.term.reset())
    check world.out.write(std.term.leaveMouseCapture())
    check world.out.write(std.term.leaveAltScreen())
}

Key decoding is target-neutral: it parses bytes the caller already has. TTY and size helpers are hosted metadata calls and return caller fallbacks when a terminal size is unavailable. Raw mode is a hosted terminal capability: call leaveRawMode() before returning to normal line-oriented terminal input. readInput() is nonblocking; in raw mode it can be polled by interactive programs, and on noninteractive stdin it returns available piped bytes when the host exposes them.