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(" ")
         .success("[INFO]").append(" ")
         .message("Application started")
         .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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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 (blue/cyan).

      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 (blue/cyan) 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.

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

      Debug uses a subdued color that is less prominent than info level:

      • For dark themes: white (37) - visible but not colorful
      • For light themes: gray (90) - subdued
      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 (cyan).

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

      Timestamps use a subdued cyan 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 (cyan) 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

    • 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