nish:io

Text and bytes to stdout and stderr with nothing added, and the panic that ends a program on an unmet invariant.

import {
  panic,
  write,
  writeBytes,
  writeError,
} from "nish:io";
import { write, writeError, writeBytes, panic } from "nish:io";

write("progress: ");
write("done\n");
const bytes: u8[] = [0x89, 0x50, 0x4e, 0x47];
if (writeBytes(bytes, 0, bytes.length) < 0) {
  panic("stdout refused the bytes");
}

Each export is the global of the same name, renamed: the call checks through the same rule and emits the same IR as the global spelling, and an imported name cannot be shadowed by a user function. None needs a capability; each has the write effect.

A wasm32 build has no stdout to reach and refuses writeBytes. A writeBytes range outside bytes panics, as dst.set does, rather than answering an error.

Bytes out, and the string route

A native string is {len, bytes}, never validated as UTF-8, and write and writeError send its len bytes as they are. That route is native only: under the prelude a byte above 127 that String.fromBytes made becomes two. writeBytes sends a u8[] as it is on every host, and is the route for bytes that are not text.

Rules: https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#builtin-modules-nish and https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#console

Functions

panic

message and a newline to stderr, then exit 1: the same ending an out-of-range index has. A statement and a terminator, as process.exit is, so a non-void function may end with it; never is how tsc spells that. It is how a program ends on an unmet invariant, since there is no throw.

const panic: (message: string) => never
messagestringrequired

The text written before the program exits.

returnsnever

Never: the program has ended.

write

s to stdout with no trailing newline and no conversion; a statement.

const write: (s: string) => void
sstringrequired

The text, a string only, sent as its bytes.

writeBytes

bytes[off .. off + len) to stdout, every byte as it is: the one way to send bytes that are not text, a byte of 0x80 or above or a zero byte included. A loop of write(2) sends them all, retried on an interrupted call. A pipe whose reader has gone raises SIGPIPE natively, as it does for write, where Node answers -32 (EPIPE). The shape is netWrite's with the descriptor fixed at 1; under Node the bytes go to fs.writeSync(1, …).

const writeBytes: (
  bytes: readonly u8[],
  off: i32,
  len: i32,
) => i32
bytesreadonly u8[]required

The bytes, a u8[] (NL2268 otherwise), readonly or not.

offi32required

The first byte to send. The range is checked once after the arguments are evaluated: 0 <= off, 0 <= len and off + len <= bytes.length, else it panics with slice out of range: [off, off+len) of length n and exits 1 (a slice site).

leni32required

How many bytes to send.

returnsi32

len, or a negative errno when the stream refuses them (-9, EBADF, on a closed descriptor); never a panic for a refused write.

writeError

s to stderr with no trailing newline and no conversion; a statement.

const writeError: (s: string) => void
sstringrequired

The text, a string only, sent as its bytes.