Class AttributedCharSequence
- All Implemented Interfaces:
CharSequence
- Direct Known Subclasses:
AttributedString
,AttributedStringBuilder
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 ClassesModifier and TypeClassDescriptionstatic enum
Enum defining color mode forcing options for ANSI rendering. -
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprotected 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
Returns the display width of this attributed string in columns.columnSplitLength
(int columns) Splits this attributed string into multiple lines based on column width.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.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
Prints this attributed string to the specified terminal.void
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) substring
(int start, int end) Returns a new AttributedString that is a substring of this attributed string.toAnsi()
Converts this attributed string to an ANSI escape sequence string.toAnsi
(int colors, boolean force256colors) Deprecated.Deprecated.toAnsi
(int colors, AttributedCharSequence.ForceMode force) Converts this attributed string to an ANSI escape sequence string with the specified color capabilities and force mode.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.toAnsi
(int colors, AttributedCharSequence.ForceMode force, ColorPalette palette, String altIn, 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.Converts this attributed string to an ANSI escape sequence string appropriate for the specified terminal.Converts this attributed character sequence to an AttributedString.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, isEmpty, length
-
Field Details
-
TRUE_COLORS
public static final int TRUE_COLORS- See Also:
-
-
Constructor Details
-
AttributedCharSequence
public AttributedCharSequence()
-
-
Method Details
-
print
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
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
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
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. -
toAnsi
Deprecated. -
toAnsi
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
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 renderingpalette
- the color palette to use for color conversion- Returns:
- a string with ANSI escape sequences representing this attributed string
-
toAnsi
public String toAnsi(int colors, AttributedCharSequence.ForceMode force, ColorPalette palette, String altIn, 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 renderingpalette
- the color palette to use for color conversion, or null for the default palettealtIn
- the sequence to enable the alternate character set, or null to disablealtOut
- 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. -
roundColor
Deprecated. -
roundRgbColor
Deprecated. -
styleAt
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:
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:
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:
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:
IndexOutOfBoundsException
- if the index is out of range
-
subSequence
- Specified by:
subSequence
in interfaceCharSequence
-
substring
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, inclusiveend
- the end index, exclusive- Returns:
- the specified substring with its attributes
- Throws:
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 interfaceCharSequence
-
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:
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:
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 rangelength
- the length of the range in characters- Returns:
- the number of Unicode code points in the specified range
- Throws:
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
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
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)
withincludeNewlines=false
anddelayLineWrap=true
.- Parameters:
columns
- the maximum width of each line in columns- Returns:
- a list of attributed strings, each representing a line
-
columnSplitLength
public 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 columnsincludeNewlines
- whether to include newline characters in the resulting linesdelayLineWrap
- whether to delay line wrapping until the last possible moment- Returns:
- a list of attributed strings, each representing a line
-
toString
- Specified by:
toString
in interfaceCharSequence
- Overrides:
toString
in classObject
-
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
-