smudgy:core — Saved automations

Generated from smudgy v0.3.5 (smudgy-core.d.ts @ cfcea3b156f6). Index: scriptref.

Create, edit, and delete the saved aliases/triggers/hotkeys (the ones shown in the automations window) from a script, via userAutomations. Saved automations run outside any sandbox, so a sandboxed package can never access them: writing one would let the package run code outside its sandbox. For the automations scripts create with the create* functions, see automations.

export const userAutomations: UserAutomations;

Manage the saved automations (see UserAutomations).

export interface UserAutomations {
  aliases: SavedAutomationRegistry<SavedAlias, SavedAliasHandle>;
  triggers: SavedAutomationRegistry<SavedTrigger, SavedTriggerHandle>;
  hotkeys: SavedAutomationRegistry<SavedHotkey, SavedHotkeyHandle>;
}

Create and edit the saved automations (the aliases, triggers, and hotkeys shown in the automations window), as opposed to the ones scripts create with createAlias/createTrigger/createHotkey. One SavedAutomationRegistry per kind.

Not available to sandboxed packages: saved automations run outside any sandbox, so writing one would let a package run code outside its own.

export interface SavedAutomationRegistry<Def, Handle> {
  save(name: string, def: Def): Handle;
  get(name: string): Handle | undefined;
  list(): string[];
  exists(name: string): boolean;
  delete(name: string): boolean;
}

Manage one kind of saved automation. save creates or replaces and returns a handle; get returns a handle to an existing name; list/exists inspect; delete removes. Every write is saved to disk, takes effect in this session, and reloads the server's other sessions.

export interface SavedAutomationHandle<Def> {
  readonly name: string;
  def(): Def;
  refresh(): boolean;
  update(patch: Partial<Def>): boolean;
  delete(): boolean;
}

A handle to one saved automation, returned by a registry's save/get. Reads are a snapshot: def() returns the definition as last read, and refresh() re-reads it from disk. update() and delete() write to disk and reload the server's other sessions.

• name — The automation's name (its key in the saved set).
• def — The saved definition as last read into this handle.
• refresh — Re-read the definition from disk. Returns false if the automation no longer exists.
• update — Save a partial change: patch's fields are merged onto the current saved definition and written back.
• delete — Remove the saved automation.

export interface SavedAlias {
  pattern: string;
  script?: string;
  enabled?: boolean;
  language?: ScriptLang;
  package?: string;
}

A saved alias, as stored in aliases.json and shown in the automations window.

• pattern — The regex matched against what you type.
• script — The body: a command template, or code when language is "js"/"ts".
• enabled — Defaults to true.
• language — Defaults to "plaintext".
• package — Optional folder grouping in the automations window.

export interface SavedTrigger {
  patterns?: string[];
  rawPatterns?: string[];
  antiPatterns?: string[];
  script?: string;
  enabled?: boolean;
  prompt?: boolean;
  language?: ScriptLang;
  package?: string;
}

A saved trigger, as stored in triggers.json and shown in the automations window.

• patterns — Regexes matched against each incoming line's displayed text.
• rawPatterns — Regexes matched against the raw incoming line, before ANSI color codes are stripped. Use these to match on colors.
• antiPatterns — Vetoes: if any of these match, the trigger does not fire.
• enabled — Defaults to true.
• prompt — Also test prompts, not just complete lines. Defaults to false.
• language — Defaults to "plaintext".

export interface SavedHotkey {
  key: string;
  modifiers?: string[];
  script?: string;
  enabled?: boolean;
  language?: ScriptLang;
  package?: string;
}

A saved hotkey, as stored in hotkeys.json and shown in the automations window.

• key — The main key (e.g. "A", "F1", "Space").
• modifiers — Modifier keys held with it (e.g. ["Control", "Shift"]).
• enabled — Defaults to true.
• language — Defaults to "plaintext".

export type SavedAliasHandle = SavedAutomationHandle<SavedAlias>;

export type SavedTriggerHandle = SavedAutomationHandle<SavedTrigger>;

export type SavedHotkeyHandle = SavedAutomationHandle<SavedHotkey>;

export type ScriptLang = "plaintext" | "js" | "ts";

How a saved automation's script body runs: "js"/"ts" execute it as code; "plaintext" (the default) sends it as a literal command template.

Script API reference · smudgy:core — Sessions & output · smudgy:core — Lines & buffer · smudgy:core — Events · smudgy:core — Automations · smudgy:core — Panes · smudgy:widgets · Mapper · smudgy:params