@visulima/ansi
Version:
ANSI escape codes for some terminal swag.
536 lines (535 loc) • 21 kB
TypeScript
/**
* Represents an ANSI terminal status report type.
* Discriminates on {@link StatusReport.isDecReport} being `false`.
*/
interface AnsiStatusReport extends StatusReport {
readonly isDecReport: false;
}
/**
* Represents a DEC terminal status report type.
* Discriminates on {@link StatusReport.isDecReport} being `true`.
*/
interface DecStatusReport extends StatusReport {
readonly isDecReport: true;
}
/**
* Interface for terminal status reports.
*/
interface StatusReport {
readonly isDecReport: boolean;
readonly reportCode: number;
}
/**
* Creates an ANSI-type status report object.
* These reports are typically requested using `CSI Ps n`.
* @param code The numeric code for the ANSI status report.
* @returns An object implementing the {@link StatusReport} interface, marked as not DEC-specific.
* @example
* ```typescript
* import { createAnsiStatusReport, deviceStatusReport } from "@visulima/ansi";
*
* const report = createAnsiStatusReport(5);
* const sequence = deviceStatusReport(report);
* console.log(sequence);
* ```
*/
declare const createAnsiStatusReport: (code: number) => AnsiStatusReport;
/**
* Creates a DEC private status report object.
* These reports are typically requested using `CSI ? Ps n`.
* @param code The numeric code for the DEC private status report.
* @returns An object implementing the {@link StatusReport} interface, marked as DEC-specific.
* @example
* ```typescript
* import { createDecStatusReport, deviceStatusReport } from "@visulima/ansi";
*
* const report = createDecStatusReport(15);
* const sequence = deviceStatusReport(report);
* console.log(sequence);
* ```
*/
declare const createDecStatusReport: (code: number) => DecStatusReport;
/**
* Generates a Device Status Report (DSR) sequence to request terminal status information.
*
* Standard DSR: `CSI Ps n` (where `Ps` are numeric parameters separated by semicolons).
* DEC-specific DSR: `CSI ? Ps n` (where `Ps` are numeric parameters separated by semicolons).
*
* Standard (ANSI) and DEC-specific reports are grouped separately: the ANSI codes are emitted as
* `CSI a;b n` and the DEC codes as a distinct `CSI ? c;d n` sequence. When both kinds are requested
* the two sequences are concatenated, so a DEC code is never mislabeled as an ANSI code (or vice versa).
* @param reports One or more {@link StatusReport} objects indicating the statuses to request.
* If no reports are provided, an empty string is returned.
* @returns The DSR sequence string (e.g., `"\x1b[5n"`, `"\x1b[?25n"`, `"\x1b[5n\x1b[?25n"`).
* @see https://vt100.net/docs/vt510-rm/DSR.html
* @example
* ```typescript
* import { deviceStatusReport, createAnsiStatusReport, createDecStatusReport } from "@visulima/ansi";
*
* const ansiReport = createAnsiStatusReport(5);
* const decReport = createDecStatusReport(25);
*
* console.log(deviceStatusReport(ansiReport));
* console.log(deviceStatusReport(decReport));
* console.log(deviceStatusReport(ansiReport, decReport));
* ```
*/
declare const deviceStatusReport: (...reports: StatusReport[]) => string;
/**
* DSR (Device Status Report) alias.
* This function serves as a shorthand for {@link deviceStatusReport} when requesting a single status.
* @param report A single {@link StatusReport} object.
* @returns The DSR sequence string.
* @see deviceStatusReport
* @example
* ```typescript
* import { DSR, requestTerminalStatus } from "@visulima/ansi";
*
* console.log(DSR(requestTerminalStatus));
* ```
*/
declare const DSR: (report: StatusReport) => string;
/**
* ANSI escape sequence to request the cursor's current position (row and column).
* This is a common Device Status Report (DSR) request.
* Sequence: `CSI 6 n`
* The terminal typically responds with a Cursor Position Report (CPR) like `CSI Pl ; Pc R`.
* @see cursorPositionReport
* @see https://vt100.net/docs/vt510-rm/CPR.html
* @example
* ```typescript
* import { requestCursorPositionReport } from "@visulima/ansi";
*
* process.stdout.write(requestCursorPositionReport);
* ```
*/
declare const requestCursorPositionReport: string;
/**
* ANSI escape sequence to request the cursor's current position including page number (DEC private).
* This is a DEC-specific Device Status Report (DSR) request, often called DECXCPR.
* Sequence: `CSI ? 6 n`
* The terminal typically responds with an Extended Cursor Position Report (DECXCPR) like `CSI ? Pl ; Pc ; Pp R`.
* @see extendedCursorPositionReport
* @see https://vt100.net/docs/vt510-rm/DECXCPR.html
* @example
* ```typescript
* import { requestExtendedCursorPositionReport } from "@visulima/ansi";
*
* process.stdout.write(requestExtendedCursorPositionReport);
* ```
*/
declare const requestExtendedCursorPositionReport: string;
/**
* Generates the Cursor Position Report (CPR) response sequence.
* This sequence is typically sent by the terminal in response to a DSR CPR request (`CSI 6 n`).
*
* Sequence: `CSI Pl ; Pc R`
* - `Pl`: Line number (1-based).
* - `Pc`: Column number (1-based).
* @param line The line number (1-based). Values less than 1 are treated as 1.
* @param column The column number (1-based). Values less than 1 are treated as 1.
* @returns The CPR sequence string.
* @example
* ```typescript
* import { cursorPositionReport } from "@visulima/ansi";
*
* console.log(cursorPositionReport(10, 5));
* ```
*/
declare const cursorPositionReport: (line: number, column: number) => string;
/**
* Alias for {@link cursorPositionReport}.
* Provides a shorter name for the CPR response sequence generator.
* @see cursorPositionReport
* @example
* ```typescript
* import { CPR } from "@visulima/ansi";
*
* console.log(CPR(10, 5));
* ```
*/
declare const CPR: (line: number, column: number) => string;
/**
* Extended Cursor Position Report (DECXCPR) response format.
* @param line The line number (1-based).
* @param column The column number (1-based).
* @param page The page number (1-based). If 0 or less, it's omitted.
* @returns The DECXCPR sequence string.
* @example
* ```typescript
* import { extendedCursorPositionReport } from "@visulima/ansi";
*
* console.log(extendedCursorPositionReport(10, 5, 1));
*
* console.log(extendedCursorPositionReport(10, 5, 0));
* ```
*/
declare const extendedCursorPositionReport: (line: number, column: number, page: number) => string;
/**
* Alias for {@link extendedCursorPositionReport}.
* Provides a shorter name for the DECXCPR response sequence generator.
* @see extendedCursorPositionReport
* @example
* ```typescript
* import { DECXCPR } from "@visulima/ansi";
*
* console.log(DECXCPR(10, 5, 1));
* ```
*/
declare const DECXCPR: (line: number, column: number, page: number) => string;
/**
* ANSI escape sequence to request the terminal's name and version (XTVERSION).
* Sequence: `CSI > 0 q`
* The terminal typically responds with a DCS sequence: `DCS > | text ST`
* Where `text` is the terminal name and version.
* @see https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-PC-Style-Function-Keys
* @example
* ```typescript
* import { RequestNameVersion } from "@visulima/ansi";
*
* process.stdout.write(RequestNameVersion);
* ```
*/
declare const RequestNameVersion: string;
/**
* Alias for {@link RequestNameVersion}.
* @see RequestNameVersion
*/
declare const XTVERSION: string;
/**
* ANSI escape sequence to request Primary Device Attributes (DA1).
* Sequence: `CSI c` or `CSI 0 c`. Using `CSI c` as it's the more common base form.
* The terminal responds with `CSI ? Pn ; Pn ; ... c`.
* @example
* ```typescript
* import { requestPrimaryDeviceAttributes } from "@visulima/ansi";
*
* process.stdout.write(requestPrimaryDeviceAttributes);
* ```
*/
declare const requestPrimaryDeviceAttributes: string;
/**
* Alias for {@link requestPrimaryDeviceAttributes}.
*/
declare const DA1: string;
/**
* Generates the response sequence for Primary Device Attributes (DA1).
* Sequence: `CSI ? Ps ; ... c`.
* @remarks
* Common attributes include:
* - 1 132 columns
* - 2 Printer port
* - 4 Sixel
* - 6 Selective erase
* - 7 Soft character set (DRCS)
* - 8 User-defined keys (UDKs)
* - 9 National replacement character sets (NRCS) (International terminal only)
* - 12 Yugoslavian (SCS)
* - 15 Technical character set
* - 18 Windowing capability
* - 21 Horizontal scrolling
* - 23 Greek
* - 24 Turkish
* - 42 ISO Latin-2 character set
* - 44 PCTerm
* - 45 Soft key map
* - 46 ASCII emulation.
* @param attributes Numeric attribute codes.
* @returns The DA1 response sequence.
* @example
* ```typescript
* import { reportPrimaryDeviceAttributes } from "@visulima/ansi";
*
* console.log(reportPrimaryDeviceAttributes(1, 9));
* console.log(reportPrimaryDeviceAttributes(61));
* ```
*/
declare const reportPrimaryDeviceAttributes: (...attributes: number[]) => string;
/**
* ANSI escape sequence to request Secondary Device Attributes (DA2).
* Sequence: `CSI > c` or `CSI > 0 c`. Using `CSI > c` as the base.
* The terminal responds with `CSI > Pv ; Pl ; Pc c` (Version; Level; Cartridge).
* @example
* ```typescript
* import { requestSecondaryDeviceAttributes } from "@visulima/ansi";
*
* process.stdout.write(requestSecondaryDeviceAttributes);
* ```
*/
declare const requestSecondaryDeviceAttributes: string;
/**
* Alias for {@link requestSecondaryDeviceAttributes}.
*/
declare const DA2: string;
/**
* Generates the response sequence for Secondary Device Attributes (DA2).
* Sequence: `CSI > Pv ; Pl ; Pc c`
* @param version Terminal version number.
* @param level Terminal model/level number.
* @param cartridge ROM cartridge (0 for none).
* @returns The DA2 response sequence.
* @example
* ```typescript
* import { reportSecondaryDeviceAttributes } from "@visulima/ansi";
*
* console.log(reportSecondaryDeviceAttributes(0, 2, 0));
* console.log(reportSecondaryDeviceAttributes(41, 370, 0));
* ```
*/
declare const reportSecondaryDeviceAttributes: (version: number, level: number, cartridge?: number) => string;
/**
* ANSI escape sequence to request Tertiary Device Attributes (DA3).
* Sequence: `CSI = c` or `CSI = 0 c`. Using `CSI = c` as the base.
* The terminal responds with `DCS ! | unitID ST`. (DECRPTUI - Report Unit ID)
* @example
* ```typescript
* import { requestTertiaryDeviceAttributes } from "@visulima/ansi";
*
* process.stdout.write(requestTertiaryDeviceAttributes);
* ```
*/
declare const requestTertiaryDeviceAttributes: string;
/**
* Alias for {@link requestTertiaryDeviceAttributes}.
*/
declare const DA3: string;
/**
* Generates the response sequence for Tertiary Device Attributes (DA3), which is a DECRPTUI.
* Sequence: `DCS ! | unitID ST`
* @param unitID The unit ID string for the terminal.
* @returns The DA3 response sequence (DECRPTUI).
* If unitID is empty, it's arguably an invalid report, but we'll return `DCS ! | ST` to match some behaviors.
* @example
* ```typescript
* import { reportTertiaryDeviceAttributes } from "@visulima/ansi";
*
* console.log(reportTertiaryDeviceAttributes("MYTERM001"));
* console.log(reportTertiaryDeviceAttributes(""));
* ```
*/
declare const reportTertiaryDeviceAttributes: (unitID: string) => string;
/**
* ANSI escape sequence to request Primary Device Attributes (DA1) with explicit parameter 0.
* Sequence: `CSI 0 c`.
* This is an alternative form of {@link requestPrimaryDeviceAttributes}.
* @example
* ```typescript
* import { requestPrimaryDeviceAttributesParam0 } from "@visulima/ansi";
*
* process.stdout.write(requestPrimaryDeviceAttributesParam0);
* ```
*/
declare const requestPrimaryDeviceAttributesParam0: string;
/**
* ANSI escape sequence to request Secondary Device Attributes (DA2) with explicit parameter 0.
* Sequence: `CSI > 0 c`.
* This is an alternative form of {@link requestSecondaryDeviceAttributes}.
* Note: This is also what XTerm uses for `sendDeviceAttributes` with no arguments in some contexts,
* but it's different from `XTVERSION` (`CSI > 0 q`).
* @example
* ```typescript
* import { requestSecondaryDeviceAttributesParam0 } from "@visulima/ansi";
*
* process.stdout.write(requestSecondaryDeviceAttributesParam0);
* ```
*/
declare const requestSecondaryDeviceAttributesParam0: string;
/**
* ANSI escape sequence to request Tertiary Device Attributes (DA3) with explicit parameter 0.
* Sequence: `CSI = 0 c`.
* This is an alternative form of {@link requestTertiaryDeviceAttributes}.
* @example
* ```typescript
* import { requestTertiaryDeviceAttributesParam0 } from "@visulima/ansi";
*
* process.stdout.write(requestTertiaryDeviceAttributesParam0);
* ```
*/
declare const requestTertiaryDeviceAttributesParam0: string;
/**
* A {@link StatusReport} object to request the terminal's general status.
* Corresponds to DSR request `CSI 5 n`.
* The terminal is expected to respond with `CSI 0 n` (OK) or `CSI 3 n` (Failure).
* @see DSR_TerminalStatus
* @see reportTerminalOK
* @see reportTerminalNotOK
* @example
* ```typescript
* import { DSR, requestTerminalStatus } from "@visulima/ansi";
*
* const reportSequence = DSR(requestTerminalStatus);
* console.log(reportSequence);
* ```
*/
declare const requestTerminalStatus: StatusReport;
/**
* ANSI escape sequence `CSI 5 n` to request terminal status.
* This is generated using `deviceStatusReport(requestTerminalStatus)`.
* @see requestTerminalStatus
* @example
* ```typescript
* import { DSR_TerminalStatus } from "@visulima/ansi";
*
* process.stdout.write(DSR_TerminalStatus);
* ```
*/
declare const DSR_TerminalStatus: string;
/**
* ANSI escape sequence `CSI 0 n` indicating Terminal is OK (Operating Normally).
* This is a typical response to {@link DSR_TerminalStatus} (`CSI 5 n`) or `deviceStatusReport(requestTerminalStatus)`.
* @see requestTerminalStatus
* @see DSR_TerminalStatus
*/
declare const reportTerminalOK: string;
/**
* ANSI escape sequence `CSI 3 n` indicating Terminal is NOT OK (Malfunction).
* This is a typical response to {@link DSR_TerminalStatus} (`CSI 5 n`) or `deviceStatusReport(requestTerminalStatus)`.
* @see requestTerminalStatus
* @see DSR_TerminalStatus
*/
declare const reportTerminalNotOK: string;
/**
* A DEC-specific {@link StatusReport} object to request printer status.
* Corresponds to DSR request `CSI ? 15 n`.
* The terminal is expected to respond with sequences like `CSI ? 10 n` (Ready), `CSI ? 11 n` (Not Ready), or `CSI ? 13 n` (No Paper).
* @see DSR_PrinterStatusDEC
* @see reportPrinterReadyDEC
* @see reportPrinterNotReadyDEC
* @see reportPrinterNoPaperDEC
* @example
* ```typescript
* import { DSR, requestPrinterStatusDEC } from "@visulima/ansi";
*
* const reportSequence = DSR(requestPrinterStatusDEC);
* console.log(reportSequence);
* ```
*/
declare const requestPrinterStatusDEC: StatusReport;
/**
* ANSI escape sequence `CSI ? 15 n` to request DEC-specific printer status.
* This is generated using `deviceStatusReport(requestPrinterStatusDEC)`.
* @see requestPrinterStatusDEC
* @example
* ```typescript
* import { DSR_PrinterStatusDEC } from "@visulima/ansi";
*
* process.stdout.write(DSR_PrinterStatusDEC);
* ```
*/
declare const DSR_PrinterStatusDEC: string;
/**
* ANSI escape sequence `CSI ? 10 n` indicating Printer is Ready (DEC-specific response).
* Typical response to {@link DSR_PrinterStatusDEC} or `deviceStatusReport(requestPrinterStatusDEC)`.
* @see requestPrinterStatusDEC
* @see DSR_PrinterStatusDEC
*/
declare const reportPrinterReadyDEC: string;
/**
* ANSI escape sequence `CSI ? 11 n` indicating Printer is Not Ready (DEC-specific response).
* Typical response to {@link DSR_PrinterStatusDEC} or `deviceStatusReport(requestPrinterStatusDEC)`.
* @see requestPrinterStatusDEC
* @see DSR_PrinterStatusDEC
*/
declare const reportPrinterNotReadyDEC: string;
/**
* ANSI escape sequence `CSI ? 13 n` indicating Printer has No Paper (DEC-specific response).
* Typical response to {@link DSR_PrinterStatusDEC} or `deviceStatusReport(requestPrinterStatusDEC)`.
* @see requestPrinterStatusDEC
* @see DSR_PrinterStatusDEC
*/
declare const reportPrinterNoPaperDEC: string;
/**
* A DEC-specific {@link StatusReport} object to request User Defined Keys (UDK) status.
* Corresponds to DSR request `CSI ? 25 n`.
* The terminal is expected to respond with `CSI ? 20 n` (UDKs locked) or `CSI ? 21 n` (UDKs unlocked).
* @see DSR_UDKStatusDEC
* @see reportUDKLockedDEC
* @see reportUDKUnlockedDEC
*/
declare const requestUDKStatusDEC: StatusReport;
/**
* ANSI escape sequence `CSI ? 25 n` to request DEC-specific UDK status.
* This is generated using `deviceStatusReport(requestUDKStatusDEC)`.
* @see requestUDKStatusDEC
* @example
* ```typescript
* import { DSR_UDKStatusDEC } from "@visulima/ansi";
*
* process.stdout.write(DSR_UDKStatusDEC);
* ```
*/
declare const DSR_UDKStatusDEC: string;
/**
* ANSI escape sequence `CSI ? 20 n` indicating User Defined Keys (UDKs) are locked (DEC-specific response).
* Typical response to {@link DSR_UDKStatusDEC}.
*/
declare const reportUDKLockedDEC: string;
/**
* ANSI escape sequence `CSI ? 21 n` indicating User Defined Keys (UDKs) are unlocked (DEC-specific response).
* Typical response to {@link DSR_UDKStatusDEC}.
*/
declare const reportUDKUnlockedDEC: string;
/**
* A DEC-specific {@link StatusReport} object to request keyboard language status.
* This is often related to DECRQPSR (Request Presentation State Report) rather than a simple DSR with 'n'.
* For the purpose of this module, following the DSR pattern `CSI ? Ps n`.
* Corresponds to DSR request `CSI ? 26 n`.
* @see DSR_KeyboardLanguageDEC
* @see reportKeyboardLanguageDEC
*/
declare const requestKeyboardLanguageDEC: StatusReport;
/**
* ANSI escape sequence `CSI ? 26 n` to request DEC-specific keyboard language status.
* This is generated using `deviceStatusReport(requestKeyboardLanguageDEC)`.
* Note: Keyboard language reporting is complex and varies; this is a simplified DSR-style request.
* @see requestKeyboardLanguageDEC
* @see reportKeyboardLanguageDEC
* @example
* ```typescript
* import { DSR_KeyboardLanguageDEC } from "@visulima/ansi";
*
* process.stdout.write(DSR_KeyboardLanguageDEC);
* ```
*/
declare const DSR_KeyboardLanguageDEC: string;
/**
* Generates a DEC Keyboard Language Report sequence.
* This is an example of how a terminal might report its keyboard language.
* Sequence: `CSI ? Pl ; Pv n` (example format)
* - `Pl`: Parameter indicating language report (e.g., 27).
* - `Pv`: Value representing the language code.
* @param langCode The numeric code representing the keyboard language.
* @returns The keyboard language report sequence string.
* @example
* ```typescript
* import { reportKeyboardLanguageDEC } from "@visulima/ansi";
*
* console.log(reportKeyboardLanguageDEC(1));
* ```
*/
declare const reportKeyboardLanguageDEC: (langCode: number) => string;
/**
* ANSI escape sequence `CSI ? 996 n` to request the terminal to report its operating system light/dark color preference.
* Supported terminals should respond with a LightDarkReport sequence.
* @see {@link https://contour-terminal.org/vt-extensions/color-palette-update-notifications/}
*/
declare const RequestLightDarkReport: string;
/**
* Generates a Light/Dark Color Scheme Report sequence.
* This sequence reports the terminal's operating system light/dark color preference.
* @remarks
* - `CSI ? 997 ; 1 n` for dark mode.
* - `CSI ? 997 ; 2 n` for light mode.
* @param dark Whether the color scheme is dark mode (true) or light mode (false).
* @returns The light/dark report sequence string.
* @see {@link https://contour-terminal.org/vt-extensions/color-palette-update-notifications/}
* @example
* ```typescript
* import { LightDarkReport } from "@visulima/ansi";
*
* console.log(LightDarkReport(true)); // Dark mode: "\x1b[?997;1n"
* console.log(LightDarkReport(false)); // Light mode: "\x1b[?997;2n"
* ```
*/
declare const LightDarkReport: (dark: boolean) => string;
export { AnsiStatusReport, CPR, DA1, DA2, DA3, DECXCPR, DSR, DSR_KeyboardLanguageDEC, DSR_PrinterStatusDEC, DSR_TerminalStatus, DSR_UDKStatusDEC, DecStatusReport, LightDarkReport, RequestLightDarkReport, RequestNameVersion, StatusReport, XTVERSION, createAnsiStatusReport, createDecStatusReport, cursorPositionReport, deviceStatusReport, extendedCursorPositionReport, reportKeyboardLanguageDEC, reportPrimaryDeviceAttributes, reportPrinterNoPaperDEC, reportPrinterNotReadyDEC, reportPrinterReadyDEC, reportSecondaryDeviceAttributes, reportTerminalNotOK, reportTerminalOK, reportTertiaryDeviceAttributes, reportUDKLockedDEC, reportUDKUnlockedDEC, requestCursorPositionReport, requestExtendedCursorPositionReport, requestKeyboardLanguageDEC, requestPrimaryDeviceAttributes, requestPrimaryDeviceAttributesParam0, requestPrinterStatusDEC, requestSecondaryDeviceAttributes, requestSecondaryDeviceAttributesParam0, requestTerminalStatus, requestTertiaryDeviceAttributes, requestTertiaryDeviceAttributesParam0, requestUDKStatusDEC };