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 Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    ALTERNATE_BUFFER
    ANSI escape code to switch to alternate screen buffer.
    static final String
    BEL
    BEL character, used as OSC terminator.
    static final String
    BLACK_BG
    ANSI escape code for black background.
    static final String
    BLACK_TEXT
    ANSI escape code for black foreground text.
    static final String
    BLINK
    ANSI escape code to enable blinking text.
    static final String
    BLINK_OFF
    ANSI escape code to disable blinking text.
    static final String
    BLUE_BG
    ANSI escape code for blue background.
    static final String
    BLUE_TEXT
    ANSI escape code for blue foreground text.
    static final String
    BOLD
    ANSI escape code to enable bold text.
    static final String
    BOLD_OFF
    ANSI escape code to disable bold text.
    static final int[]
    CLEAR_SCREEN
    ANSI escape sequence to clear the entire screen.
    static final String
    CURSOR_HIDE
    ANSI escape code to hide the cursor.
    static final String
    CURSOR_RESTORE
    ANSI escape code to restore previously saved cursor position.
    static final String
    CURSOR_ROW
    ANSI escape code to query cursor row position.
    static final String
    CURSOR_SAVE
    ANSI escape code to save current cursor position.
    static final String
    CURSOR_SHOW
    ANSI escape code to show the cursor.
    static final int[]
    CURSOR_START
    ANSI escape sequence to move cursor to start of line.
    static final String
    CYAN_BG
    ANSI escape code for cyan background.
    static final String
    CYAN_TEXT
    ANSI escape code for cyan foreground text.
    static final String
    DA1_QUERY
    DA1 (Primary Device Attributes) query sequence.
    static final String
    DA2_QUERY
    DA2 (Secondary Device Attributes) query sequence.
    static final String
    DARK_BG
    ANSI escape code to enable dark (normal) background mode.
    static final String
    DEFAULT_BG
    ANSI escape code for default background color.
    static final String
    DEFAULT_TEXT
    ANSI escape code for default foreground text color.
    static final int[]
    ERASE_LINE_FROM_CURSOR
    ANSI escape sequence to erase from cursor to end of line.
    static final int[]
    ERASE_WHOLE_LINE
    ANSI escape sequence to erase the entire current line.
    static final String
    GREEN_BG
    ANSI escape code for green background.
    static final String
    GREEN_TEXT
    ANSI escape code for green foreground text.
    static final String
    INVERT_BACKGROUND
    ANSI escape code to invert foreground and background colors.
    static final String
    LIGHT_BG
    ANSI escape code to enable light (reverse video) background mode.
    static final String
    MAGENTA_BG
    ANSI escape code for magenta background.
    static final String
    MAGENTA_TEXT
    ANSI escape code for magenta foreground text.
    static final String
    MAIN_BUFFER
    ANSI escape code to switch back to main screen buffer.
    static final int[]
    MOVE_LINE_DOWN
    ANSI escape sequence to move cursor down one line.
    static final int[]
    MOVE_LINE_UP
    ANSI escape sequence to move cursor up one line.
    static final String
    NORMAL_BACKGROUND
    ANSI escape code to restore normal foreground and background colors.
    static final int
    OSC_BACKGROUND
    OSC code for background color query/set.
    static final int
    OSC_CURSOR_COLOR
    OSC code for cursor color query/set.
    static final int
    OSC_FOREGROUND
    OSC code for foreground color query/set.
    static final int
    OSC_PALETTE
    OSC code for palette color query/set.
    static final String
    OSC_START
    OSC (Operating System Command) escape sequence start.
    static final String
    RED_BG
    ANSI escape code for red background.
    static final String
    RED_TEXT
    ANSI escape code for red foreground text.
    static final String
    RESET
    ANSI escape code to reset all text attributes to default.
    static final String
    ST
    ST (String Terminator), alternate OSC terminator.
    static final String
    START
    ANSI escape sequence start.
    static final String
    UNDERLINE
    ANSI escape code to enable underlined text.
    static final String
    UNDERLINE_OFF
    ANSI escape code to disable underlined text.
    static final String
    WHITE_BG
    ANSI escape code for white background.
    static final String
    WHITE_TEXT
    ANSI escape code for white foreground text.
    static final String
    YELLOW_BG
    ANSI escape code for yellow background.
    static final String
    YELLOW_TEXT
    ANSI escape code for yellow foreground text.

  • Method Summary

    Modifier and Type
    Method
    Description
    static String
    buildOscQuery(int oscCode, int index, String param)
    Build an OSC query string with an additional index parameter.
    static String
    buildOscQuery(int oscCode, String param)
    Build an OSC (Operating System Command) query string.
    static int[]
    color256ToRgb(int index)
    Get the RGB values for a 256-color palette index.
    static Point
    getActualCursor(int[] input)
    Parse cursor position response and return the actual cursor position.
    static int[]
    moveColumnsLeft(int rows)
    Create ANSI escape sequence to move cursor left by specified columns.
    static int[]
    moveColumnsRight(int rows)
    Create ANSI escape sequence to move cursor right by specified columns.
    static int[]
    moveRowsDown(int rows)
    Create ANSI escape sequence to move cursor down by specified rows.
    static int[]
    moveRowsUp(int rows)
    Create ANSI escape sequence to move cursor up by specified rows.
    static DeviceAttributes
    parseDA1Response(int[] input)
    Parse a DA1 (Primary Device Attributes) response.
    static DeviceAttributes
    parseDA2Response(int[] input)
    Parse a DA2 (Secondary Device Attributes) response.
    static DeviceAttributes
    parseDAResponse(int[] input)
    Parse both DA1 and DA2 responses from a combined input.
    static int[]
    parseOscColorResponse(int[] input, int oscCode)
    Parse an OSC color response.
    static int[]
    parseOscColorResponse(int[] input, int oscCode, int oscParam)
    Parse an OSC color response with an optional parameter.
    static int[]
    printAnsi(char... out)
    Return a ansified string based on param
    static int[]
    printAnsi(String out)
    Return a ansified string based on param
    static boolean
    rgbIsBright(int r, int g, int b)
    Determine if an RGB color should use bright ANSI variant.
    static int
    rgbTo256Color(int r, int g, int b)
    Convert RGB to nearest 256-color palette index.
    static int
    rgbToAnsiBackgroundColor(int r, int g, int b)
    Convert RGB to nearest basic ANSI background color code.
    static int
    rgbToAnsiBackgroundColor(int r, int g, int b, boolean bright)
    Convert RGB to nearest basic ANSI background color code with explicit brightness.
    static int
    rgbToAnsiColor(int r, int g, int b)
    Convert RGB to nearest basic ANSI foreground color code.
    static int
    rgbToAnsiColor(int r, int g, int b, boolean bright)
    Convert RGB to nearest basic ANSI foreground color code with explicit brightness.
    static int
    rgbToBasicColorCode(int r, int g, int b)
    Get the basic ANSI color code (30-37) for an RGB value.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • 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:

    • 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.

    • 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.

    • 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:

    • 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

    • 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

    • 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

    • 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)

    • 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