Package org.aesh.terminal.utils

Class ANSIBuilder

java.lang.Object
org.aesh.terminal.utils.ANSIBuilder
public class ANSIBuilder extends Object
A fluent builder for constructing ANSI escape sequences for terminal text formatting. Supports colors, text styles (bold, italic, underline, etc.), and various text effects.

Basic usage: 

 String output = ANSIBuilder.builder()
         .bold().redText("Error: ").boldOff()
         .append("Something went wrong")
         .toString();

Theme-aware usage with semantic colors: 

 TerminalColorCapability cap = TerminalColorCapability.detectFromEnvironment();
 String output = ANSIBuilder.builder(cap)
         .timestamp("2024-01-15 10:30:45").append(" ")
         .error("ERROR").append(" ")
         .category("[org.aesh.readline.ReadlineConsole]").append(" ")
         .threadName("(main)").append(" ")
         .message("Failed to initialize readline")
         .toString();

Extended color support: 

 ANSIBuilder.builder()
         .bright().redText("Bright red") // Bright color variant
         .color256(208).append("Orange") // 256-color palette
         .rgb(255, 100, 50).append("Custom") // True color RGB
         .toString();
Author:
Ståle Pedersen

  • Method Details

    • builder

      public static ANSIBuilder builder()
      Creates a new ANSIBuilder with ANSI formatting enabled.
      Returns:
      a new ANSIBuilder instance

    • builder

      public static ANSIBuilder builder(boolean enableAnsi)
      Creates a new ANSIBuilder with configurable ANSI formatting.
      Parameters:
      enableAnsi - true to enable ANSI escape sequences, false to disable
      Returns:
      a new ANSIBuilder instance

    • builder

      public static ANSIBuilder builder(TerminalColorCapability capability)
      Creates a new theme-aware ANSIBuilder with terminal color capability.

      When a capability is provided, semantic color methods like error(), success(), timestamp(), etc. will automatically choose appropriate color intensities based on the terminal's theme (light or dark).

      Parameters:
      capability - the detected terminal color capability
      Returns:
      a new ANSIBuilder instance configured for the terminal

    • errorCode

      public ANSIBuilder errorCode(int code)
      Overrides the error color code for this builder.

      This takes precedence over the capability-provided color. Supports basic ANSI codes (30-37, 90-97) or 256-color palette indices (0-255).

      Parameters:
      code - the ANSI color code to use for error messages
      Returns:
      this builder for method chaining

    • successCode

      public ANSIBuilder successCode(int code)
      Overrides the success color code for this builder.
      Parameters:
      code - the ANSI color code to use for success messages
      Returns:
      this builder for method chaining

    • warningCode

      public ANSIBuilder warningCode(int code)
      Overrides the warning color code for this builder.
      Parameters:
      code - the ANSI color code to use for warning messages
      Returns:
      this builder for method chaining

    • infoCode

      public ANSIBuilder infoCode(int code)
      Overrides the info color code for this builder.
      Parameters:
      code - the ANSI color code to use for info messages
      Returns:
      this builder for method chaining

    • debugCode

      public ANSIBuilder debugCode(int code)
      Overrides the debug color code for this builder.
      Parameters:
      code - the ANSI color code to use for debug messages
      Returns:
      this builder for method chaining

    • traceCode

      public ANSIBuilder traceCode(int code)
      Overrides the trace color code for this builder.
      Parameters:
      code - the ANSI color code to use for trace messages
      Returns:
      this builder for method chaining

    • timestampCode

      public ANSIBuilder timestampCode(int code)
      Overrides the timestamp color code for this builder.
      Parameters:
      code - the ANSI color code to use for timestamps
      Returns:
      this builder for method chaining

    • messageCode

      public ANSIBuilder messageCode(int code)
      Overrides the message color code for this builder.
      Parameters:
      code - the ANSI color code to use for highlighted messages
      Returns:
      this builder for method chaining

    • categoryCode

      public ANSIBuilder categoryCode(int code)
      Overrides the category (package/class name) color code for this builder.
      Parameters:
      code - the ANSI color code to use for category/logger names
      Returns:
      this builder for method chaining

    • threadNameCode

      public ANSIBuilder threadNameCode(int code)
      Overrides the thread name color code for this builder.
      Parameters:
      code - the ANSI color code to use for thread names
      Returns:
      this builder for method chaining

    • fatalCode

      public ANSIBuilder fatalCode(int code)
      Overrides the fatal color code for this builder.
      Parameters:
      code - the ANSI color code to use for fatal messages
      Returns:
      this builder for method chaining

    • errorRgb

      public ANSIBuilder errorRgb(int r, int g, int b)
      Overrides the error color using RGB values (true color).

      RGB overrides take precedence over code overrides.

      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      this builder for method chaining

    • errorHex

      public ANSIBuilder errorHex(String hex)
      Overrides the error color using a hex color value.
      Parameters:
      hex - the color in hex format (e.g., "#FF5733" or "FF5733")
      Returns:
      this builder for method chaining

    • errorHsl

      public ANSIBuilder errorHsl(float h, float s, float l)
      Overrides the error color using HSL values.
      Parameters:
      h - hue in degrees (0-360)
      s - saturation as percentage (0-100)
      l - lightness as percentage (0-100)
      Returns:
      this builder for method chaining

    • successRgb

      public ANSIBuilder successRgb(int r, int g, int b)
      Overrides the success color using RGB values (true color).
      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      this builder for method chaining

    • successHex

      public ANSIBuilder successHex(String hex)
      Overrides the success color using a hex color value.
      Parameters:
      hex - the color in hex format
      Returns:
      this builder for method chaining

    • successHsl

      public ANSIBuilder successHsl(float h, float s, float l)
      Overrides the success color using HSL values.
      Parameters:
      h - hue in degrees (0-360)
      s - saturation as percentage (0-100)
      l - lightness as percentage (0-100)
      Returns:
      this builder for method chaining

    • warningRgb

      public ANSIBuilder warningRgb(int r, int g, int b)
      Overrides the warning color using RGB values (true color).
      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      this builder for method chaining

    • warningHex

      public ANSIBuilder warningHex(String hex)
      Overrides the warning color using a hex color value.
      Parameters:
      hex - the color in hex format
      Returns:
      this builder for method chaining

    • warningHsl

      public ANSIBuilder warningHsl(float h, float s, float l)
      Overrides the warning color using HSL values.
      Parameters:
      h - hue in degrees (0-360)
      s - saturation as percentage (0-100)
      l - lightness as percentage (0-100)
      Returns:
      this builder for method chaining

    • infoRgb

      public ANSIBuilder infoRgb(int r, int g, int b)
      Overrides the info color using RGB values (true color).
      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      this builder for method chaining

    • infoHex

      public ANSIBuilder infoHex(String hex)
      Overrides the info color using a hex color value.
      Parameters:
      hex - the color in hex format
      Returns:
      this builder for method chaining

    • infoHsl

      public ANSIBuilder infoHsl(float h, float s, float l)
      Overrides the info color using HSL values.
      Parameters:
      h - hue in degrees (0-360)
      s - saturation as percentage (0-100)
      l - lightness as percentage (0-100)
      Returns:
      this builder for method chaining

    • debugRgb

      public ANSIBuilder debugRgb(int r, int g, int b)
      Overrides the debug color using RGB values (true color).
      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      this builder for method chaining

    • debugHex

      public ANSIBuilder debugHex(String hex)
      Overrides the debug color using a hex color value.
      Parameters:
      hex - the color in hex format
      Returns:
      this builder for method chaining

    • debugHsl

      public ANSIBuilder debugHsl(float h, float s, float l)
      Overrides the debug color using HSL values.
      Parameters:
      h - hue in degrees (0-360)
      s - saturation as percentage (0-100)
      l - lightness as percentage (0-100)
      Returns:
      this builder for method chaining

    • traceRgb

      public ANSIBuilder traceRgb(int r, int g, int b)
      Overrides the trace color using RGB values (true color).
      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      this builder for method chaining

    • traceHex

      public ANSIBuilder traceHex(String hex)
      Overrides the trace color using a hex color value.
      Parameters:
      hex - the color in hex format
      Returns:
      this builder for method chaining

    • traceHsl

      public ANSIBuilder traceHsl(float h, float s, float l)
      Overrides the trace color using HSL values.
      Parameters:
      h - hue in degrees (0-360)
      s - saturation as percentage (0-100)
      l - lightness as percentage (0-100)
      Returns:
      this builder for method chaining

    • timestampRgb

      public ANSIBuilder timestampRgb(int r, int g, int b)
      Overrides the timestamp color using RGB values (true color).
      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      this builder for method chaining

    • timestampHex

      public ANSIBuilder timestampHex(String hex)
      Overrides the timestamp color using a hex color value.
      Parameters:
      hex - the color in hex format
      Returns:
      this builder for method chaining

    • timestampHsl

      public ANSIBuilder timestampHsl(float h, float s, float l)
      Overrides the timestamp color using HSL values.
      Parameters:
      h - hue in degrees (0-360)
      s - saturation as percentage (0-100)
      l - lightness as percentage (0-100)
      Returns:
      this builder for method chaining

    • messageRgb

      public ANSIBuilder messageRgb(int r, int g, int b)
      Overrides the message color using RGB values (true color).
      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      this builder for method chaining

    • messageHex

      public ANSIBuilder messageHex(String hex)
      Overrides the message color using a hex color value.
      Parameters:
      hex - the color in hex format
      Returns:
      this builder for method chaining

    • messageHsl

      public ANSIBuilder messageHsl(float h, float s, float l)
      Overrides the message color using HSL values.
      Parameters:
      h - hue in degrees (0-360)
      s - saturation as percentage (0-100)
      l - lightness as percentage (0-100)
      Returns:
      this builder for method chaining

    • categoryRgb

      public ANSIBuilder categoryRgb(int r, int g, int b)
      Overrides the category color using RGB values (true color).
      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      this builder for method chaining

    • categoryHex

      public ANSIBuilder categoryHex(String hex)
      Overrides the category color using a hex color value.
      Parameters:
      hex - the color in hex format
      Returns:
      this builder for method chaining

    • categoryHsl

      public ANSIBuilder categoryHsl(float h, float s, float l)
      Overrides the category color using HSL values.
      Parameters:
      h - hue in degrees (0-360)
      s - saturation as percentage (0-100)
      l - lightness as percentage (0-100)
      Returns:
      this builder for method chaining

    • threadNameRgb

      public ANSIBuilder threadNameRgb(int r, int g, int b)
      Overrides the thread name color using RGB values (true color).
      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      this builder for method chaining

    • threadNameHex

      public ANSIBuilder threadNameHex(String hex)
      Overrides the thread name color using a hex color value.
      Parameters:
      hex - the color in hex format
      Returns:
      this builder for method chaining

    • threadNameHsl

      public ANSIBuilder threadNameHsl(float h, float s, float l)
      Overrides the thread name color using HSL values.
      Parameters:
      h - hue in degrees (0-360)
      s - saturation as percentage (0-100)
      l - lightness as percentage (0-100)
      Returns:
      this builder for method chaining

    • fatalRgb

      public ANSIBuilder fatalRgb(int r, int g, int b)
      Overrides the fatal color using RGB values (true color).
      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      this builder for method chaining

    • fatalHex

      public ANSIBuilder fatalHex(String hex)
      Overrides the fatal color using a hex color value.
      Parameters:
      hex - the color in hex format
      Returns:
      this builder for method chaining

    • fatalHsl

      public ANSIBuilder fatalHsl(float h, float s, float l)
      Overrides the fatal color using HSL values.
      Parameters:
      h - hue in degrees (0-360)
      s - saturation as percentage (0-100)
      l - lightness as percentage (0-100)
      Returns:
      this builder for method chaining

    • resetColors

      public ANSIBuilder resetColors()
      Resets all colors and text styles to default.
      Returns:
      this builder for method chaining

    • clear

      public ANSIBuilder clear()
      Clears the builder content and resets all formatting.
      Returns:
      this builder for method chaining

    • reset

      public ANSIBuilder reset()
      Clears the builder content and resets all formatting, identical to clear()
      Returns:
      this builder for method chaining

    • text

      public ANSIBuilder text(ANSIBuilder.Color color)
      Sets the foreground text color.
      Parameters:
      color - the color to use for text
      Returns:
      this builder for method chaining

    • textType

      public ANSIBuilder textType(ANSIBuilder.TextType type)
      Sets the text type/style.
      Parameters:
      type - the text type to apply
      Returns:
      this builder for method chaining

    • bg

      public ANSIBuilder bg(ANSIBuilder.Color color)
      Sets the background color.
      Parameters:
      color - the color to use for background
      Returns:
      this builder for method chaining

    • blackText

      public ANSIBuilder blackText()
      Sets foreground text color to black.
      Returns:
      this builder for method chaining

    • redText

      public ANSIBuilder redText()
      Sets foreground text color to red.
      Returns:
      this builder for method chaining

    • greenText

      public ANSIBuilder greenText()
      Sets foreground text color to green.
      Returns:
      this builder for method chaining

    • yellowText

      public ANSIBuilder yellowText()
      Sets foreground text color to yellow.
      Returns:
      this builder for method chaining

    • blueText

      public ANSIBuilder blueText()
      Sets foreground text color to blue.
      Returns:
      this builder for method chaining

    • magentaText

      public ANSIBuilder magentaText()
      Sets foreground text color to magenta.
      Returns:
      this builder for method chaining

    • cyanText

      public ANSIBuilder cyanText()
      Sets foreground text color to cyan.
      Returns:
      this builder for method chaining

    • whiteText

      public ANSIBuilder whiteText()
      Sets foreground text color to white.
      Returns:
      this builder for method chaining

    • defaultText

      public ANSIBuilder defaultText()
      Sets foreground text color to default.
      Returns:
      this builder for method chaining

    • blackBg

      public ANSIBuilder blackBg()
      Sets background color to black.
      Returns:
      this builder for method chaining

    • redBg

      public ANSIBuilder redBg()
      Sets background color to red.
      Returns:
      this builder for method chaining

    • greenBg

      public ANSIBuilder greenBg()
      Sets background color to green.
      Returns:
      this builder for method chaining

    • yellowBg

      public ANSIBuilder yellowBg()
      Sets background color to yellow.
      Returns:
      this builder for method chaining

    • blueBg

      public ANSIBuilder blueBg()
      Sets background color to blue.
      Returns:
      this builder for method chaining

    • magentaBg

      public ANSIBuilder magentaBg()
      Sets background color to magenta.
      Returns:
      this builder for method chaining

    • cyanBg

      public ANSIBuilder cyanBg()
      Sets background color to cyan.
      Returns:
      this builder for method chaining

    • whiteBg

      public ANSIBuilder whiteBg()
      Sets background color to white.
      Returns:
      this builder for method chaining

    • defaultBg

      public ANSIBuilder defaultBg()
      Sets background color to default.
      Returns:
      this builder for method chaining

    • blackText

      public ANSIBuilder blackText(String text)
      Appends text with black foreground color and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • redText

      public ANSIBuilder redText(String text)
      Appends text with red foreground color and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • greenText

      public ANSIBuilder greenText(String text)
      Appends text with green foreground color and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • yellowText

      public ANSIBuilder yellowText(String text)
      Appends text with yellow foreground color and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • blueText

      public ANSIBuilder blueText(String text)
      Appends text with blue foreground color and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • magentaText

      public ANSIBuilder magentaText(String text)
      Appends text with magenta foreground color and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • cyanText

      public ANSIBuilder cyanText(String text)
      Appends text with cyan foreground color and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • whiteText

      public ANSIBuilder whiteText(String text)
      Appends text with white foreground color and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • defaultText

      public ANSIBuilder defaultText(String text)
      Appends text with default foreground color and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • blackBg

      public ANSIBuilder blackBg(String text)
      Appends text with black background and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • redBg

      public ANSIBuilder redBg(String text)
      Appends text with red background and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • greenBg

      public ANSIBuilder greenBg(String text)
      Appends text with green background and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • yellowBg

      public ANSIBuilder yellowBg(String text)
      Appends text with yellow background and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • blueBg

      public ANSIBuilder blueBg(String text)
      Appends text with blue background and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • magentaBg

      public ANSIBuilder magentaBg(String text)
      Appends text with magenta background and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • cyanBg

      public ANSIBuilder cyanBg(String text)
      Appends text with cyan background and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • whiteBg

      public ANSIBuilder whiteBg(String text)
      Appends text with white background and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • defaultBg

      public ANSIBuilder defaultBg(String text)
      Appends text with default background and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • append

      public ANSIBuilder append(String data)
      Appends a string to the builder.
      Parameters:
      data - the string to append
      Returns:
      this builder for method chaining

    • append

      public ANSIBuilder append(int data)
      Appends an integer to the builder.
      Parameters:
      data - the integer to append
      Returns:
      this builder for method chaining

    • append

      public ANSIBuilder append(char data)
      Appends a character to the builder.
      Parameters:
      data - the character to append
      Returns:
      this builder for method chaining

    • append

      public ANSIBuilder append(CharSequence data)
      Appends a CharSequence to the builder.
      Parameters:
      data - the CharSequence to append
      Returns:
      this builder for method chaining

    • append

      public ANSIBuilder append(char[] data)
      Appends a character array to the builder.
      Parameters:
      data - the character array to append
      Returns:
      this builder for method chaining

    • append

      public ANSIBuilder append(Object data)
      Appends an Object to the builder.
      Parameters:
      data - the Object to append
      Returns:
      this builder for method chaining

    • append

      public ANSIBuilder append(StringBuilder data)
      Appends a StringBuilder to the builder.
      Parameters:
      data - the StringBuilder to append
      Returns:
      this builder for method chaining

    • append

      public ANSIBuilder append(float data)
      Appends a float to the builder.
      Parameters:
      data - the float to append
      Returns:
      this builder for method chaining

    • append

      public ANSIBuilder append(double data)
      Appends a double to the builder.
      Parameters:
      data - the double to append
      Returns:
      this builder for method chaining

    • append

      public ANSIBuilder append(long data)
      Appends a long to the builder.
      Parameters:
      data - the long to append
      Returns:
      this builder for method chaining

    • bold

      public ANSIBuilder bold()
      Enables bold text style.
      Returns:
      this builder for method chaining

    • boldOff

      public ANSIBuilder boldOff()
      Disables bold text style.
      Returns:
      this builder for method chaining

    • faint

      public ANSIBuilder faint()
      Enables faint (dim) text style.
      Returns:
      this builder for method chaining

    • faintOff

      public ANSIBuilder faintOff()
      Disables faint text style.
      Returns:
      this builder for method chaining

    • italic

      public ANSIBuilder italic()
      Enables italic text style.
      Returns:
      this builder for method chaining

    • italicOff

      public ANSIBuilder italicOff()
      Disables italic text style.
      Returns:
      this builder for method chaining

    • underline

      public ANSIBuilder underline()
      Enables underline text style.
      Returns:
      this builder for method chaining

    • underlineOff

      public ANSIBuilder underlineOff()
      Disables underline text style.
      Returns:
      this builder for method chaining

    • blink

      public ANSIBuilder blink()
      Enables blinking text style.
      Returns:
      this builder for method chaining

    • blinkOff

      public ANSIBuilder blinkOff()
      Disables blinking text style.
      Returns:
      this builder for method chaining

    • invert

      public ANSIBuilder invert()
      Enables inverted (reverse video) text style.
      Returns:
      this builder for method chaining

    • invertOff

      public ANSIBuilder invertOff()
      Disables inverted text style.
      Returns:
      this builder for method chaining

    • conceal

      public ANSIBuilder conceal()
      Enables concealed (hidden) text style.
      Returns:
      this builder for method chaining

    • concealOff

      public ANSIBuilder concealOff()
      Disables concealed text style.
      Returns:
      this builder for method chaining

    • crossedOut

      public ANSIBuilder crossedOut()
      Enables crossed-out (strikethrough) text style.
      Returns:
      this builder for method chaining

    • crossedOutOff

      public ANSIBuilder crossedOutOff()
      Disables crossed-out text style.
      Returns:
      this builder for method chaining

    • newline

      public ANSIBuilder newline()
      Appends a newline to the builder.
      Returns:
      this builder for method chaining

    • bold

      public ANSIBuilder bold(String text)
      Appends text with bold style and disables bold after.
      Parameters:
      text - the text to append in bold
      Returns:
      this builder for method chaining

    • faint

      public ANSIBuilder faint(String text)
      Appends text with faint style and resets after.
      Parameters:
      text - the text to append in faint style
      Returns:
      this builder for method chaining

    • italic

      public ANSIBuilder italic(String text)
      Appends text with italic style and disables italic after.
      Parameters:
      text - the text to append in italic
      Returns:
      this builder for method chaining

    • underline

      public ANSIBuilder underline(String text)
      Appends text with underline style and disables underline after.
      Parameters:
      text - the text to append with underline
      Returns:
      this builder for method chaining

    • blink

      public ANSIBuilder blink(String text)
      Appends text with blink style and disables blink after.
      Parameters:
      text - the text to append with blink
      Returns:
      this builder for method chaining

    • invert

      public ANSIBuilder invert(String text)
      Appends text with inverted style and disables invert after.
      Parameters:
      text - the text to append with invert
      Returns:
      this builder for method chaining

    • conceal

      public ANSIBuilder conceal(String text)
      Appends text with concealed style and disables conceal after.
      Parameters:
      text - the text to append concealed
      Returns:
      this builder for method chaining

    • crossedOut

      public ANSIBuilder crossedOut(String text)
      Appends text with crossed-out style and disables it after.
      Parameters:
      text - the text to append crossed out
      Returns:
      this builder for method chaining

    • bright

      public ANSIBuilder bright()
      Enables bright (high intensity) mode for subsequent colors.

      When bright mode is enabled, basic colors (red, green, etc.) will use their bright variants (codes 90-97 instead of 30-37).

      Example: 

       ANSIBuilder.builder().bright().redText("Bright red").toString();
      Returns:
      this builder for method chaining

    • brightOff

      public ANSIBuilder brightOff()
      Disables bright mode, returning to normal intensity colors.
      Returns:
      this builder for method chaining

    • color256

      public ANSIBuilder color256(int index)
      Sets the foreground color using the 256-color palette.

      The 256-color palette is organized as:

      • 0-7: Standard colors (same as basic ANSI)
      • 8-15: High intensity colors
      • 16-231: 6x6x6 color cube
      • 232-255: Grayscale from dark to light
      Parameters:
      index - the color index (0-255)
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if index is out of range

    • bg256

      public ANSIBuilder bg256(int index)
      Sets the background color using the 256-color palette.
      Parameters:
      index - the color index (0-255)
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if index is out of range

    • color256

      public ANSIBuilder color256(int index, String text)
      Appends text with the specified 256-color foreground and resets.
      Parameters:
      index - the color index (0-255)
      text - the text to append
      Returns:
      this builder for method chaining

    • bg256

      public ANSIBuilder bg256(int index, String text)
      Appends text with the specified 256-color background and resets.
      Parameters:
      index - the color index (0-255)
      text - the text to append
      Returns:
      this builder for method chaining

    • rgb

      public ANSIBuilder rgb(int r, int g, int b)
      Sets the foreground color using RGB values (true color).

      True color support requires a terminal that supports 24-bit colors. Use TerminalColorCapability.getColorDepth() to check if the terminal supports true color.

      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if any component is out of range

    • bgRgb

      public ANSIBuilder bgRgb(int r, int g, int b)
      Sets the background color using RGB values (true color).
      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if any component is out of range

    • hex

      public ANSIBuilder hex(String hex)
      Sets the foreground color using a hex color value.
      Parameters:
      hex - the color in hex format (e.g., "#FF5733" or "FF5733")
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if the hex string is invalid

    • bgHex

      public ANSIBuilder bgHex(String hex)
      Sets the background color using a hex color value.
      Parameters:
      hex - the color in hex format (e.g., "#FF5733" or "FF5733")
      Returns:
      this builder for method chaining
      Throws:
      IllegalArgumentException - if the hex string is invalid

    • rgb

      public ANSIBuilder rgb(int r, int g, int b, String text)
      Appends text with the specified RGB foreground color and resets.
      Parameters:
      r - red component (0-255)
      g - green component (0-255)
      b - blue component (0-255)
      text - the text to append
      Returns:
      this builder for method chaining

    • hex

      public ANSIBuilder hex(String hex, String text)
      Appends text with the specified hex foreground color and resets.
      Parameters:
      hex - the color in hex format
      text - the text to append
      Returns:
      this builder for method chaining

    • hsl

      public ANSIBuilder hsl(float h, float s, float l)
      Sets the foreground color using HSL values (converted to RGB true color).

      HSL (Hue, Saturation, Lightness) is often more intuitive for color selection:

      • Hue: Position on color wheel (0=red, 60=yellow, 120=green, 180=cyan, 240=blue, 300=magenta)
      • Saturation: Color intensity (0=gray, 100=vivid)
      • Lightness: Brightness (0=black, 50=pure color, 100=white)

      Example for creating visible colors on dark terminals: 

       // Use high lightness (65-75) for dark backgrounds
 ANSIBuilder.builder().hsl(0, 80, 65).append("Red on dark").toString();
      Parameters:
      h - hue in degrees (0-360)
      s - saturation as percentage (0-100)
      l - lightness as percentage (0-100)
      Returns:
      this builder for method chaining

    • bgHsl

      public ANSIBuilder bgHsl(float h, float s, float l)
      Sets the background color using HSL values (converted to RGB true color).
      Parameters:
      h - hue in degrees (0-360)
      s - saturation as percentage (0-100)
      l - lightness as percentage (0-100)
      Returns:
      this builder for method chaining

    • hsl

      public ANSIBuilder hsl(float h, float s, float l, String text)
      Appends text with the specified HSL foreground color and resets.
      Parameters:
      h - hue in degrees (0-360)
      s - saturation as percentage (0-100)
      l - lightness as percentage (0-100)
      text - the text to append
      Returns:
      this builder for method chaining

    • bgHsl

      public ANSIBuilder bgHsl(float h, float s, float l, String text)
      Appends text with the specified HSL background color and resets.
      Parameters:
      h - hue in degrees (0-360)
      s - saturation as percentage (0-100)
      l - lightness as percentage (0-100)
      text - the text to append
      Returns:
      this builder for method chaining

    • error

      public ANSIBuilder error()
      Sets the foreground color to the theme-appropriate error color (red).

      Color priority: RGB override > code override > capability > default.

      Returns:
      this builder for method chaining

    • error

      public ANSIBuilder error(String text)
      Appends text with error styling (red) and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • success

      public ANSIBuilder success()
      Sets the foreground color to the theme-appropriate success color (green).

      Color priority: RGB override > code override > capability > default.

      Returns:
      this builder for method chaining

    • success

      public ANSIBuilder success(String text)
      Appends text with success styling (green) and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • warning

      public ANSIBuilder warning()
      Sets the foreground color to the theme-appropriate warning color (yellow).

      Color priority: RGB override > code override > capability > default.

      Returns:
      this builder for method chaining

    • warning

      public ANSIBuilder warning(String text)
      Appends text with warning styling (yellow) and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • info

      public ANSIBuilder info()
      Sets the foreground color to the theme-appropriate info color (green).

      Color priority: RGB override > code override > capability > default.

      Returns:
      this builder for method chaining

    • info

      public ANSIBuilder info(String text)
      Appends text with info styling (green) and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • debug

      public ANSIBuilder debug()
      Sets the foreground color to the theme-appropriate debug color (cyan).

      Color priority: RGB override > code override > capability > default.

      Debug uses cyan, aligning with JBoss LogManager's color spectrum where DEBUG maps to teal/cyan:

      • For dark themes: bright cyan (96)
      • For light themes: dark cyan (36)
      Returns:
      this builder for method chaining

    • debug

      public ANSIBuilder debug(String text)
      Appends text with debug styling and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • trace

      public ANSIBuilder trace()
      Sets the foreground color to the theme-appropriate trace color.

      Color priority: RGB override > code override > capability > default.

      Trace is the least prominent log level, using a dim gray color that doesn't distract from more important messages:

      • For dark themes: 256-color gray (242) - visible but dimmer than debug
      • For light themes: gray (90) - very subdued
      Returns:
      this builder for method chaining

    • trace

      public ANSIBuilder trace(String text)
      Appends text with trace styling and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • timestamp

      public ANSIBuilder timestamp()
      Sets the foreground color to the theme-appropriate timestamp color (gray).

      Color priority: RGB override > code override > capability > default.

      Timestamps use a neutral gray color that is visible but doesn't distract from the main message content.

      Returns:
      this builder for method chaining

    • timestamp

      public ANSIBuilder timestamp(String text)
      Appends text with timestamp styling (gray) and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • message

      public ANSIBuilder message()
      Sets the foreground color to the theme-appropriate message color (magenta).

      Color priority: RGB override > code override > capability > default.

      Message color is used for highlighted or emphasized message content that should stand out from regular text.

      Returns:
      this builder for method chaining

    • message

      public ANSIBuilder message(String text)
      Appends text with message styling (magenta) and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • category

      public ANSIBuilder category()
      Sets the foreground color to the theme-appropriate category color (blue).

      Color priority: RGB override > code override > capability > default.

      Category color is used for package/class names (logger categories) in log output. Aligns with JBoss LogManager's ColorPatternFormatter CATEGORY item (HSL 220°, 0.9, 0.8 — a blue hue).

      Returns:
      this builder for method chaining

    • category

      public ANSIBuilder category(String text)
      Appends text with category styling (blue) and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • threadName

      public ANSIBuilder threadName()
      Sets the foreground color to the theme-appropriate thread name color (green).

      Color priority: RGB override > code override > capability > default.

      Thread name color is used for thread identifiers in log output. Aligns with JBoss LogManager's ColorPatternFormatter THREAD_NAME item (HSL 120°, 0.429, 0.8 — a muted green).

      Returns:
      this builder for method chaining

    • threadName

      public ANSIBuilder threadName(String text)
      Appends text with thread name styling (green) and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • fatal

      public ANSIBuilder fatal()
      Sets the foreground color to the theme-appropriate fatal color (red).

      Color priority: RGB override > code override > capability > default.

      Fatal color is used for FATAL-level log messages — the most severe log level. Uses the same red base as error, but is typically distinguished by bold styling in usage.

      Returns:
      this builder for method chaining

    • fatal

      public ANSIBuilder fatal(String text)
      Appends text with fatal styling (red) and resets.
      Parameters:
      text - the text to append
      Returns:
      this builder for method chaining

    • textCode

      public ANSIBuilder textCode(int code)
      Sets the foreground color using a raw ANSI color code.

      This allows direct control over the ANSI color code used:

      • 30-37: Standard foreground colors
      • 90-97: Bright foreground colors
      Parameters:
      code - the ANSI color code
      Returns:
      this builder for method chaining

    • bgCode

      public ANSIBuilder bgCode(int code)
      Sets the background color using a raw ANSI color code.

      This allows direct control over the ANSI color code used:

      • 40-47: Standard background colors
      • 100-107: Bright background colors
      Parameters:
      code - the ANSI color code
      Returns:
      this builder for method chaining

    • toString

      public String toString()
      Returns the built string with ANSI formatting.
      Overrides:
      toString in class Object
      Returns:
      the formatted string

    • toLine

      public String toLine()
      Returns the built string with ANSI formatting followed by a newline.

      This is a convenience method equivalent to toString() + "\n".

      Returns:
      the formatted string with a trailing newline

    • appendLine

      public ANSIBuilder appendLine(String text)
      Appends text followed by a newline.

      This is a convenience method equivalent to append(text).newline().

      Parameters:
      text - the text to append before the newline
      Returns:
      this builder for method chaining