Package org.jline.utils

Class AttributedCharSequence

java.lang.Object

org.jline.utils.AttributedCharSequence

All Implemented Interfaces:

CharSequence

Direct Known Subclasses:

AttributedString, AttributedStringBuilder

public abstract class AttributedCharSequence
extends Object
implements 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 enum	AttributedCharSequence.ForceMode	Enum defining color mode forcing options for ANSI rendering.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	TRUE_COLORS

Constructor Summary

Constructors

Constructor	Description
AttributedCharSequence()

Method Summary

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.
List<AttributedString>	columnSplitLength(int columns)	Splits this attributed string into multiple lines based on column width.
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.
String	toAnsi()	Converts this attributed string to an ANSI escape sequence string.
String	toAnsi(int colors, boolean force256colors)	Deprecated.
String	toAnsi(int colors, boolean force256colors, String altIn, String altOut)	Deprecated.
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.
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.
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.
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.
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, isEmpty, length

Field Details

TRUE_COLORS

public static final int TRUE_COLORS

See Also:

• Constant Field Values

Constructor Details

AttributedCharSequence

public AttributedCharSequence()

Method Details

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 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 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 String toAnsi(int colors,
 boolean force256colors)

Deprecated.

toAnsi

@Deprecated
public String toAnsi(int colors,
 boolean force256colors,
 String altIn,
 String altOut)

Deprecated.

toAnsi

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

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

public abstract AttributedString subSequence(int start,
 int end)

Specified by:

subSequence in interface 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:

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

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 range

length - 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

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 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 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 String toString()

Specified by:

toString in interface CharSequence

Overrides:

toString in class 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