Package org.apache.commons.cli.help

Class TextHelpAppendable

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static java.lang.String BLANK_LINE
      A blank line in the output: "".
      private static java.util.Set<java.lang.Character> BREAK_CHAR_SET
      The set of characters that are breaks in text.
      static int DEFAULT_INDENT
      The number of space characters to be prefixed to each description line: 3.
      static int DEFAULT_LEFT_PAD
      The default padding to the left of each line: 1.
      static int DEFAULT_LIST_INDENT
      The number of space characters before a list continuation line: 7.
      static int DEFAULT_WIDTH
      The default number of characters per line: 74.
      private TextStyle.Builder textStyleBuilder
      Defines the TextStyle for paragraph, and associated output formats.

    • Constructor Summary

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

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected TableDefinition adjustTableFormat​(TableDefinition table)
      Adjusts the table format.
      void appendHeader​(int level, java.lang.CharSequence text)
      Appends a header.
      void appendList​(boolean ordered, java.util.Collection<java.lang.CharSequence> list)
      Appends a list.
      void appendParagraph​(java.lang.CharSequence paragraph)
      Appends a paragraph.
      void appendTable​(TableDefinition rawTable)
      Appends a table.
      void appendTitle​(java.lang.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​(java.lang.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 java.util.Queue<java.lang.String> makeColumnQueue​(java.lang.CharSequence columnData, TextStyle style)
      Creates a queue comprising strings extracted from columnData where the alignment and length are determined by the style.
      protected java.util.List<java.util.Queue<java.lang.String>> makeColumnQueues​(java.util.List<java.lang.String> columnData, java.util.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.
      private void printQueue​(java.util.Queue<java.lang.String> queue)
      Prints a queue of text.
      void printWrapped​(java.lang.String text)
      Prints wrapped text using the TextHelpAppendable output style.
      void printWrapped​(java.lang.String text, TextStyle style)
      Prints wrapped text.
      private int resize​(int orig, double fraction)
      Resizes an original width based on the fractional size it should be.
      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​(java.util.List<java.util.Queue<java.lang.String>> columnQueues, java.util.List<TextStyle> styles)
      Writes one line from each of the columnQueues until all the queues are exhausted.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • 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

      • BLANK_LINE

        private static final java.lang.String BLANK_LINE
        A blank line in the output: "".
        See Also:
        Constant Field Values

      • BREAK_CHAR_SET

        private static final java.util.Set<java.lang.Character> BREAK_CHAR_SET
        The set of characters that are breaks in text.

      • textStyleBuilder

        private final TextStyle.Builder textStyleBuilder
        Defines the TextStyle for paragraph, and associated output formats.

    • Constructor Detail

      • TextHelpAppendable

        public TextHelpAppendable​(java.lang.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 Detail

      • indexOfWrap

        public static int indexOfWrap​(java.lang.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,
                         java.lang.CharSequence text)
                  throws java.io.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:
        java.io.IOException - If an output error occurs.

      • appendList

        public void appendList​(boolean ordered,
                       java.util.Collection<java.lang.CharSequence> list)
                throws java.io.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:
        java.io.IOException - If an output error occurs.

      • appendParagraph

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

      • appendTable

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

      • appendTitle

        public void appendTitle​(java.lang.CharSequence title)
                 throws java.io.IOException
        Description copied from interface: HelpAppendable
        Appends a title.
        Parameters:
        title - the title to write, null is a noop.
        Throws:
        java.io.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 java.util.Queue<java.lang.String> makeColumnQueue​(java.lang.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 java.util.List<java.util.Queue<java.lang.String>> makeColumnQueues​(java.util.List<java.lang.String> columnData,
                                                                             java.util.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.

      • printQueue

        private void printQueue​(java.util.Queue<java.lang.String> queue)
                 throws java.io.IOException
        Prints a queue of text.
        Parameters:
        queue - the queue of text to print.
        Throws:
        java.io.IOException - on output error.

      • printWrapped

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

      • printWrapped

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

      • resize

        private int resize​(int orig,
                   double fraction)
        Resizes an original width based on the fractional size it should be.
        Parameters:
        orig - the original size.
        fraction - the fractional adjustment.
        Returns:
        the resized value.

      • 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​(java.util.List<java.util.Queue<java.lang.String>> columnQueues,
                                 java.util.List<TextStyle> styles)
                          throws java.io.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:
        java.io.IOException - on output error.