API Reference

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();

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);

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);

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);

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());

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());

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());

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();

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();

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();

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);

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]);

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");

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"));