escape-codes

escape-codes

A Node.js package providing an extensive collection of ANSI escape codes for enhanced command-line interface (CLI) styling and interaction. It allows for sophisticated text formatting, color manipulation, cursor control, and provides utilities for reading and writing in terminal applications.

Features

• ANSI Escape Codes: Constants for text formatting, cursor movement, color setting, and more.
• Control Keys: Key codes for common control characters and actions.
• Text Formatting: Methods for styling CLI output with bold, italic, underline, blinking text, etc.
• Cursor Control: Functions to manipulate the cursor position in the terminal.
• Color Codes: Easy-to-use foreground and background color settings.
• ASCII Control Characters: Mapped ASCII control characters for various control actions.
• CLI Interaction: Utilities for synchronous and asynchronous terminal I/O operations.

Installation

To install Escape Codes, run the following command in your project directory:

npm install escape-codes

Usage

After installation, import the module into your project to access its functionalities:

import { ansi, ascii, cli } from 'escape-codes';

Then use the codes to control and format the terminal.

cli.write([ansi.foreground.blue, "Hello, Blue!", ansi.format.reset])
cli.write(`${ansi.format.bold}I am bold!${ansi.format.reset}`)
cli.write(ansi.cursor.left(1))

Or read input from the terminal.

cli.read((stroke, stop) => {
  switch (stroke) {
    case ansi.key.exit:
      process.exit()
    case ansi.key.enter:
      stop() // stop reading key strokes
      break
    default:
      if (/^[a-zA-Z0-9 .,!?;:'"()-]*$/.test(stroke)) {
        console.log(`You pressed: ${stroke}`)
      }
  }
})

API

Below is the detailed API documentation for the Escape Codes package:

ANSI Codes

ANSI escape codes for various CLI styling and control:

Property	Description
ansi.key	Key codes for control actions.
ansi.format	Formatting codes for text styling.
ansi.cursor	Cursor control codes.
ansi.foreground	Foreground color codes.
ansi.background	Background color codes.

Control Keys

Usage: ansi.key.tab

Key	Code	Description
tab	"\x09"	Horizontal Tab
enter	"\x0D"	Carriage Return (Enter)
escape	"\x1B"	Escape character
backspace	"\x7F"	Backspace character
delete	"\u001b[3~"	Delete character
exit	"\x03"	Exit character (Ctrl+C)
up	"\x1B[A"	Arrow Up
down	"\x1B[B"	Arrow Down
right	"\x1B[C"	Arrow Right
left	"\x1B[D"	Arrow Left

Formatting Codes

Usage: ansi.format.reset

Style	Code	Description
reset	"\x1b[0m"	Reset all styles to default
bold	"\x1b[1m"	Bold text
faint	"\x1b[2m"	Fainter text
italic	"\x1b[3m"	Italic text
underline	"\x1b[4m"	Underlined text
blink	"\x1b[5m"	Slow Blink
rapid	"\x1b[6m"	Rapid Blink (not widely supported)
reverse	"\x1b[7m"	Swap foreground and background colors
conceal	"\x1b[8m"	Conceal text (not widely supported)
strike	"\x1b[9m"	Strikethrough text

Cursor Control Codes

Usage: ansi.cursor.up(3) or ansi.cursor.save

Action	Code	Description
up	(n = 1) => "\x1b[${n}A"	Move cursor up by 'n' rows
down	(n = 1) => "\x1b[${n}B"	Move cursor down by 'n' rows
right	(n = 1) => "\x1b[${n}C"	Move cursor right by 'n' columns
left	(n = 1) => "\x1b[${n}D"	Move cursor left by 'n' columns
move	(n, m) => "\x1b[${n};${m}H"	Move cursor to row 'n', column 'm'
save	"\x1b[s"	Save the current cursor position
restore	"\x1b[u"	Restore the saved cursor position
show	"\x1b[?25h"	Show the cursor
hide	"\x1b[?25l"	Hide the cursor

Foreground Color Codes

Usage: ansi.foreground.blue

Property	Code	Description
default	"\x1b[39m"	Default foreground color
black	"\x1b[30m"	Black text color
red	"\x1b[31m"	Red text color
green	"\x1b[32m"	Green text color
yellow	"\x1b[33m"	Yellow text color
blue	"\x1b[34m"	Blue text color
magenta	"\x1b[35m"	Magenta text color
cyan	"\x1b[36m"	Cyan text color
white	"\x1b[37m"	White text color
brightBlack	"\x1b[90m"	Bright black text color
brightRed	"\x1b[91m"	Bright red text color
brightGreen	"\x1b[92m"	Bright green text color
brightYellow	"\x1b[93m"	Bright yellow text color
brightBlue	"\x1b[94m"	Bright blue text color
brightMagenta	"\x1b[95m"	Bright magenta text color
brightCyan	"\x1b[96m"	Bright cyan text color
brightWhite	"\x1b[97m"	Bright white text color

Background Color Codes

Usage: ansi.background.red

Property	Code	Description
default	"\x1b[49m"	Default background color
black	"\x1b[40m"	Black background color
red	"\x1b[41m"	Red background color
green	"\x1b[42m"	Green background color
yellow	"\x1b[43m"	Yellow background color
blue	"\x1b[44m"	Blue background color
magenta	"\x1b[45m"	Magenta background color
cyan	"\x1b[46m"	Cyan background color
white	"\x1b[47m"	White background color
brightBlack	"\x1b[100m"	Bright black background color
brightRed	"\x1b[101m"	Bright red background color
brightGreen	"\x1b[102m"	Bright green background color
brightYellow	"\x1b[103m"	Bright yellow background color
brightBlue	"\x1b[104m"	Bright blue background color
brightMagenta	"\x1b[105m"	Bright magenta background color
brightCyan	"\x1b[106m"	Bright cyan background color
brightWhite	"\x1b[107m"	Bright white background color

ASCII Control Characters

Usage: ascii.ctrlA (note the ascii instead of ansi)

Property	Code	ASCII Character	Description
ctrlA	"\x01"	Start of Header (SOH)	Marks the start of a header.
ctrlB	"\x02"	Start of Text (STX)	Marks the start of the text intended for processing.
ctrlC	"\x03"	End of Text (ETX)	Marks the break or end of the text.
ctrlD	"\x04"	End of Transmission (EOT)	Indicates the end of transmission of data.
ctrlE	"\x05"	Enquiry (ENQ)	Requests an answer from a remote station.
ctrlF	"\x06"	Acknowledge (ACK)	Acknowledges receipt of a message.
ctrlG	"\x07"	Bell (BEL)	Triggers an alert or bell signal.
ctrlH	"\x08"	Backspace (BS)	Moves the cursor one position backwards.
ctrlI	"\x09"	Horizontal Tab (HT)	Moves the cursor to the next horizontal tab stop.
ctrlJ	"\x0A"	Line Feed (LF)	Moves the cursor to the next line.
ctrlK	"\x0B"	Vertical Tab (VT)	Moves the cursor to the next vertical tab stop.
ctrlL	"\x0C"	Form Feed (FF)	Moves to the next form or page.
ctrlM	"\x0D"	Carriage Return (CR)	Moves the cursor to the beginning of the line.
ctrlN	"\x0E"	Shift Out / X-On (SO)	Activates the transmission of control characters.
ctrlO	"\x0F"	Shift In / X-Off (SI)	Deactivates the transmission of control characters.
ctrlP	"\x10"	Data Link Escape (DLE)	Signals a change in the meaning of the following characters.
ctrlQ	"\x11"	Device Control 1 (DC1)	Often used as XON for software flow control.
ctrlR	"\x12"	Device Control 2 (DC2)	Device-specific control function.
ctrlS	"\x13"	Device Control 3 (DC3)	Often used as XOFF for software flow control.
ctrlT	"\x14"	Device Control 4 (DC4)	Device-specific control function.
ctrlU	"\x15"	Negative Acknowledge (NAK)	Indicates that data was received incorrectly.
ctrlV	"\x16"	Synchronous Idle (SYN)	Used to maintain timing for synchronous transmission.
ctrlW	"\x17"	End of Transmission Block (ETB)	Marks the end of a block of data for transmission.
ctrlX	"\x18"	Cancel (CAN)	Indicates that the data preceding it is in error.
ctrlY	"\x19"	End of Medium (EM)	Indicates the logical end of the medium.
ctrlZ	"\x1A"	Substitute (SUB)	A placeholder character used to replace a character considered to be erroneous or corrupt.

CLI Interaction

Utility functions for terminal I/O operations:

cli.write

Writes data to the standard output.

cli.write(data: string | string[]);

cli.read

Reads input from the standard input, character by character.

cli.read(cb: (data: string, stop: () => void) => void);

cli.input

Asynchronously captures a single line of input from the standard input.

async cli.input(): Promise<string>;

Contributions

We welcome contributions from the community. If you'd like to contribute, please fork the repository, make your changes, and submit a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for more details.

Support

For questions, issues, or feature requests, please submit an issue on the GitHub repository.