Package org.aesh.terminal.utils

Class ANSI

java.lang.Object
org.aesh.terminal.utils.ANSI
public class ANSI extends Object
Utility class to provide ANSI codes for different operations
Author:
Ståle W. Pedersen

  • Field Details

    • START

      public static final String START
      ANSI escape sequence start.
      See Also:

    • BLACK_TEXT

      public static final String BLACK_TEXT
      ANSI escape code for black foreground text.
      See Also:

    • RED_TEXT

      public static final String RED_TEXT
      ANSI escape code for red foreground text.
      See Also:

    • GREEN_TEXT

      public static final String GREEN_TEXT
      ANSI escape code for green foreground text.
      See Also:

    • YELLOW_TEXT

      public static final String YELLOW_TEXT
      ANSI escape code for yellow foreground text.
      See Also:

    • BLUE_TEXT

      public static final String BLUE_TEXT
      ANSI escape code for blue foreground text.
      See Also:

    • MAGENTA_TEXT

      public static final String MAGENTA_TEXT
      ANSI escape code for magenta foreground text.
      See Also:

    • CYAN_TEXT

      public static final String CYAN_TEXT
      ANSI escape code for cyan foreground text.
      See Also:

    • WHITE_TEXT

      public static final String WHITE_TEXT
      ANSI escape code for white foreground text.
      See Also:

    • DEFAULT_TEXT

      public static final String DEFAULT_TEXT
      ANSI escape code for default foreground text color.
      See Also:

    • BLACK_BG

      public static final String BLACK_BG
      ANSI escape code for black background.
      See Also:

    • RED_BG

      public static final String RED_BG
      ANSI escape code for red background.
      See Also:

    • GREEN_BG

      public static final String GREEN_BG
      ANSI escape code for green background.
      See Also:

    • YELLOW_BG

      public static final String YELLOW_BG
      ANSI escape code for yellow background.
      See Also:

    • BLUE_BG

      public static final String BLUE_BG
      ANSI escape code for blue background.
      See Also:

    • MAGENTA_BG

      public static final String MAGENTA_BG
      ANSI escape code for magenta background.
      See Also:

    • CYAN_BG

      public static final String CYAN_BG
      ANSI escape code for cyan background.
      See Also:

    • WHITE_BG

      public static final String WHITE_BG
      ANSI escape code for white background.
      See Also:

    • DEFAULT_BG

      public static final String DEFAULT_BG
      ANSI escape code for default background color.
      See Also:

    • ALTERNATE_BUFFER

      public static final String ALTERNATE_BUFFER
      ANSI escape code to switch to alternate screen buffer.

    • MAIN_BUFFER

      public static final String MAIN_BUFFER
      ANSI escape code to switch back to main screen buffer.

    • INVERT_BACKGROUND

      public static final String INVERT_BACKGROUND
      ANSI escape code to invert foreground and background colors.

    • NORMAL_BACKGROUND

      public static final String NORMAL_BACKGROUND
      ANSI escape code to restore normal foreground and background colors.

    • RESET

      public static final String RESET
      ANSI escape code to reset all text attributes to default.
      See Also:

    • BOLD

      public static final String BOLD
      ANSI escape code to enable bold text.

    • BOLD_OFF

      public static final String BOLD_OFF
      ANSI escape code to disable bold text.
      See Also:

    • UNDERLINE

      public static final String UNDERLINE
      ANSI escape code to enable underlined text.

    • UNDERLINE_OFF

      public static final String UNDERLINE_OFF
      ANSI escape code to disable underlined text.

    • CURSOR_START

      public static final int[] CURSOR_START
      ANSI escape sequence to move cursor to start of line.

    • ERASE_WHOLE_LINE

      public static final int[] ERASE_WHOLE_LINE
      ANSI escape sequence to erase the entire current line.

    • CURSOR_ROW

      public static final String CURSOR_ROW
      ANSI escape code to query cursor row position.
      See Also:

    • CURSOR_POSITION_QUERY

      public static final int[] CURSOR_POSITION_QUERY
      ANSI escape code to query cursor position as int array (Device Status Report).

    • CLEAR_SCREEN

      public static final int[] CLEAR_SCREEN
      ANSI escape sequence to clear the entire screen.

    • CURSOR_SAVE

      public static final String CURSOR_SAVE
      ANSI escape code to save current cursor position.

    • CURSOR_RESTORE

      public static final String CURSOR_RESTORE
      ANSI escape code to restore previously saved cursor position.

    • CURSOR_HIDE

      public static final String CURSOR_HIDE
      ANSI escape code to hide the cursor.
      See Also:

    • CURSOR_SHOW

      public static final String CURSOR_SHOW
      ANSI escape code to show the cursor.
      See Also:

    • ERASE_LINE_FROM_CURSOR

      public static final int[] ERASE_LINE_FROM_CURSOR
      ANSI escape sequence to erase from cursor to end of line.

    • ERASE_SCREEN_FROM_CURSOR

      public static final int[] ERASE_SCREEN_FROM_CURSOR
      ANSI escape sequence to erase from cursor to end of screen.

    • MOVE_LINE_UP

      public static final int[] MOVE_LINE_UP
      ANSI escape sequence to move cursor up one line.

    • MOVE_LINE_DOWN

      public static final int[] MOVE_LINE_DOWN
      ANSI escape sequence to move cursor down one line.

    • DIM

      public static final int[] DIM
      ANSI escape sequence for dim/faint text (SGR 2).

    • DIM_OFF

      public static final int[] DIM_OFF
      ANSI escape sequence to turn off dim/faint text (SGR 22 — normal intensity).

    • LIGHT_BG

      public static final String LIGHT_BG
      ANSI escape code to enable light (reverse video) background mode.
      See Also:

    • DARK_BG

      public static final String DARK_BG
      ANSI escape code to enable dark (normal) background mode.
      See Also:

    • OSC_START

      public static final String OSC_START
      OSC (Operating System Command) escape sequence start.
      See Also:

    • BEL

      public static final String BEL
      BEL character, used as OSC terminator.
      See Also:

    • ST

      public static final String ST
      ST (String Terminator), alternate OSC terminator.
      See Also:

    • OSC_PALETTE

      public static final int OSC_PALETTE
      OSC code for palette color query/set.
      See Also:

    • OSC_FOREGROUND

      public static final int OSC_FOREGROUND
      OSC code for foreground color query/set.
      See Also:

    • OSC_BACKGROUND

      public static final int OSC_BACKGROUND
      OSC code for background color query/set.
      See Also:

    • OSC_CURSOR_COLOR

      public static final int OSC_CURSOR_COLOR
      OSC code for cursor color query/set.
      See Also:

    • OSC_SHELL_INTEGRATION

      public static final int OSC_SHELL_INTEGRATION
      OSC code for shell integration (semantic prompt).
      See Also:

    • OSC_133_PROMPT_START

      public static final String OSC_133_PROMPT_START
      OSC 133;A — Prompt Start: emitted before the prompt text.
      See Also:

    • OSC_133_PROMPT_END

      public static final String OSC_133_PROMPT_END
      OSC 133;B — Prompt End: emitted after the prompt, before user input.
      See Also:

    • OSC_133_COMMAND_START

      public static final String OSC_133_COMMAND_START
      OSC 133;C — Command Start: emitted when the user presses Enter.
      See Also:

    • OSC_133_COMMAND_FINISHED

      public static final String OSC_133_COMMAND_FINISHED
      OSC 133;D — Command Finished: emitted after command completes (no exit code).
      See Also:

    • THEME_MODE_QUERY

      public static final String THEME_MODE_QUERY
      CSI query to request the current color theme mode (dark or light).

      Sends CSI ? 996 n to the terminal. The terminal responds with:

      • CSI ? 997 ; 1 n for dark mode
      • CSI ? 997 ; 2 n for light mode

      Ref: Contour VT extension: Dark and Light Mode detection

      Supported by: Contour, Ghostty, Kitty (0.38.1+), tmux, VTE (0.82.0+), Helix, Neovim.

      See Also:

    • THEME_NOTIFY_ENABLE

      public static final String THEME_NOTIFY_ENABLE
      Enable unsolicited DSR notifications for color palette updates.

      Sends CSI ? 2031 h to the terminal. When enabled, the terminal will send CSI ? 997 ; 1 n or CSI ? 997 ; 2 n whenever the color palette changes (e.g., dark/light mode switch, profile change).

      Use THEME_NOTIFY_DISABLE to stop receiving notifications.

      See Also:

    • THEME_NOTIFY_DISABLE

      public static final String THEME_NOTIFY_DISABLE
      Disable unsolicited DSR notifications for color palette updates.

      Sends CSI ? 2031 l to the terminal.

      See Also:

    • THEME_DSR_DARK

      public static final int THEME_DSR_DARK
      DSR response value indicating dark mode: CSI ? 997 ; 1 n.
      See Also:

    • THEME_DSR_LIGHT

      public static final int THEME_DSR_LIGHT
      DSR response value indicating light mode: CSI ? 997 ; 2 n.
      See Also:

    • MODE_2026_QUERY

      public static final String MODE_2026_QUERY
      DECRQM query for Mode 2026 (synchronized output).
      See Also:

    • MODE_2026_ENABLE

      public static final String MODE_2026_ENABLE
      Enable Mode 2026 (synchronized output) — Begin Synchronized Update (BSU).
      See Also:

    • MODE_2026_DISABLE

      public static final String MODE_2026_DISABLE
      Disable Mode 2026 (synchronized output) — End Synchronized Update (ESU).
      See Also:

    • MODE_2027_QUERY

      public static final String MODE_2027_QUERY
      DECRQM query for Mode 2027 (grapheme cluster segmentation).
      See Also:

    • MODE_2027_ENABLE

      public static final String MODE_2027_ENABLE
      Enable Mode 2027 (grapheme cluster segmentation).
      See Also:

    • MODE_2027_DISABLE

      public static final String MODE_2027_DISABLE
      Disable Mode 2027 (grapheme cluster segmentation).
      See Also:

    • DA1_QUERY

      public static final String DA1_QUERY
      DA1 (Primary Device Attributes) query sequence.
      See Also:

    • DA2_QUERY

      public static final String DA2_QUERY
      DA2 (Secondary Device Attributes) query sequence.
      See Also:

  • Method Details

    • osc133CommandFinished

      public static String osc133CommandFinished(int exitCode)
      Build an OSC 133;D sequence with an exit code.
      Parameters:
      exitCode - the command exit code
      Returns:
      the OSC 133;D;exitCode sequence

    • printAnsi

      public static int[] printAnsi(String out)
      Return a ansified string based on param
      Parameters:
      out - string
      Returns:
      ansified string

    • printAnsi

      public static int[] printAnsi(char... out)
      Return a ansified string based on param
      Parameters:
      out - what will be ansified
      Returns:
      ansified string

    • getActualCursor

      public static Point getActualCursor(int[] input)
      Parse cursor position response and return the actual cursor position.
      Parameters:
      input - the ANSI cursor position response sequence
      Returns:
      a Point containing the column and row of the cursor

    • moveRowsUp

      public static int[] moveRowsUp(int rows)
      Create ANSI escape sequence to move cursor up by specified rows.
      Parameters:
      rows - number of rows to move up
      Returns:
      ANSI escape sequence as int array

    • moveRowsDown

      public static int[] moveRowsDown(int rows)
      Create ANSI escape sequence to move cursor down by specified rows.
      Parameters:
      rows - number of rows to move down
      Returns:
      ANSI escape sequence as int array

    • moveColumnsRight

      public static int[] moveColumnsRight(int rows)
      Create ANSI escape sequence to move cursor right by specified columns.
      Parameters:
      rows - number of columns to move right
      Returns:
      ANSI escape sequence as int array

    • moveColumnsLeft

      public static int[] moveColumnsLeft(int rows)
      Create ANSI escape sequence to move cursor left by specified columns.
      Parameters:
      rows - number of columns to move left
      Returns:
      ANSI escape sequence as int array

    • cursorPosition

      public static int[] cursorPosition(int row, int col)
      Build an ANSI cursor position sequence: ESC[row;colH

      Uses exact-size allocation to avoid oversized buffers and array copying.

      Parameters:
      row - the 1-based row number
      col - the 1-based column number
      Returns:
      ANSI cursor position sequence as int array

    • buildOscQuery

      public static String buildOscQuery(int oscCode, String param)
      Build an OSC (Operating System Command) query string.

      OSC format: ESC ] Ps ; Pt BEL Where Ps is the OSC code and Pt is the parameter.

      Parameters:
      oscCode - the OSC code (e.g., 10 for foreground, 11 for background)
      param - the parameter (e.g., "?" for query)
      Returns:
      the OSC query string

    • buildOscQuery

      public static String buildOscQuery(int oscCode, int index, String param)
      Build an OSC query string with an additional index parameter.

      This is used for OSC codes that require an index, such as OSC 4 (palette colors).

      OSC format: ESC ] Ps ; Pn ; Pt BEL Where Ps is the OSC code, Pn is the index/parameter, and Pt is the query.

      Parameters:
      oscCode - the OSC code (e.g., 4 for palette color)
      index - the index parameter (e.g., palette color index 0-255)
      param - the parameter (e.g., "?" for query)
      Returns:
      the OSC query string

    • buildHyperlinkStart

      public static String buildHyperlinkStart(String url, String id)
      Build an OSC 8 hyperlink open sequence.

      Format: ESC ] 8 ; params ; URL ST

      Parameters:
      url - the hyperlink URL (must not be null)
      id - optional link id for grouping (may be null)
      Returns:
      the opening escape sequence
      Throws:
      IllegalArgumentException - if url is null

    • buildHyperlinkEnd

      public static String buildHyperlinkEnd()
      Build an OSC 8 hyperlink close sequence.

      Format: ESC ] 8 ; ; ST

      Returns:
      the closing escape sequence

    • hyperlink

      public static String hyperlink(String url, String text, String id)
      Wrap visible text in a complete OSC 8 hyperlink.
      Parameters:
      url - the hyperlink URL
      text - the visible text
      id - optional link id (may be null)
      Returns:
      the full sequence: open + text + close

    • hyperlink

      public static String hyperlink(String url, String text)
      Wrap visible text in a complete OSC 8 hyperlink (without id).
      Parameters:
      url - the hyperlink URL
      text - the visible text
      Returns:
      the full sequence: open + text + close

    • buildBatchOscQuery

      public static String buildBatchOscQuery(int... oscCodes)
      Build a batch OSC query string for multiple OSC codes.

      This method concatenates multiple OSC queries into a single string, allowing them to be sent to the terminal in one write operation. This is much more efficient than sending queries one at a time, as it reduces latency from multiple round-trips.

      For example, querying foreground (10), background (11), and cursor (12) colors at once instead of sequentially can reduce total query time from 600-700ms to under 100ms.

      Parameters:
      oscCodes - the OSC codes to query (e.g., 10, 11, 12)
      Returns:
      the concatenated OSC query string

    • buildBatchOscQueryWithIndices

      public static String buildBatchOscQueryWithIndices(int oscCode, int... indices)
      Build a batch OSC query string for multiple OSC codes with index parameters.

      This is useful for querying multiple palette colors at once (OSC 4).

      Parameters:
      oscCode - the OSC code (e.g., 4 for palette)
      indices - the indices to query
      Returns:
      the concatenated OSC query string

    • parseMultipleOscColorResponses

      public static Map<Integer,int[]> parseMultipleOscColorResponses(int[] input, int... expectedCodes)
      Parse multiple OSC color responses from a single input buffer.

      This method extracts all OSC color responses from an input that may contain multiple concatenated responses. It's used with batch queries where multiple OSC queries are sent at once and responses come back together.

      The method returns a map from OSC code to RGB values. For OSC codes with indices (like OSC 4 palette colors), the key is encoded as (oscCode * 1000 + index).

      Parameters:
      input - the input sequence containing multiple OSC responses
      expectedCodes - the OSC codes that were queried
      Returns:
      map from OSC code to RGB array [r, g, b] (0-255 each)

    • parseMultiplePaletteResponses

      public static Map<Integer,int[]> parseMultiplePaletteResponses(int[] input, int... indices)
      Parse multiple OSC palette color responses from a single input buffer.

      This method extracts OSC 4 palette color responses for multiple indices.

      Parameters:
      input - the input sequence containing multiple OSC 4 responses
      indices - the palette indices that were queried
      Returns:
      map from palette index to RGB array [r, g, b] (0-255 each)

    • parseOscColorResponse

      public static int[] parseOscColorResponse(int[] input, int oscCode)
      Parse an OSC color response.

      Expected format: ESC ] {oscCode} ; rgb:RRRR/GGGG/BBBB {ST} Where:

      • ESC is 0x1B (27)
      • oscCode is the OSC code (e.g., 10 for foreground, 11 for background)
      • RRRR, GGGG, BBBB are 4-digit or 2-digit hex values
      • ST is either BEL (0x07) or ESC \ (0x1B 0x5C)

      For OSC codes with parameters (like OSC 4 palette colors), use parseOscColorResponse(int[], int, int) instead.

      Parameters:
      input - the input sequence as code points
      oscCode - the expected OSC code in response
      Returns:
      RGB array [r, g, b] (0-255 each), or null if parsing failed

    • parseOscColorResponse

      public static int[] parseOscColorResponse(int[] input, int oscCode, int oscParam)
      Parse an OSC color response with an optional parameter.

      This method handles OSC codes that include a parameter, such as OSC 4 (palette colors) which includes a color index.

      Expected formats:

      • Without parameter: ESC ] {code} ; rgb:RRRR/GGGG/BBBB {ST}
      • With parameter: ESC ] {code} ; {param} ; rgb:RRRR/GGGG/BBBB {ST}
      Parameters:
      input - the input sequence as code points
      oscCode - the expected OSC code in response
      oscParam - the expected parameter (e.g., palette index for OSC 4), or -1 to not require a specific parameter
      Returns:
      RGB array [r, g, b] (0-255 each), or null if parsing failed

    • rgbTo256Color

      public static int rgbTo256Color(int r, int g, int b)
      Convert RGB to nearest 256-color palette index.

      The 256-color palette consists of:

      • 0-15: Standard and bright ANSI colors
      • 16-231: 6x6x6 color cube
      • 232-255: 24-shade grayscale ramp

      This method maps to the color cube (16-231) or grayscale (232-255). For standard ANSI colors (0-15), use rgbToAnsiColor(int, int, int).

      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      the nearest 256-color palette index (16-255)

    • rgbToAnsiColor

      public static int rgbToAnsiColor(int r, int g, int b)
      Convert RGB to nearest basic ANSI foreground color code.

      Returns a foreground color code in the range 30-37 (normal) or 90-97 (bright), automatically determining brightness based on the RGB luminance.

      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      ANSI foreground color code (30-37 or 90-97)

    • rgbToAnsiColor

      public static int rgbToAnsiColor(int r, int g, int b, boolean bright)
      Convert RGB to nearest basic ANSI foreground color code with explicit brightness.

      Returns a foreground color code:

      • 30-37: Normal colors (black, red, green, yellow, blue, magenta, cyan, white)
      • 90-97: Bright colors
      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      bright - true for bright variant (90-97), false for normal (30-37)
      Returns:
      ANSI foreground color code

    • rgbToAnsiBackgroundColor

      public static int rgbToAnsiBackgroundColor(int r, int g, int b)
      Convert RGB to nearest basic ANSI background color code.

      Returns a background color code in the range 40-47 (normal) or 100-107 (bright), automatically determining brightness based on the RGB luminance.

      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      ANSI background color code (40-47 or 100-107)

    • rgbToAnsiBackgroundColor

      public static int rgbToAnsiBackgroundColor(int r, int g, int b, boolean bright)
      Convert RGB to nearest basic ANSI background color code with explicit brightness.

      Returns a background color code:

      • 40-47: Normal colors
      • 100-107: Bright colors
      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      bright - true for bright variant (100-107), false for normal (40-47)
      Returns:
      ANSI background color code

    • rgbToBasicColorCode

      public static int rgbToBasicColorCode(int r, int g, int b)
      Get the basic ANSI color code (30-37) for an RGB value.

      Maps RGB to one of the 8 basic colors:

      • 30: Black
      • 31: Red
      • 32: Green
      • 33: Yellow
      • 34: Blue
      • 35: Magenta
      • 36: Cyan
      • 37: White
      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      basic ANSI color code (30-37)

    • rgbIsBright

      public static boolean rgbIsBright(int r, int g, int b)
      Determine if an RGB color should use bright ANSI variant.
      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      true if the color is bright enough for bright ANSI variant

    • color256ToRgb

      public static int[] color256ToRgb(int index)
      Get the RGB values for a 256-color palette index.

      This is the inverse of rgbTo256Color(int, int, int).

      Parameters:
      index - the 256-color palette index (0-255)
      Returns:
      RGB array [r, g, b] (0-255 each)

    • parseThemeDsrResponse

      public static TerminalTheme parseThemeDsrResponse(int[] input)
      Parse a theme mode DSR response.

      Expected format: ESC [ ? 997 ; Ps n

      Where Ps is:

      • 1 for dark mode
      • 2 for light mode

      This parses the response to THEME_MODE_QUERY (CSI ? 996 n) and also handles unsolicited DSR notifications when THEME_NOTIFY_ENABLE (CSI ? 2031 h) is active.

      Parameters:
      input - the input sequence as code points
      Returns:
      TerminalTheme.DARK or TerminalTheme.LIGHT, or null if the input does not contain a valid theme DSR response

    • parseMode2026Response

      public static Boolean parseMode2026Response(int[] input)
      Parse a DECRPM (DEC Private Mode Report) response for Mode 2026.

      Expected format: CSI ? 2026 ; Ps $ y

      Where Ps indicates the mode status:

      • 0 - not recognized
      • 1 - set (enabled)
      • 2 - reset (disabled, but recognized)
      • 3 - permanently set
      • 4 - permanently reset

      Returns Boolean.TRUE if Ps is 1, 2, or 3 (terminal recognizes the mode), Boolean.FALSE if Ps is 0 or 4 (not recognized or permanently disabled), or null if the response cannot be parsed.

      Parameters:
      input - the input sequence as code points
      Returns:
      true if the terminal supports Mode 2026, false if not, null if unparseable

    • parseMode2027Response

      public static Boolean parseMode2027Response(int[] input)
      Parse a DECRPM (DEC Private Mode Report) response for Mode 2027.

      Expected format: CSI ? 2027 ; Ps $ y

      Where Ps indicates the mode status:

      • 0 - not recognized
      • 1 - set (enabled)
      • 2 - reset (disabled, but recognized)
      • 3 - permanently set
      • 4 - permanently reset

      Returns Boolean.TRUE if Ps is 1, 2, or 3 (terminal recognizes the mode), Boolean.FALSE if Ps is 0 or 4 (not recognized or permanently disabled), or null if the response cannot be parsed.

      Parameters:
      input - the input sequence as code points
      Returns:
      true if the terminal supports Mode 2027, false if not, null if unparseable

    • parseDA1Response

      public static DeviceAttributes parseDA1Response(int[] input)
      Parse a DA1 (Primary Device Attributes) response.

      Expected format: ESC [ ? Ps ; Ps ; ... c

      Where the first Ps is the device class/conformance level and subsequent Ps values are feature parameters.

      Parameters:
      input - the input sequence as code points
      Returns:
      DeviceAttributes parsed from DA1, or null if parsing failed

    • parseDA2Response

      public static DeviceAttributes parseDA2Response(int[] input)
      Parse a DA2 (Secondary Device Attributes) response.

      Expected format: ESC [ > Pp ; Pv ; Pc c

      Where:

      • Pp is the terminal type (0=VT100, 1=VT220, etc.)
      • Pv is the firmware version
      • Pc is the ROM cartridge registration number
      Parameters:
      input - the input sequence as code points
      Returns:
      DeviceAttributes parsed from DA2, or null if parsing failed

    • parseDAResponse

      public static DeviceAttributes parseDAResponse(int[] input)
      Parse both DA1 and DA2 responses from a combined input.

      This is useful when both queries are sent together and responses arrive in sequence.

      Parameters:
      input - the input sequence containing both responses
      Returns:
      DeviceAttributes with merged DA1 and DA2 data, or null if parsing failed