de.ipcon.tools

Class TextBreaker

java.lang.Object

de.ipcon.tools.TextBreaker

public class TextBreaker
extends java.lang.Object

This class provides utility methods for formatting a given string of text by breaking it into multiple lines based on specified length constraints and adding optional prefixes and postfixes. It offers fine-grained control over how text is wrapped and presented, including:

• Configurable Line Lengths: Allows setting different maximum lengths for the first line and all subsequent lines, or disabling line breaking entirely for specific lines.
• Line Prefixes and Postfixes: Supports custom strings to be prepended and appended to each line, offering flexibility for formatting output (e.g., adding bullet points, line numbers, or newline characters).
• Intelligent Word Wrapping: Breaks lines at word boundaries where possible, considering specified whitespace characters.
• Forced Word Splitting: Can be configured to split individual words that are longer than the defined line length, preventing excessively long lines.
• Tag-Aware Processing: Includes logic to prevent inadvertent text breaks within HTML-like tags (e.g., <b>bold text</b>), ensuring the integrity of structured content.
• Paragraph Handling: Provides a mechanism to insert a specific character when new paragraphs are detected in the input text.

This class is particularly useful for preparing text for display in user interfaces, reports, (log) files, or any scenario where controlled text wrapping and formatting are required.

TODO: This class is currently named `TextBreaker`, but its functionality extends beyond simply breaking text. It acts more as a TextFormatter or LineWrapper, handling various aspects of text presentation such as configurable line lengths, prefixes, postfixes, word splitting (even for words longer than the line), and tag-aware text processing. A more descriptive name would better reflect its comprehensive text formatting capabilities.

Constructor Summary

Constructors

Constructor and Description
TextBreaker(int _lineLength, java.lang.String _linePrefix, java.lang.String _linePostfix) Constructs a new TextBreaker instance with specified line length, prefix, and postfix applied uniformly to all lines.

Method Summary

Modifier and Type	Method and Description
void	appendIfNotNull(java.lang.StringBuilder sb, java.lang.String s) Appends a string to a StringBuilder only if the string is not null.
java.lang.String	breakText(java.lang.String s) Breaks and formats the given string into multiple lines according to the configured line lengths, prefixes, and postfixes.
java.lang.String	breakText(java.lang.String s, boolean breakOnAnyWhiteSpaceChar)
int	getFirstLineLength()
java.lang.String	getFirstLinePostfix()
java.lang.String	getFirstLinePrefix()
java.lang.String	getLengthForLine(int n) Returns the desired line length for a given line number.
int	getLineLength()
java.lang.String	getLinePostfix()
java.lang.String	getLinePostfixForLine(int n) Returns the line postfix for a given line number.
java.lang.String	getLinePrefix()
java.lang.String	getLinePrefixForLine(int n) Returns the line prefix for a given line number.
java.lang.String	getNewParagraphChar()
java.lang.String	getWhitespaceChars()
boolean	isSplitWordsLongerThanLine()
int	longestSubWord(netrexx.lang.Rexx s, int w, netrexx.lang.Rexx line) Gets a long word "s", e.g. trichotillomania (an abnormal desire to pull out one's hair - might explain the baldness of some programmers ;)) and specifies the substring position of the "whitespaceChars" separator, where you have to cut the word at the latest for it to be no longer than w.
void	setFirstLineLength(int $19)
void	setFirstLinePostfix(java.lang.String $17)
void	setFirstLinePrefix(java.lang.String $15)
void	setLineLength(int $20)
void	setLinePostfix(java.lang.String $18)
void	setLinePrefix(java.lang.String $16)
void	setNewParagraphChar(java.lang.String $22)
void	setSplitWordsLongerThanLine(boolean $23)
void	setWhitespaceChars(java.lang.String $21)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TextBreaker

public TextBreaker(int _lineLength,
                   java.lang.String _linePrefix,
                   java.lang.String _linePostfix)

Constructs a new TextBreaker instance with specified line length, prefix, and postfix applied uniformly to all lines.

Parameters:

_lineLength - The maximum length for all lines. A value of -1 means no line breaking.

_linePrefix - The prefix to be prepended to all lines.

_linePostfix - The postfix to be appended to all lines.

Method Detail

breakText

public java.lang.String breakText(java.lang.String s)

Breaks and formats the given string into multiple lines according to the configured line lengths, prefixes, and postfixes.

Parameters:

s - The input string to be formatted.

breakOnAnyWhiteSpaceChar - A boolean flag indicating whether to attempt to break words at any character specified in "whitespaceChars" when a word is too long for the current line.

Returns:

The formatted string with line breaks, prefixes, and postfixes applied.

breakText

public java.lang.String breakText(java.lang.String s,
                                  boolean breakOnAnyWhiteSpaceChar)

appendIfNotNull

public void appendIfNotNull(java.lang.StringBuilder sb,
                            java.lang.String s)

Appends a string to a StringBuilder only if the string is not null.

Parameters:

sb - The StringBuilder to append to.

s - The string to append.

getLengthForLine

public java.lang.String getLengthForLine(int n)

Returns the desired line length for a given line number. The first line uses "firstLineLength", and subsequent lines use "lineLength".

Parameters:

n - The current line number (1-indexed).

Returns:

The maximum length for the specified line.

getLinePrefixForLine

public java.lang.String getLinePrefixForLine(int n)

Returns the line prefix for a given line number. The first line uses "firstLinePrefix", and subsequent lines use "linePrefix".

Parameters:

n - The current line number (1-indexed).

Returns:

The prefix for the specified line.

getLinePostfixForLine

public java.lang.String getLinePostfixForLine(int n)

Returns the line postfix for a given line number. The first line uses "firstLinePostfix", and subsequent lines use "linePostfix".

Parameters:

n - The current line number (1-indexed).

Returns:

The postfix for the specified line.

longestSubWord

public int longestSubWord(netrexx.lang.Rexx s,
                          int w,
                          netrexx.lang.Rexx line)

Gets a long word "s", e.g. trichotillomania (an abnormal desire to pull out one's hair - might explain the baldness of some programmers ;)) and specifies the substring position of the "whitespaceChars" separator, where you have to cut the word at the latest for it to be no longer than w. This method attempts to find the longest possible sub-word that fits within the remaining width "w", considering specified whitespace characters and avoiding breaks within HTML-like tags.

Parameters:

s - The long word to potentially break.

w - The maximum remaining width available for the word.

line - The current line content, including the word, used for tag-aware processing.

Returns:

The position within the word "s" where it can be separated, or -1 if no suitable separation point is found within the given width.

getFirstLinePrefix

public java.lang.String getFirstLinePrefix()

setFirstLinePrefix

public void setFirstLinePrefix(java.lang.String $15)

getLinePrefix

public java.lang.String getLinePrefix()

setLinePrefix

public void setLinePrefix(java.lang.String $16)

getFirstLinePostfix

public java.lang.String getFirstLinePostfix()

setFirstLinePostfix

public void setFirstLinePostfix(java.lang.String $17)

getLinePostfix

public java.lang.String getLinePostfix()

setLinePostfix

public void setLinePostfix(java.lang.String $18)

getFirstLineLength

public int getFirstLineLength()

setFirstLineLength

public void setFirstLineLength(int $19)

getLineLength

public int getLineLength()

setLineLength

public void setLineLength(int $20)

getWhitespaceChars

public java.lang.String getWhitespaceChars()

setWhitespaceChars

public void setWhitespaceChars(java.lang.String $21)

getNewParagraphChar

public java.lang.String getNewParagraphChar()

setNewParagraphChar

public void setNewParagraphChar(java.lang.String $22)

isSplitWordsLongerThanLine

public boolean isSplitWordsLongerThanLine()

setSplitWordsLongerThanLine

public void setSplitWordsLongerThanLine(boolean $23)