Class AttributedStringBuilder
- All Implemented Interfaces:
Appendable
,CharSequence
The AttributedStringBuilder class provides a mutable implementation of AttributedCharSequence for constructing styled text strings. It allows for dynamic building of attributed strings by appending characters, strings, or other attributed strings with various styles.
This class is similar to StringBuilder but with added support for ANSI style attributes. It provides methods for appending text with different styles, manipulating the content, and converting the result to an immutable AttributedString when building is complete.
Key features include:
- Append operations with different styles
- Tab expansion with configurable tab stops
- Style manipulation (foreground/background colors, bold, underline, etc.)
- Regular expression based styling
- Alternative character set support
This class is commonly used for building complex styled output for terminal applications, such as syntax highlighting, interactive prompts, and formatted displays.
- See Also:
-
Nested Class Summary
Nested classes/interfaces inherited from class org.jline.utils.AttributedCharSequence
AttributedCharSequence.ForceMode
-
Field Summary
Fields inherited from class org.jline.utils.AttributedCharSequence
TRUE_COLORS
-
Constructor Summary
ConstructorsConstructorDescriptionCreates a new AttributedStringBuilder with the default initial capacity.AttributedStringBuilder
(int capacity) Creates a new AttributedStringBuilder with the specified initial capacity. -
Method Summary
Modifier and TypeMethodDescriptionaltCharset
(String altIn, String altOut) Sets the alternate character set sequences for this builder.ansiAppend
(String ansi) Appends the specified ANSI-encoded string to this builder.append
(char c) Appends the specified character to this builder.append
(char c, int repeat) Appends the specified character to this builder multiple times.append
(CharSequence csq) Appends the specified character sequence to this builder.static AttributedString
append
(CharSequence... strings) Creates an AttributedString by appending multiple character sequences.append
(CharSequence csq, int start, int end) Appends a subsequence of the specified character sequence to this builder.append
(CharSequence csq, AttributedStyle style) Appends the specified character sequence to this builder with the specified style.Appends the specified AttributedCharSequence to this builder.append
(AttributedCharSequence str, int start, int end) Appends a subsequence of the specified AttributedCharSequence to this builder.append
(AttributedString str) Appends the specified AttributedString to this builder.append
(AttributedString str, int start, int end) Appends a subsequence of the specified AttributedString to this builder.void
appendAnsi
(String ansi) Appends the specified ANSI-encoded string to this builder.protected char[]
buffer()
Returns the character buffer for this attributed string builder.char
charAt
(int index) Returns the character at the specified index in this attributed string builder.protected void
ensureCapacity
(int nl) protected void
int
length()
Returns the length of this attributed string builder.protected int
offset()
Returns the offset in the buffer where this attributed string builder starts.void
setLength
(int l) Sets the length of this attributed string builder.style()
Returns the current style for this builder.style
(Function<AttributedStyle, AttributedStyle> style) Updates the current style for this builder using a function.style
(AttributedStyle style) Sets the current style for this builder.styleAt
(int index) Returns the style at the specified index in this attributed string builder.styled
(Function<AttributedStyle, AttributedStyle> style, CharSequence cs) Appends the specified character sequence with a temporarily modified style.styled
(Function<AttributedStyle, AttributedStyle> style, Consumer<AttributedStringBuilder> consumer) Performs operations with a temporarily modified style.styled
(AttributedStyle style, CharSequence cs) Appends the specified character sequence with the specified style.styleMatches
(Pattern pattern, List<AttributedStyle> styles) Applies different styles to different capture groups in pattern matches.styleMatches
(Pattern pattern, AttributedStyle s) Applies the specified style to all matches of the pattern in this builder.subSequence
(int start, int end) Returns a new AttributedString that is a subsequence of this attributed string builder.tabs
(int tabsize) Set the number of spaces a tab is expanded to.Sets the tab stops for this attributed string builder.Methods inherited from class org.jline.utils.AttributedCharSequence
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, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.lang.CharSequence
chars, codePoints, isEmpty
-
Constructor Details
-
AttributedStringBuilder
public AttributedStringBuilder()Creates a new AttributedStringBuilder with the default initial capacity.This constructor creates a new AttributedStringBuilder with an initial capacity of 64 characters. The builder will automatically grow as needed when more characters are appended.
-
AttributedStringBuilder
public AttributedStringBuilder(int capacity) Creates a new AttributedStringBuilder with the specified initial capacity.This constructor creates a new AttributedStringBuilder with the specified initial capacity. The builder will automatically grow as needed when more characters are appended.
- Parameters:
capacity
- the initial capacity of the builder
-
-
Method Details
-
append
Creates an AttributedString by appending multiple character sequences.This static utility method creates a new AttributedString by appending all the specified character sequences. It is a convenient way to concatenate multiple strings or AttributedStrings into a single AttributedString.
- Parameters:
strings
- the character sequences to append- Returns:
- a new AttributedString containing all the appended sequences
-
length
public int length()Returns the length of this attributed string builder.This method returns the number of characters in this attributed string builder.
- Specified by:
length
in interfaceCharSequence
- Returns:
- the number of characters in this attributed string builder
-
charAt
public char charAt(int index) Returns the character at the specified index in this attributed string builder.This method returns the character at the specified index in this attributed string builder.
- Specified by:
charAt
in interfaceCharSequence
- Overrides:
charAt
in classAttributedCharSequence
- Parameters:
index
- the index of the character to return- Returns:
- the character at the specified index
- Throws:
IndexOutOfBoundsException
- if the index is out of range
-
styleAt
Returns the style at the specified index in this attributed string builder.This method returns the AttributedStyle object associated with the character at the specified index in this attributed string builder.
- Specified by:
styleAt
in classAttributedCharSequence
- 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
-
buffer
protected char[] buffer()Returns the character buffer for this attributed string builder.This method is used internally by the AttributedCharSequence implementation to access the underlying character buffer.
- Specified by:
buffer
in classAttributedCharSequence
- Returns:
- the character buffer
-
offset
protected int offset()Returns the offset in the buffer where this attributed string builder starts.This method is used internally by the AttributedCharSequence implementation to determine the starting position in the buffer. For AttributedStringBuilder, this is always 0 since the builder uses the entire buffer.
- Specified by:
offset
in classAttributedCharSequence
- Returns:
- the offset in the buffer (always 0 for AttributedStringBuilder)
-
subSequence
Returns a new AttributedString that is a subsequence of this attributed string builder.This method returns a new AttributedString that contains the characters and styles from this attributed string builder starting at the specified start index (inclusive) and ending at the specified end index (exclusive).
- Specified by:
subSequence
in interfaceCharSequence
- Specified by:
subSequence
in classAttributedCharSequence
- Parameters:
start
- the start index, inclusiveend
- 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
-
append
Appends the specified character sequence to this builder.This method appends the specified character sequence to this builder, applying the current style to all characters. If the character sequence is null, the string "null" is appended, as required by the Appendable interface.
- Specified by:
append
in interfaceAppendable
- Parameters:
csq
- the character sequence to append, or null- Returns:
- this builder
-
append
Appends a subsequence of the specified character sequence to this builder.This method appends a subsequence of the specified character sequence to this builder, applying the current style to all characters. If the character sequence is null, the string "null" is appended, as required by the Appendable interface.
- Specified by:
append
in interfaceAppendable
- Parameters:
csq
- the character sequence to append, or nullstart
- the index of the first character to appendend
- the index after the last character to append- Returns:
- this builder
- Throws:
IndexOutOfBoundsException
- if start or end are negative, or if end is greater than csq.length(), or if start is greater than end
-
append
Appends the specified character to this builder.This method appends the specified character to this builder, applying the current style to the character.
- Specified by:
append
in interfaceAppendable
- Parameters:
c
- the character to append- Returns:
- this builder
-
append
Appends the specified character to this builder multiple times.This method appends the specified character to this builder the specified number of times, applying the current style to all characters.
- Parameters:
c
- the character to appendrepeat
- the number of times to append the character- Returns:
- this builder
-
append
Appends the specified character sequence to this builder with the specified style.This method appends the specified character sequence to this builder, applying the specified style to all characters. This allows appending text with a style different from the current style without changing the current style.
- Parameters:
csq
- the character sequence to appendstyle
- the style to apply to the appended characters- Returns:
- this builder
-
style
Sets the current style for this builder.This method sets the current style for this builder, which will be applied to all characters appended after this call (until the style is changed again).
- Parameters:
style
- the new current style- Returns:
- this builder
-
style
Updates the current style for this builder using a function.This method updates the current style for this builder by applying the specified function to the current style. This allows for fluent style modifications without creating intermediate style objects.
Example usage:
builder.style(s -> s.bold().foreground(AttributedStyle.RED));
- Parameters:
style
- the function to apply to the current style- Returns:
- this builder
-
styled
public AttributedStringBuilder styled(Function<AttributedStyle, AttributedStyle> style, CharSequence cs) Appends the specified character sequence with a temporarily modified style.This method temporarily modifies the current style using the specified function, appends the specified character sequence with that style, and then restores the original style. This allows for appending styled text without permanently changing the current style.
- Parameters:
style
- the function to apply to the current stylecs
- the character sequence to append- Returns:
- this builder
-
styled
Appends the specified character sequence with the specified style.This method temporarily sets the current style to the specified style, appends the specified character sequence with that style, and then restores the original style. This allows for appending styled text without permanently changing the current style.
- Parameters:
style
- the style to usecs
- the character sequence to append- Returns:
- this builder
-
styled
public AttributedStringBuilder styled(Function<AttributedStyle, AttributedStyle> style, Consumer<AttributedStringBuilder> consumer) Performs operations with a temporarily modified style.This method temporarily modifies the current style using the specified function, performs the operations specified by the consumer with that style, and then restores the original style. This allows for performing complex styling operations without permanently changing the current style.
Example usage:
builder.styled(s -> s.bold().foreground(AttributedStyle.RED), sb -> sb.append("Error: ").append(errorMessage));
- Parameters:
style
- the function to apply to the current styleconsumer
- the consumer that performs operations on this builder- Returns:
- this builder
-
style
Returns the current style for this builder.This method returns the current style for this builder, which is applied to all characters appended after the style was set (until the style is changed).
- Returns:
- the current style
-
append
Appends the specified AttributedString to this builder.This method appends the specified AttributedString to this builder, preserving its character attributes. The current style is applied to any attributes that are not explicitly set in the AttributedString.
- Parameters:
str
- the AttributedString to append- Returns:
- this builder
-
append
Appends a subsequence of the specified AttributedString to this builder.This method appends a subsequence of the specified AttributedString to this builder, preserving its character attributes. The current style is applied to any attributes that are not explicitly set in the AttributedString.
- Parameters:
str
- the AttributedString to appendstart
- the index of the first character to appendend
- the index after the last character to append- Returns:
- this builder
- Throws:
IndexOutOfBoundsException
- if start or end are negative, or if end is greater than str.length(), or if start is greater than end
-
append
Appends the specified AttributedCharSequence to this builder.This method appends the specified AttributedCharSequence to this builder, preserving its character attributes. The current style is applied to any attributes that are not explicitly set in the AttributedCharSequence.
- Parameters:
str
- the AttributedCharSequence to append- Returns:
- this builder
-
append
Appends a subsequence of the specified AttributedCharSequence to this builder.This method appends a subsequence of the specified AttributedCharSequence to this builder, preserving its character attributes. The current style is applied to any attributes that are not explicitly set in the AttributedCharSequence.
If the sequence contains tab characters and tab stops are defined, the tabs will be expanded according to the current tab stop settings.
- Parameters:
str
- the AttributedCharSequence to appendstart
- the index of the first character to appendend
- the index after the last character to append- Returns:
- this builder
- Throws:
IndexOutOfBoundsException
- if start or end are negative, or if end is greater than str.length(), or if start is greater than end
-
ensureCapacity
protected void ensureCapacity(int nl) -
appendAnsi
Appends the specified ANSI-encoded string to this builder.This method parses the ANSI escape sequences in the input string and appends the text with the corresponding styles to this builder. This is useful for converting ANSI-colored output from external commands into styled text.
This method is equivalent to
ansiAppend(String)
but returns void.- Parameters:
ansi
- the ANSI-encoded string to parse and append- See Also:
-
ansiAppend
Appends the specified ANSI-encoded string to this builder.This method parses the ANSI escape sequences in the input string and appends the text with the corresponding styles to this builder. This is useful for converting ANSI-colored output from external commands into styled text.
The method recognizes standard ANSI SGR (Select Graphic Rendition) sequences for text attributes (bold, underline, etc.) and colors (foreground and background).
- Parameters:
ansi
- the ANSI-encoded string to parse and append- Returns:
- this builder
-
insertTab
-
setLength
public void setLength(int l) Sets the length of this attributed string builder.This method sets the length of this attributed string builder. If the specified length is less than the current length, the builder is truncated; if it is greater than the current length, the builder is extended with undefined characters and styles.
Note that extending the builder with this method may result in undefined behavior if the extended region is accessed without first setting its characters and styles.
- Parameters:
l
- the new length
-
tabs
Set the number of spaces a tab is expanded to. Tab size cannot be changed after text has been added to prevent inconsistent indentation. If tab size is set to 0, tabs are not expanded (the default).- Parameters:
tabsize
- Spaces per tab or 0 for no tab expansion. Must be non-negative- Returns:
- this
-
tabs
Sets the tab stops for this attributed string builder.This method sets the tab stops for this attributed string builder, which are used for tab expansion when appending tab characters. Tab stops cannot be changed after text has been added to prevent inconsistent indentation.
- Parameters:
tabs
- the list of tab stop positions- Returns:
- this attributed string builder
- Throws:
IllegalStateException
- if text has already been appended
-
altCharset
Sets the alternate character set sequences for this builder.This method sets the alternate character set sequences for this builder, which are used for handling special characters like box drawing characters. The alternate character set cannot be changed after text has been added to prevent inconsistent character rendering.
- Parameters:
altIn
- 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:
- this builder
- Throws:
IllegalStateException
- if text has already been appended
-
styleMatches
Applies the specified style to all matches of the pattern in this builder.This method finds all matches of the specified regular expression pattern in this builder and applies the specified style to the matching regions. The style is applied to all characters in each match.
Example usage:
builder.append("Error: File not found") .styleMatches(Pattern.compile("Error:"), AttributedStyle.DEFAULT.foreground(AttributedStyle.RED));
- Parameters:
pattern
- the regular expression pattern to matchs
- the style to apply to matching regions- Returns:
- this builder
-
styleMatches
Applies different styles to different capture groups in pattern matches.This method finds all matches of the specified regular expression pattern in this builder and applies different styles to different capture groups in each match. The first style in the list is applied to the first capture group, the second style to the second capture group, and so on.
Example usage:
builder.append("Error: File not found") .styleMatches(Pattern.compile("(Error): (File not found)"), Arrays.asList( AttributedStyle.DEFAULT.foreground(AttributedStyle.RED), AttributedStyle.DEFAULT.foreground(AttributedStyle.YELLOW)));
- Parameters:
pattern
- the regular expression pattern to matchstyles
- the list of styles to apply to capture groups- Returns:
- this builder
- Throws:
IndexOutOfBoundsException
- if the pattern has fewer capture groups than styles
-