Class AttributedCharSequence

  • All Implemented Interfaces:
    java.lang.CharSequence
    Direct Known Subclasses:
    AttributedString, AttributedStringBuilder

    public abstract class AttributedCharSequence
    extends java.lang.Object
    implements java.lang.CharSequence
    A character sequence with ANSI style attributes.

    The AttributedCharSequence class is an abstract base class for character sequences that have ANSI style attributes (colors, bold, underline, etc.) associated with each character. It provides methods for rendering the character sequence with its attributes to various outputs, such as ANSI terminals, non-ANSI terminals, and plain text.

    This class serves as the foundation for styled text in JLine, allowing for rich text formatting in terminal applications. It is extended by concrete classes like AttributedString and AttributedStringBuilder that provide specific implementations for different use cases.

    The class provides methods to:

    • Convert the sequence to a plain string without attributes
    • Render the sequence with ANSI escape codes for compatible terminals
    • Render the sequence for terminals with limited attribute support
    • Calculate the visible length of the sequence (excluding escape codes)
    • Extract substrings while preserving attributes
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  AttributedCharSequence.ForceMode
      Enum defining color mode forcing options for ANSI rendering.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int TRUE_COLORS  
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      protected abstract char[] buffer()  
      char charAt​(int index)  
      int codePointAt​(int index)
      Returns the code point at the specified index in this attributed string.
      int codePointBefore​(int index)
      Returns the code point before the specified index in this attributed string.
      int codePointCount​(int index, int length)
      Returns the number of Unicode code points in the specified range of this attributed string.
      int columnLength()
      Returns the display width of this attributed string in columns.
      java.util.List<AttributedString> columnSplitLength​(int columns)
      Splits this attributed string into multiple lines based on column width.
      java.util.List<AttributedString> columnSplitLength​(int columns, boolean includeNewlines, boolean delayLineWrap)
      Splits this attributed string into multiple lines based on column width, with options for handling newlines and line wrapping.
      AttributedString columnSubSequence​(int start, int stop)
      Returns a subsequence of this attributed string based on column positions.
      boolean contains​(char c)
      Returns whether this attributed string contains the specified character.
      boolean isHidden​(int index)
      Returns whether the character at the specified index is hidden.
      protected abstract int offset()  
      void print​(Terminal terminal)
      Prints this attributed string to the specified terminal.
      void println​(Terminal terminal)
      Prints this attributed string to the specified terminal, followed by a line break.
      static int rgbColor​(int col)
      Deprecated.
      static int roundColor​(int col, int max)
      Deprecated.
      static int roundRgbColor​(int r, int g, int b, int max)
      Deprecated.
      int runLimit​(int index)
      Returns the limit index of the run of characters with the same style that includes the character at the specified index.
      int runStart​(int index)
      Returns the start index of the run of characters with the same style that includes the character at the specified index.
      abstract AttributedStyle styleAt​(int index)
      Returns the style at the specified index in this attributed string.
      abstract AttributedString subSequence​(int start, int end)  
      AttributedString substring​(int start, int end)
      Returns a new AttributedString that is a substring of this attributed string.
      java.lang.String toAnsi()
      Converts this attributed string to an ANSI escape sequence string.
      java.lang.String toAnsi​(int colors, boolean force256colors)
      Deprecated.
      java.lang.String toAnsi​(int colors, boolean force256colors, java.lang.String altIn, java.lang.String altOut)
      Deprecated.
      java.lang.String toAnsi​(int colors, AttributedCharSequence.ForceMode force)
      Converts this attributed string to an ANSI escape sequence string with the specified color capabilities and force mode.
      java.lang.String toAnsi​(int colors, AttributedCharSequence.ForceMode force, ColorPalette palette)
      Converts this attributed string to an ANSI escape sequence string with the specified color capabilities, force mode, and color palette.
      java.lang.String toAnsi​(int colors, AttributedCharSequence.ForceMode force, ColorPalette palette, java.lang.String altIn, java.lang.String altOut)
      Converts this attributed string to an ANSI escape sequence string with the specified color capabilities, force mode, color palette, and alternate character set sequences.
      java.lang.String toAnsi​(Terminal terminal)
      Converts this attributed string to an ANSI escape sequence string appropriate for the specified terminal.
      AttributedString toAttributedString()
      Converts this attributed character sequence to an AttributedString.
      java.lang.String toString()  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
      • Methods inherited from interface java.lang.CharSequence

        chars, codePoints, length
    • Constructor Detail

      • AttributedCharSequence

        public AttributedCharSequence()
    • Method Detail

      • print

        public void print​(Terminal terminal)
        Prints this attributed string to the specified terminal.

        This method renders the attributed string with appropriate ANSI escape sequences for the specified terminal and prints it to the terminal's writer.

        Parameters:
        terminal - the terminal to print to
      • println

        public void println​(Terminal terminal)
        Prints this attributed string to the specified terminal, followed by a line break.

        This method renders the attributed string with appropriate ANSI escape sequences for the specified terminal and prints it to the terminal's writer, followed by a line break.

        Parameters:
        terminal - the terminal to print to
      • toAnsi

        public java.lang.String toAnsi()
        Converts this attributed string to an ANSI escape sequence string.

        This method renders the attributed string with ANSI escape sequences to represent the text attributes (colors, bold, underline, etc.). It uses default color capabilities (256 colors) and no forced color mode.

        Returns:
        a string with ANSI escape sequences representing this attributed string
        See Also:
        toAnsi(Terminal)
      • toAnsi

        public java.lang.String toAnsi​(Terminal terminal)
        Converts this attributed string to an ANSI escape sequence string appropriate for the specified terminal.

        This method renders the attributed string with ANSI escape sequences to represent the text attributes (colors, bold, underline, etc.), taking into account the capabilities of the specified terminal.

        If the terminal is a dumb terminal (Terminal.TYPE_DUMB), this method returns the plain text without any escape sequences.

        Parameters:
        terminal - the terminal to generate ANSI sequences for, or null to use default capabilities
        Returns:
        a string with ANSI escape sequences representing this attributed string
      • toAnsi

        @Deprecated
        public java.lang.String toAnsi​(int colors,
                                       boolean force256colors)
        Deprecated.
      • toAnsi

        @Deprecated
        public java.lang.String toAnsi​(int colors,
                                       boolean force256colors,
                                       java.lang.String altIn,
                                       java.lang.String altOut)
        Deprecated.
      • toAnsi

        public java.lang.String toAnsi​(int colors,
                                       AttributedCharSequence.ForceMode force)
        Converts this attributed string to an ANSI escape sequence string with the specified color capabilities and force mode.

        This method renders the attributed string with ANSI escape sequences using the specified number of colors and force mode.

        Parameters:
        colors - the number of colors to use (8, 256, or 16777216 for true colors)
        force - the force mode to use for color rendering
        Returns:
        a string with ANSI escape sequences representing this attributed string
      • toAnsi

        public java.lang.String toAnsi​(int colors,
                                       AttributedCharSequence.ForceMode force,
                                       ColorPalette palette)
        Converts this attributed string to an ANSI escape sequence string with the specified color capabilities, force mode, and color palette.

        This method renders the attributed string with ANSI escape sequences using the specified number of colors, force mode, and color palette.

        Parameters:
        colors - the number of colors to use (8, 256, or 16777216 for true colors)
        force - the force mode to use for color rendering
        palette - the color palette to use for color conversion
        Returns:
        a string with ANSI escape sequences representing this attributed string
      • toAnsi

        public java.lang.String toAnsi​(int colors,
                                       AttributedCharSequence.ForceMode force,
                                       ColorPalette palette,
                                       java.lang.String altIn,
                                       java.lang.String altOut)
        Converts this attributed string to an ANSI escape sequence string with the specified color capabilities, force mode, color palette, and alternate character set sequences.

        This method renders the attributed string with ANSI escape sequences using the specified number of colors, force mode, color palette, and alternate character set sequences for box drawing characters.

        Parameters:
        colors - the number of colors to use (8, 256, or 16777216 for true colors)
        force - the force mode to use for color rendering
        palette - the color palette to use for color conversion, or null for the default palette
        altIn - the sequence to enable the alternate character set, or null to disable
        altOut - the sequence to disable the alternate character set, or null to disable
        Returns:
        a string with ANSI escape sequences representing this attributed string
      • rgbColor

        @Deprecated
        public static int rgbColor​(int col)
        Deprecated.
      • roundColor

        @Deprecated
        public static int roundColor​(int col,
                                     int max)
        Deprecated.
      • roundRgbColor

        @Deprecated
        public static int roundRgbColor​(int r,
                                        int g,
                                        int b,
                                        int max)
        Deprecated.
      • styleAt

        public abstract AttributedStyle styleAt​(int index)
        Returns the style at the specified index in this attributed string.

        This method returns the AttributedStyle object associated with the character at the specified index in this attributed string.

        Parameters:
        index - the index of the character whose style to return
        Returns:
        the style at the specified index
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is out of range
      • isHidden

        public boolean isHidden​(int index)
        Returns whether the character at the specified index is hidden.

        This method checks if the character at the specified index has the hidden attribute set, which means it should not be displayed.

        Parameters:
        index - the index of the character to check
        Returns:
        true if the character is hidden, false otherwise
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is out of range
      • runStart

        public int runStart​(int index)
        Returns the start index of the run of characters with the same style that includes the character at the specified index.

        A run is a sequence of consecutive characters that have the same style. This method finds the first character in the run that includes the character at the specified index.

        Parameters:
        index - the index of a character in the run
        Returns:
        the start index of the run (inclusive)
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is out of range
      • runLimit

        public int runLimit​(int index)
        Returns the limit index of the run of characters with the same style that includes the character at the specified index.

        A run is a sequence of consecutive characters that have the same style. This method finds the index after the last character in the run that includes the character at the specified index.

        Parameters:
        index - the index of a character in the run
        Returns:
        the limit index of the run (exclusive)
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is out of range
      • subSequence

        public abstract AttributedString subSequence​(int start,
                                                     int end)
        Specified by:
        subSequence in interface java.lang.CharSequence
      • substring

        public AttributedString substring​(int start,
                                          int end)
        Returns a new AttributedString that is a substring of this attributed string.

        This method returns a new AttributedString that contains the characters and styles from this attributed string starting at the specified start index (inclusive) and ending at the specified end index (exclusive).

        This method is equivalent to subSequence(int, int) but returns an AttributedString instead of an AttributedCharSequence.

        Parameters:
        start - the start index, inclusive
        end - the end index, exclusive
        Returns:
        the specified substring with its attributes
        Throws:
        java.lang.IndexOutOfBoundsException - if start or end are negative, if end is greater than length(), or if start is greater than end
      • buffer

        protected abstract char[] buffer()
      • offset

        protected abstract int offset()
      • charAt

        public char charAt​(int index)
        Specified by:
        charAt in interface java.lang.CharSequence
      • codePointAt

        public int codePointAt​(int index)
        Returns the code point at the specified index in this attributed string.

        This method returns the Unicode code point at the specified index. If the character at the specified index is a high-surrogate code unit and the following character is a low-surrogate code unit, then the supplementary code point is returned; otherwise, the code unit at the specified index is returned.

        Parameters:
        index - the index to the code point
        Returns:
        the code point at the specified index
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is out of range
      • contains

        public boolean contains​(char c)
        Returns whether this attributed string contains the specified character.

        This method checks if the specified character appears in this attributed string.

        Parameters:
        c - the character to search for
        Returns:
        true if this attributed string contains the specified character, false otherwise
      • codePointBefore

        public int codePointBefore​(int index)
        Returns the code point before the specified index in this attributed string.

        This method returns the Unicode code point before the specified index. If the character before the specified index is a low-surrogate code unit and the character before that is a high-surrogate code unit, then the supplementary code point is returned; otherwise, the code unit before the specified index is returned.

        Parameters:
        index - the index following the code point that should be returned
        Returns:
        the Unicode code point value before the specified index
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is less than 1 or greater than length()
      • codePointCount

        public int codePointCount​(int index,
                                  int length)
        Returns the number of Unicode code points in the specified range of this attributed string.

        This method counts the number of Unicode code points in the range of this attributed string starting at the specified index (inclusive) and extending for the specified length. A surrogate pair is counted as one code point.

        Parameters:
        index - the index to the first character of the range
        length - the length of the range in characters
        Returns:
        the number of Unicode code points in the specified range
        Throws:
        java.lang.IndexOutOfBoundsException - if index is negative, or length is negative, or index + length is greater than length()
      • columnLength

        public int columnLength()
        Returns the display width of this attributed string in columns.

        This method calculates the display width of this attributed string in columns, taking into account wide characters (such as East Asian characters), zero-width characters (such as combining marks), and hidden characters. This is useful for determining how much space the string will occupy when displayed in a terminal.

        Hidden characters (those with the hidden attribute set) are not counted in the column length.

        Returns:
        the display width of this attributed string in columns
      • columnSubSequence

        public AttributedString columnSubSequence​(int start,
                                                  int stop)
        Returns a subsequence of this attributed string based on column positions.

        This method returns a subsequence of this attributed string that spans from the specified start column position (inclusive) to the specified stop column position (exclusive). Column positions are determined by the display width of characters, taking into account wide characters, zero-width characters, and hidden characters.

        This method is useful for extracting portions of text based on their visual position in a terminal, rather than their character indices.

        Parameters:
        start - the starting column position (inclusive)
        stop - the ending column position (exclusive)
        Returns:
        the subsequence spanning the specified column range
      • columnSplitLength

        public java.util.List<AttributedString> columnSplitLength​(int columns)
        Splits this attributed string into multiple lines based on column width.

        This method splits this attributed string into multiple lines, each with a maximum width of the specified number of columns. The splitting is done based on the display width of characters, taking into account wide characters, zero-width characters, and hidden characters.

        This is equivalent to calling columnSplitLength(int, boolean, boolean) with includeNewlines=false and delayLineWrap=true.

        Parameters:
        columns - the maximum width of each line in columns
        Returns:
        a list of attributed strings, each representing a line
      • columnSplitLength

        public java.util.List<AttributedString> columnSplitLength​(int columns,
                                                                  boolean includeNewlines,
                                                                  boolean delayLineWrap)
        Splits this attributed string into multiple lines based on column width, with options for handling newlines and line wrapping.

        This method splits this attributed string into multiple lines, each with a maximum width of the specified number of columns. The splitting is done based on the display width of characters, taking into account wide characters, zero-width characters, and hidden characters.

        Parameters:
        columns - the maximum width of each line in columns
        includeNewlines - whether to include newline characters in the resulting lines
        delayLineWrap - whether to delay line wrapping until the last possible moment
        Returns:
        a list of attributed strings, each representing a line
      • toString

        public java.lang.String toString()
        Specified by:
        toString in interface java.lang.CharSequence
        Overrides:
        toString in class java.lang.Object
      • toAttributedString

        public AttributedString toAttributedString()
        Converts this attributed character sequence to an AttributedString.

        This method creates a new AttributedString that contains all the characters and styles from this attributed character sequence. This is useful for converting an AttributedCharSequence to an immutable AttributedString.

        Returns:
        a new AttributedString containing all characters and styles from this sequence