Package org.apache.commons.cli.help

# Class TextHelpAppendable

java.lang.Object
org.apache.commons.cli.help.FilterHelpAppendable
org.apache.commons.cli.help.TextHelpAppendable

All Implemented Interfaces:
  `Appendable`, `HelpAppendable`

public class TextHelpAppendable extends FilterHelpAppendable
Writes text format output.

Since:
  1.10.0

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEFAULT_INDENT`
  The number of space characters to be prefixed to each description line: 3.
  `static final int`
  `DEFAULT_LEFT_PAD`
  The default padding to the left of each line: 1.
  `static final int`
  `DEFAULT_LIST_INDENT`
  The number of space characters before a list continuation line: 7.
  `static final int`
  `DEFAULT_WIDTH`
  The default number of characters per line: 74.

  ### Fields inherited from class org.apache.commons.cli.help.FilterHelpAppendable

  `output`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TextHelpAppendable(Appendable output)`
  Constructs an appendable filter built on top of the specified underlying appendable.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected TableDefinition`
  `adjustTableFormat(TableDefinition table)`
  Adjusts the table format.
  `void`
  `appendHeader(int level, CharSequence text)`
  Appends a header.
  `void`
  `appendList(boolean ordered, Collection<CharSequence> list)`
  Appends a list.
  `void`
  `appendParagraph(CharSequence paragraph)`
  Appends a paragraph.
  `void`
  `appendTable(TableDefinition rawTable)`
  Appends a table.
  `void`
  `appendTitle(CharSequence title)`
  Appends a title.
  `int`
  `getIndent()`
  Gets the indent for the output.
  `int`
  `getLeftPad()`
  Returns the left padding for the output.
  `int`
  `getMaxWidth()`
  Gets the maximum width for the output
  `TextStyle.Builder`
  `getTextStyleBuilder()`
  Gets the style builder used to format text that is not otherwise formatted.
  `static int`
  `indexOfWrap(CharSequence text, int width, int startPos)`
  Finds the next text wrap position after `startPos` for the text in `text` with the column width `width`.
  `protected Queue<String>`
  `makeColumnQueue(CharSequence columnData, TextStyle style)`
  Creates a queue comprising strings extracted from columnData where the alignment and length are determined by the style.
  `protected List<Queue<String>>`
  `makeColumnQueues(List<String> columnData, List<TextStyle> styles)`
  For each column in the `columnData` apply the associated `TextStyle` and generated a queue of strings that are the maximum size of the column + the left pad.
  `void`
  `printWrapped(String text)`
  Prints wrapped text using the TextHelpAppendable output style.
  `void`
  `printWrapped(String text, TextStyle style)`
  Prints wrapped text.
  `protected TextStyle.Builder`
  `resize(TextStyle.Builder builder, double fraction)`
  Resizes a TextStyle builder based on the fractional size.
  `void`
  `setIndent(int indent)`
  Sets the indent for the output.
  `void`
  `setLeftPad(int leftPad)`
  Sets the left padding: the number of characters from the left edge to start output.
  `void`
  `setMaxWidth(int maxWidth)`
  Sets the maximum width for the output.
  `protected static TextHelpAppendable`
  `systemOut()`
  Creates a new TextHelpAppendable on `System.out`.
  `protected void`
  `writeColumnQueues(List<Queue<String>> columnQueues, List<TextStyle> styles)`
  Writes one line from each of the `columnQueues` until all the queues are exhausted.

  ### Methods inherited from class org.apache.commons.cli.help.FilterHelpAppendable

  `append, append, append`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface org.apache.commons.cli.help.HelpAppendable

  `appendFormat, appendParagraphFormat`

- ## Field Details

  - ### DEFAULT_WIDTH

    public static final int DEFAULT_WIDTH
    The default number of characters per line: 74.
    See Also:
      - Constant Field Values

  - ### DEFAULT_LEFT_PAD

    public static final int DEFAULT_LEFT_PAD
    The default padding to the left of each line: 1.
    See Also:
      - Constant Field Values

  - ### DEFAULT_INDENT

    public static final int DEFAULT_INDENT
    The number of space characters to be prefixed to each description line: 3.
    See Also:
      - Constant Field Values

  - ### DEFAULT_LIST_INDENT

    public static final int DEFAULT_LIST_INDENT
    The number of space characters before a list continuation line: 7.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### TextHelpAppendable

    public TextHelpAppendable(Appendable output)
    Constructs an appendable filter built on top of the specified underlying appendable.
    Parameters:
      `output` - the underlying appendable to be assigned to the field `this.output` for later use, or `null` if this instance is to be created without an underlying stream.

- ## Method Details

  - ### indexOfWrap

    public static int indexOfWrap(CharSequence text, int width, int startPos)
    Finds the next text wrap position after `startPos` for the text in `text` with the column width `width`. The wrap point is the last position before startPos+width having a whitespace character (space, \n, \r). If there is no whitespace character before startPos+width, it will return startPos+width.
    Parameters:
      `text` - The text being searched for the wrap position
      `width` - width of the wrapped text
      `startPos` - position from which to start the lookup whitespace character
    Returns:
      position on which the text must be wrapped or @{code text.length()} if the wrap position is at the end of the text.

  - ### systemOut

    protected static TextHelpAppendable systemOut()
    Creates a new TextHelpAppendable on `System.out`.
    Returns:
      a new TextHelpAppendable on `System.out`.

  - ### adjustTableFormat

    protected TableDefinition adjustTableFormat(TableDefinition table)
    Adjusts the table format.

    Given the width of the page and the size of the table attempt to resize the columns to fit the page width if necessary. Adjustments are made as follows:

    - The minimum size for a column may not be smaller than the length of the column header
    - The maximum size is set to the maximum of the length of the header or the longest line length.
    - If the total size of the columns is greater than the page wight, adjust the size of VARIABLE columns to attempt reduce the width to the the maximum size.

    Note: it is possible for the size of the columns to exceed the declared page width. In this case the table will extend beyond the desired page width.

    Parameters:
      `table` - the table to adjust.
    Returns:
      a new TableDefinition with adjusted values.

  - ### appendHeader

    public void appendHeader(int level, CharSequence text) throws IOException
    Description copied from interface: `HelpAppendable`
    Appends a header.
    Parameters:
      `level` - the level of the header. This is equivalent to the "1", "2", or "3" in the HTML "h1", "h2", "h3" tags.
      `text` - the text for the header, null is a noop.
    Throws:
      `IOException` - If an output error occurs.

  - ### appendList

    public void appendList(boolean ordered, Collection<CharSequence> list) throws IOException
    Description copied from interface: `HelpAppendable`
    Appends a list.
    Parameters:
      `ordered` - `true` if the list should be ordered.
      `list` - the list to write, null is a noop.
    Throws:
      `IOException` - If an output error occurs.

  - ### appendParagraph

    public void appendParagraph(CharSequence paragraph) throws IOException
    Description copied from interface: `HelpAppendable`
    Appends a paragraph.
    Parameters:
      `paragraph` - the paragraph to write, null is a noop.
    Throws:
      `IOException` - If an output error occurs.

  - ### appendTable

    public void appendTable(TableDefinition rawTable) throws IOException
    Description copied from interface: `HelpAppendable`
    Appends a table.
    Parameters:
      `rawTable` - the table definition to write, null is a noop.
    Throws:
      `IOException` - If an output error occurs.

  - ### appendTitle

    public void appendTitle(CharSequence title) throws IOException
    Description copied from interface: `HelpAppendable`
    Appends a title.
    Parameters:
      `title` - the title to write, null is a noop.
    Throws:
      `IOException` - If an output error occurs.

  - ### getIndent

    public int getIndent()
    Gets the indent for the output.
    Returns:
      the indent of the page.

  - ### getLeftPad

    public int getLeftPad()
    Returns the left padding for the output.
    Returns:
      The left padding for the output.

  - ### getMaxWidth

    public int getMaxWidth()
    Gets the maximum width for the output
    Returns:
      the maximum width for the output.

  - ### getTextStyleBuilder

    public TextStyle.Builder getTextStyleBuilder()
    Gets the style builder used to format text that is not otherwise formatted.
    Returns:
      The style builder used to format text that is not otherwise formatted.

  - ### makeColumnQueue

    protected Queue<String> makeColumnQueue(CharSequence columnData, TextStyle style)
    Creates a queue comprising strings extracted from columnData where the alignment and length are determined by the style.
    Parameters:
      `columnData` - The string to wrap
      `style` - The TextStyle to guide the wrapping.
    Returns:
      A queue of the string wrapped.

  - ### makeColumnQueues

    protected List<Queue<String>> makeColumnQueues(List<String> columnData, List<TextStyle> styles)
    For each column in the `columnData` apply the associated `TextStyle` and generated a queue of strings that are the maximum size of the column + the left pad.
    Parameters:
      `columnData` - The column data to output.
      `styles` - the styles to apply.
    Returns:
      A list of queues of strings that represent each column in the table.

  - ### printWrapped

    public void printWrapped(String text) throws IOException
    Prints wrapped text using the TextHelpAppendable output style.
    Parameters:
      `text` - the text to wrap
    Throws:
      `IOException` - on output error.

  - ### printWrapped

    public void printWrapped(String text, TextStyle style) throws IOException
    Prints wrapped text.
    Parameters:
      `text` - the text to wrap
      `style` - the style for the wrapped text.
    Throws:
      `IOException` - on output error.

  - ### resize

    protected TextStyle.Builder resize(TextStyle.Builder builder, double fraction)
    Resizes a TextStyle builder based on the fractional size.
    Parameters:
      `builder` - the builder to adjust.
      `fraction` - the fractional size (for example percentage of the current size) that the builder should be.
    Returns:
      the builder with the maximum width and indent values resized.

  - ### setIndent

    public void setIndent(int indent)
    Sets the indent for the output.
    Parameters:
      `indent` - the indent used for paragraphs.

  - ### setLeftPad

    public void setLeftPad(int leftPad)
    Sets the left padding: the number of characters from the left edge to start output.
    Parameters:
      `leftPad` - the left padding.

  - ### setMaxWidth

    public void setMaxWidth(int maxWidth)
    Sets the maximum width for the output.
    Parameters:
      `maxWidth` - the maximum width for the output.

  - ### writeColumnQueues

    protected void writeColumnQueues(List<Queue<String>> columnQueues, List<TextStyle> styles) throws IOException
    Writes one line from each of the `columnQueues` until all the queues are exhausted. If an exhausted queue is encountered while other queues continue to have content the exhausted queue will produce empty text for the output width of the column (maximum width + left pad).
    Parameters:
      `columnQueues` - the List of queues that represent the columns of data.
      `styles` - the TextStyle for each column.
    Throws:
      `IOException` - on output error.