smudgy:core — Lines & buffer

Generated from smudgy v0.3.5 (smudgy-core.d.ts @ cfcea3b156f6). 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, begin: number, end?: number, options?: LineColorOptions): void;
  replaceAt(text: string, begin: number, end: number): void;
  highlightAt(begin: number, end: number, options?: LineColorOptions): void;
  removeAt(begin: number, end: number): void;
  replace(oldStr: string, newStr: string): 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.
• replaceAt — Replace the byte range [begin, end) with text.
• highlightAt — Recolor the byte range [begin, end).
• removeAt — Remove the byte range [begin, end).
• replace — Replace the first occurrence of oldStr with newStr. 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 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 — Events · smudgy:core — Automations · smudgy:core — Saved automations · smudgy:core — Panes · smudgy:widgets · Mapper · smudgy:params