smudgy:core — Lines & buffer

Generated from smudgy v0.4.0 (smudgy-core.d.ts @ 3c804cdb8fa3). Index: scriptref.

Read and edit the text on screen: the line a trigger is processing right now (line), recently printed lines (buffer), colors and styling, and alias capture control.

export const line: Line;

The line a trigger is processing. Only meaningful inside a trigger handler.

export const buffer: Buffer;

This session's recent-lines buffer.

export interface Line {
  insert(
    text: string | StyledText,
    begin: number,
    end?: number,
    options?: LineColorOptions,
  ): void;
  replaceAt(text: string | StyledText, begin: number, end: number): void;
  highlightAt(begin: number, end: number, options?: LineColorOptions): void;
  removeAt(begin: number, end: number): void;
  replace(oldStr: string, newStr: string | StyledText): boolean;
  highlight(str: string, options?: LineColorOptions): boolean;
  remove(str: string): boolean;
  gag(): void;
  redirect(pane: Pane | string): void;
  copy(pane: Pane | string): void;
  readonly text: string;
  readonly styles: StyleSpan[] | undefined;
  readonly number: number;
}

A line of output you can read and edit. Inside a trigger, line is the line being processed right now; buffer.line(n) reaches an already-printed line by number. The handle remembers which line it points at; methods never take a line number.

The text-search methods (replace, highlight, remove) find their target by string; the *At forms take byte offsets (e.g. from styles).

• insert — Insert text at byte offset begin (replacing up to end if given), with optional colors. Styled text keeps its own colors and links; options then supplies the colors its unstyled parts get.
• replaceAt — Replace the byte range [begin, end) with text. Styled text keeps its own colors and links; its unstyled parts blend into the surrounding style.
• highlightAt — Recolor the byte range [begin, end).
• removeAt — Remove the byte range [begin, end).
• replace — Replace the first occurrence of oldStr with newStr (plain or styled; the search side is always plain text). Returns true if it was found.
• highlight — Recolor the first occurrence of str. Returns true if it was found.
• remove — Remove the first occurrence of str. Returns true if it was found.
• gag — Hide this line: it never reaches the screen. Current-line only (a no-op on a buffer line).
• redirect — Take the current line out of the main view and deliver it to pane instead. Styling is kept and later edits still apply; if called repeatedly, the last call wins. Current-line only (a no-op on a buffer line). A Pane handle from another session throws.
• copy — Deliver the current line to pane as well as the main view. Current-line only (a no-op on a buffer line).
• text — The line's text ("" for a buffer line outside the recent-lines window).
• styles — The line's style runs (undefined for a buffer line outside the window).
• number — The line's number (the current line reports the number it is about to be assigned).

export interface Buffer {
  line(lineNumber: number): Line;
}

Already-printed lines, looked up by number (only roughly the most recent 1000 are reachable).

• line — A handle to the already-printed line lineNumber.

export function capture(value: boolean): void;

From an alias handler: controls whether the command you typed (the one that matched) still goes to the MUD. By default an alias replaces your command: the typed line is captured, and the script sends something in its place. Call capture(false) to let the original line through. This is useful for scripts that watch what is typed but don't want to change it, or for aliases that only sometimes want to replace the command.

capture(true) forces a line to be captured, even if a previously or subsequently alias calls capture(false).

No effect in a trigger handler: incoming lines are always shown. Use line.gag() for similar behavior there.

export const style: StyleBuilder;

Builds StyledText for echo and the line-editing methods (see StyleBuilder).

export function link(command: string): StyleTag;
 
export function link(onClick: (click: LinkClick) => void): StyleTag;

Makes text clickable. Pass a command, and clicking the text sends it exactly as if you typed it into the clicked window's session. Pass a function instead, and clicking runs it with the modifier keys that were held:

echo`You see an exit ${link("north")`to the north`}.`;
echo`${link((click) => send(click.shift ? "open north" : "north"))`north`}`;

Links are underlined over a faint wash of the text's own color, so they read as links whatever the text's colors are. Style the text freely — the affordance keeps up:

line.replace("north", link("north")`${style.cyan`north`}`);

A command link works forever, even on old lines. A function link lives with the script that made it: after a script reload the text remains but clicking it does nothing, and only the most recent function links are kept, so a very old one can expire early. Prefer command links for anything long-lived.

export interface StyledText {
  readonly __smudgyStyled: true;
}

A piece of styled text, built with style or link. Accepted everywhere plain text is: echo (and a session's or pane's echo), and a line's insert, replaceAt, and replace. Fragments nest: interpolate one inside another and the inner text keeps its own styling, inheriting anything it didn't set from the fragment around it.

• __smudgyStyled — Marks a value as styled text. Fragments come from the style tag; this property just keeps other values from being mistaken for one.

export interface StyleBuilder extends StyleTag {
  (options: LineColorOptions): StyleBuilder;
  fg(color: Color): StyleBuilder;
  bg(color: Color): StyleBuilder;
  readonly black: StyleBuilder;
  readonly red: StyleBuilder;
  readonly green: StyleBuilder;
  readonly yellow: StyleBuilder;
  readonly blue: StyleBuilder;
  readonly magenta: StyleBuilder;
  readonly cyan: StyleBuilder;
  readonly white: StyleBuilder;
  readonly default: StyleBuilder;
  readonly echo: StyleBuilder;
  readonly output: StyleBuilder;
  readonly warn: StyleBuilder;
  readonly bgBlack: StyleBuilder;
  readonly bgRed: StyleBuilder;
  readonly bgGreen: StyleBuilder;
  readonly bgYellow: StyleBuilder;
  readonly bgBlue: StyleBuilder;
  readonly bgMagenta: StyleBuilder;
  readonly bgCyan: StyleBuilder;
  readonly bgWhite: StyleBuilder;
}

Builds styled text. Use it as a template tag, optionally picking colors first. Each step is itself a tag, so all of these work:

echo`A ${style.red`red`} word and ${style.blue.bgYellow`a loud one`}.`;
echo(style.fg({ r: 255, g: 128, b: 0 })`exact orange`);
echo(style({ fg: "cyan", bg: "black" })`both at once`);

Color names mean what they mean everywhere else (see Color): the ANSI names are the bright variant, the theme roles (default, echo, output, warn) follow the color scheme, and fg/bg accept any Color form, including { color, bold: false } for the dimmer shade. Text a fragment leaves unstyled behaves like plain text: the usual echo color when echoed, the surrounding style when spliced into a line.

• (call) — Both colors at once, in the same shape highlight takes.

export interface StyleTag {
  (text: TemplateStringsArray, ...values: unknown[]): StyledText;
}

A template tag producing StyledText. Interpolated fragments keep their styling; any other value becomes plain text, exactly as it would in an ordinary template string.

export interface LinkClick {
  shift: boolean;
  ctrl: boolean;
  alt: boolean;
}

Modifier keys held when a link was clicked.

export type Color =
| string
| { r: number; g: number; b: number }
| { color: string; bold: boolean };

A color accepted by the line-styling APIs. One of:

• an ANSI color name ("black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", meaning the bright variant), or a theme role: "default", "echo", "output", "warn"
• { r, g, b } with each component 0-255, for an exact color
• { color, bold }: an ANSI color name plus an explicit bright/bold flag (bold: false selects the normal, dimmer variant)

export interface StyleSpan {
  begin: number;
  end: number;
  fg: Color;
  bg: Color;
}

One styled run read back from a line. begin/end are byte offsets into the line's text (not character counts; multi-byte characters span several bytes).

export interface LineColorOptions {
  fg?: Color;
  bg?: Color;
}

Foreground and/or background color for a line write.

Script API reference · smudgy:core — Sessions & output · smudgy:core — Shared state & events · GMCP · smudgy:core — Automations · smudgy:core — Saved automations · smudgy:core — Panes · smudgy:widgets · Mapper · smudgy:params