Package org.jline.utils

Class AttributedString

java.lang.Object

org.jline.utils.AttributedCharSequence

org.jline.utils.AttributedString

All Implemented Interfaces:

CharSequence

public class AttributedString
extends AttributedCharSequence

An immutable character sequence with ANSI style attributes.

The AttributedString class represents a character sequence where each character has associated style attributes (colors, bold, underline, etc.). It extends AttributedCharSequence and provides an immutable implementation, making it safe to use in concurrent contexts.

Key features of this class include:

• Immutability - Once created, instances cannot be modified
• Memory efficiency - Substrings are created without any memory copy
• Rich styling - Support for foreground/background colors and text attributes
• Concatenation - Multiple AttributedStrings can be joined together
• Pattern matching - Regular expressions can be applied to find and extract parts

This class is commonly used for displaying styled text in terminal applications, such as prompts, menus, and highlighted output. For building AttributedStrings dynamically, use AttributedStringBuilder.

See Also:

• AttributedCharSequence
• AttributedStringBuilder
• AttributedStyle

Nested Class Summary

Nested classes/interfaces inherited from class org.jline.utils.AttributedCharSequence

AttributedCharSequence.ForceMode

Field Summary

Fields

Modifier and Type	Field	Description
static final AttributedString	EMPTY	An empty AttributedString with no characters.
static final AttributedString	NEWLINE	An AttributedString containing only a newline character.

Fields inherited from class org.jline.utils.AttributedCharSequence

TRUE_COLORS

Constructor Summary

Constructors

Constructor	Description
AttributedString(CharSequence str)	Creates a new AttributedString from the specified character sequence.
AttributedString(CharSequence str, int start, int end)	Creates a new AttributedString from a subsequence of the specified character sequence.
AttributedString(CharSequence str, int start, int end, AttributedStyle s)	Creates a new AttributedString from a subsequence of the specified character sequence with the specified style.
AttributedString(CharSequence str, AttributedStyle s)	Creates a new AttributedString from the specified character sequence with the specified style.

Method Summary

Modifier and Type	Method	Description
protected char[]	buffer()	Returns the character buffer for this attributed string.
boolean	equals(Object o)	Compares this AttributedString with another object for equality.
static AttributedString	fromAnsi(String ansi)	Creates an AttributedString from an ANSI-encoded string.
static AttributedString	fromAnsi(String ansi, int tabs)	Creates an AttributedString from an ANSI-encoded string with a specified tab size.
static AttributedString	fromAnsi(String ansi, List<Integer> tabs)	Creates an AttributedString from an ANSI-encoded string with custom tab stops.
static AttributedString	fromAnsi(String ansi, List<Integer> tabs, String altIn, String altOut)	Creates an AttributedString from an ANSI-encoded string with custom tab stops and alternate character set sequences.
static AttributedString	fromAnsi(String ansi, Terminal terminal)	Creates an AttributedString from an ANSI-encoded string, using terminal capabilities.
int	hashCode()	Returns a hash code for this AttributedString.
static AttributedString	join(AttributedString delimiter, Iterable<AttributedString> elements)	Joins an Iterable of AttributedString objects with a delimiter.
static AttributedString	join(AttributedString delimiter, AttributedString... elements)	Joins multiple AttributedString objects with a delimiter.
int	length()	Returns the length of this attributed string.
protected int	offset()	Returns the offset in the buffer where this attributed string starts.
static String	stripAnsi(String ansi)	Strips ANSI escape sequences from a string.
AttributedStyle	styleAt(int index)	Returns the style at the specified index in this attributed string.
AttributedString	styleMatches(Pattern pattern, AttributedStyle style)	Returns a new AttributedString with the specified style applied to all matches of the pattern.
AttributedString	subSequence(int start, int end)	Returns a new AttributedString that is a subsequence of this attributed string.

Methods inherited from class org.jline.utils.AttributedCharSequence

charAt, codePointAt, codePointBefore, codePointCount, columnLength, columnSplitLength, columnSplitLength, columnSubSequence, contains, isHidden, print, println, rgbColor, roundColor, roundRgbColor, runLimit, runStart, substring, toAnsi, toAnsi, toAnsi, toAnsi, toAnsi, toAnsi, toAnsi, toAttributedString, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.CharSequence

chars, codePoints, isEmpty

Field Details

EMPTY

public static final AttributedString EMPTY

An empty AttributedString with no characters.

NEWLINE

public static final AttributedString NEWLINE

An AttributedString containing only a newline character.

Constructor Details

AttributedString

public AttributedString(CharSequence str)

Creates a new AttributedString from the specified character sequence.

This constructor creates a new AttributedString containing the characters from the specified character sequence with default style (no attributes).

Parameters:

str - the character sequence to copy

AttributedString

public AttributedString(CharSequence str,
 int start,
 int end)

Creates a new AttributedString from a subsequence of the specified character sequence.

This constructor creates a new AttributedString containing the characters from the specified range of the character sequence with default style (no attributes).

Parameters:

str - the character sequence to copy

start - the index of the first character to copy (inclusive)

end - the index after the last character to copy (exclusive)

Throws:

InvalidParameterException - if end is less than start

AttributedString

public AttributedString(CharSequence str,
 AttributedStyle s)

Creates a new AttributedString from the specified character sequence with the specified style.

This constructor creates a new AttributedString containing the characters from the specified character sequence with the specified style applied to all characters.

Parameters:

str - the character sequence to copy

s - the style to apply to all characters, or null for default style

AttributedString

public AttributedString(CharSequence str,
 int start,
 int end,
 AttributedStyle s)

Creates a new AttributedString from a subsequence of the specified character sequence with the specified style.

This constructor creates a new AttributedString containing the characters from the specified range of the character sequence with the specified style applied to all characters.

If the character sequence is an AttributedString or AttributedStringBuilder, this constructor preserves the existing style information and applies the specified style on top of it (if not null).

Parameters:

str - the character sequence to copy

start - the index of the first character to copy (inclusive)

end - the index after the last character to copy (exclusive)

s - the style to apply to all characters, or null to preserve existing styles

Throws:

InvalidParameterException - if end is less than start

Method Details

fromAnsi

public static AttributedString fromAnsi(String ansi)

Creates an AttributedString from an ANSI-encoded string.

This method parses the ANSI escape sequences in the input string and creates an AttributedString with the corresponding styles. This is useful for converting ANSI-colored output from external commands into styled text that can be displayed in the terminal.

Parameters:

ansi - the ANSI-encoded string to parse

Returns:

an AttributedString with styles based on the ANSI escape sequences

See Also:

• fromAnsi(String, Terminal)

fromAnsi

public static AttributedString fromAnsi(String ansi,
 int tabs)

Creates an AttributedString from an ANSI-encoded string with a specified tab size.

This method parses the ANSI escape sequences in the input string and creates an AttributedString with the corresponding styles. It also handles tab characters according to the specified tab size.

Parameters:

ansi - the ANSI-encoded string to parse

tabs - the tab size in columns

Returns:

an AttributedString with styles based on the ANSI escape sequences

fromAnsi

public static AttributedString fromAnsi(String ansi,
 List<Integer> tabs)

Creates an AttributedString from an ANSI-encoded string with custom tab stops.

This method parses the ANSI escape sequences in the input string and creates an AttributedString with the corresponding styles. It also handles tab characters according to the specified tab stops.

Parameters:

ansi - the ANSI-encoded string to parse

tabs - the list of tab stop positions, or null for default tab stops

Returns:

an AttributedString with styles based on the ANSI escape sequences

fromAnsi

public static AttributedString fromAnsi(String ansi,
 Terminal terminal)

Creates an AttributedString from an ANSI-encoded string, using terminal capabilities.

This method parses the ANSI escape sequences in the input string and creates an AttributedString with the corresponding styles. It uses the specified terminal's capabilities to handle alternate character sets.

Parameters:

ansi - the ANSI-encoded string to parse

terminal - the terminal to use for capabilities, or null

Returns:

an AttributedString with styles based on the ANSI escape sequences

fromAnsi

public static AttributedString fromAnsi(String ansi,
 List<Integer> tabs,
 String altIn,
 String altOut)

Creates an AttributedString from an ANSI-encoded string with custom tab stops and alternate character set sequences.

This method parses the ANSI escape sequences in the input string and creates an AttributedString with the corresponding styles. It also handles tab characters according to the specified tab stops and alternate character set sequences.

Parameters:

ansi - the ANSI-encoded string to parse

tabs - the list of tab stop positions, or null for default tab stops

altIn - the sequence to enable the alternate character set, or null

altOut - the sequence to disable the alternate character set, or null

Returns:

an AttributedString with styles based on the ANSI escape sequences

stripAnsi

public static String stripAnsi(String ansi)

Strips ANSI escape sequences from a string.

This method removes all ANSI escape sequences from the input string, returning a plain text string with no styling information. This is useful for extracting the text content from ANSI-colored output.

Parameters:

ansi - the ANSI-encoded string to strip

Returns:

a plain text string with ANSI escape sequences removed, or null if the input is null

buffer

protected char[] buffer()

Returns the character buffer for this attributed string.

This method is used internally by the AttributedCharSequence implementation to access the underlying character buffer.

Specified by:

buffer in class AttributedCharSequence

Returns:

the character buffer

offset

protected int offset()

Returns the offset in the buffer where this attributed string starts.

This method is used internally by the AttributedCharSequence implementation to determine the starting position in the buffer.

Specified by:

offset in class AttributedCharSequence

Returns:

the offset in the buffer

length

public int length()

Returns the length of this attributed string.

This method returns the number of characters in this attributed string.

Returns:

the number of characters in this attributed string

styleAt

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

Specified by:

styleAt in class AttributedCharSequence

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

subSequence

public AttributedString subSequence(int start,
 int end)

Returns a new AttributedString that is a subsequence 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).

The subsequence preserves the style information from the original string.

Specified by:

subSequence in interface CharSequence

Specified by:

subSequence in class AttributedCharSequence

Parameters:

start - the start index, inclusive

end - the end index, exclusive

Returns:

the specified subsequence with its attributes

Throws:

IndexOutOfBoundsException - if start or end are negative, if end is greater than length(), or if start is greater than end

styleMatches

public AttributedString styleMatches(Pattern pattern,
 AttributedStyle style)

Returns a new AttributedString with the specified style applied to all matches of the pattern.

This method finds all matches of the specified regular expression pattern in this attributed string and applies the specified style to the matching regions. It returns a new AttributedString with the modified styles.

If no matches are found, this method returns the original attributed string.

Parameters:

pattern - the regular expression pattern to match

style - the style to apply to matching regions

Returns:

a new AttributedString with the specified style applied to matching regions

equals

public boolean equals(Object o)

Compares this AttributedString with another object for equality.

Two AttributedString objects are considered equal if they have the same length, the same characters, and the same styles at each position.

Overrides:

equals in class Object

Parameters:

o - the object to compare with

Returns:

true if the objects are equal, false otherwise

hashCode

public int hashCode()

Returns a hash code for this AttributedString.

The hash code is computed based on the characters, styles, and range of this attributed string.

Overrides:

hashCode in class Object

Returns:

a hash code value for this object

join

public static AttributedString join(AttributedString delimiter,
 AttributedString... elements)

Joins multiple AttributedString objects with a delimiter.

This method concatenates the specified AttributedString elements, inserting the specified delimiter between each element. The resulting AttributedString preserves the styles of all elements and the delimiter.

Parameters:

delimiter - the delimiter to insert between elements

elements - the elements to join

Returns:

a new AttributedString containing the joined elements

Throws:

NullPointerException - if delimiter or elements is null

join

public static AttributedString join(AttributedString delimiter,
 Iterable<AttributedString> elements)

Joins an Iterable of AttributedString objects with a delimiter.

This method concatenates the AttributedString elements in the specified Iterable, inserting the specified delimiter between each element. The resulting AttributedString preserves the styles of all elements and the delimiter.

If the delimiter is null, the elements are concatenated without any separator.

Parameters:

delimiter - the delimiter to insert between elements, or null for no delimiter

elements - the elements to join

Returns:

a new AttributedString containing the joined elements

Throws:

NullPointerException - if elements is null