API Reference

enum ColorLevel

Ansi16
Ansi256
Ascii
TrueColor

Functions

fn clear()

Clear the screen and home the cursor.

TTY-guarded: a no-op returning normally when stdout is not a TTY, never an error.

import io from "@std/io";

io.clear();

Run in Playground

fn colorProfile(): ColorLevel

Output color tier from the environment and the TTY state.

Cheapest check first: NO_COLOR set to a non-empty value forces Ascii; otherwise COLORTERM of truecolor or 24bit gives TrueColor; TERM containing 256color gives Ansi256; TERM of "" or "dumb" gives Ascii; a TTY with any other TERM gives Ansi16, and anything else gives Ascii. A non-TTY stdout caps the result at Ansi16.

returns — the tier, cheapest check first.

import io, { ColorLevel } from "@std/io";

print(io.colorProfile() == ColorLevel.Ascii || true);

Run in Playground

fn height(): Int

Terminal height in rows.

Falls back to 24 when the size cannot be read (piped output, missing ioctl, non-TTY).

returns — rows, 24 on fallback.

import io from "@std/io";

print(io.height() > 0);

Run in Playground

fn isTTY(): Bool

Whether stdin is a terminal.

returns — true when descriptor 0 is a TTY, false for pipes and files.

import io from "@std/io";

print(io.isTTY() == true || io.isTTY() == false);

Run in Playground

fn read(): Result<String, String>

Read stdin to EOF.

returns — Ok(text) with everything read, Err(message) when stdin is not available or not readable.

import io from "@std/io";

let r = io.read();
print(r.isOk());

Run in Playground

fn readLine(prompt: String): Result<String, String>

Read one line from stdin.

Writes prompt to stdout with no newline first, reads until a newline or EOF, and strips the trailing newline (a carriage return before it goes too, so CRLF input reads cleanly). Reads one byte at a time, so a second call never loses bytes buffered past the newline.

prompt — text written to stdout with no newline, defaults to "".

returns — Ok(line) without the newline, Err(message) on EOF with no bytes read or on I/O failure.

import io from "@std/io";

let r = io.readLine("> ");
print(r.isOk());

Run in Playground

fn setRawMode(enabled: Bool): Result<Bool, String>

Toggle character-at-a-time, no-echo input on stdin.

Returns Result, not Void: Ok(true) on success, Err(message) when stdin is not a TTY or the OS call fails. Callers restore with setRawMode(false); the runtime also restores the saved mode automatically at process exit.

enabled — true to enter raw mode, false to leave it.

returns — Ok(true) after toggling, Err(message) otherwise.

import io from "@std/io";

let r = io.setRawMode(false);
print(r.isOk() || r.isErr());

Run in Playground

fn stderr(): File

Standard error as a File handle.

returns — handle whose isOpen is false when descriptor 2 is bad.

import io from "@std/io";

let err = io.stderr();
print(err.isOpen);
err.close();

Run in Playground

fn stdin(): File

Standard input as a File handle.

returns — handle whose isOpen is false when descriptor 0 is bad.

import io from "@std/io";

let inn = io.stdin();
print(inn.isOpen);
inn.close();

Run in Playground

fn stdout(): File

Standard output as a File handle.

returns — handle whose isOpen is false when descriptor 1 is bad.

import io from "@std/io";

let out = io.stdout();
print(out.isOpen);
out.close();

Run in Playground

fn width(): Int

Terminal width in columns.

Falls back to 80 when the size cannot be read (piped output, missing ioctl, non-TTY).

returns — columns, 80 on fallback.

import io from "@std/io";

print(io.width() > 0);

Run in Playground

fn write(value: Any)

Print one value with a trailing newline on stdout.

Containers render structurally behind one shared renderer: arrays as [a, b], maps as {k: v} in insertion order, class instances as Name{field: value} in declaration order, results as Ok(v) and Err(e). Nesting deeper than 3 renders as ..., and a value that contains itself renders as <cycle> instead of recursing forever. Strings print as-is, never quoted and never re-escaped. Colors follow colorProfile() when stdout is a terminal and stay out otherwise. Only fields render for class instances; methods are not listed. print forwards each of its arguments through this same renderer and joins them with spaces, so print([1, 2], "x") prints [1, 2] x.

value — value to print.

import io from "@std/io";

io.write("hello");
io.write([1, 2, 3]);

Run in Playground

fn writeError(value: Any)

Print one value with a trailing newline on stderr.

Matches write but targets descriptor 2, so error text stays separate from stdout when either side is piped. Rendering, depth cap, cycle, and color rules are the same as write.

value — value to print.

import io from "@std/io";

io.writeError("boom");

Run in Playground

fn writeRaw(bytes: ByteBuffer)

Write bytes as-is to stdout: no newline, no pretty-printing.

This is the binary door for progress bars and control sequences the caller builds itself.

Byte note: native backends emit exactly these bytes. The interpreter run console is line-oriented and terminates each flush with \n.

bytes — raw bytes to write.

import io from "@std/io";
import { ByteBuffer } from "@std/bytes";

io.writeRaw(ByteBuffer.fromString("AB"));

Run in Playground