Package com.aspectran.shell.command.option

Class HelpFormatter

  • public class HelpFormatter
extends java.lang.Object
    A formatter of help messages for command line options.

    Example:

     Options options = new Options();
 options.addOption(OptionBuilder.withLongOpt("file")
                                .withDescription("The file to be processed")
                                .hasArg()
                                .withArgName("FILE")
                                .isRequired()
                                .create('f'));
 options.addOption(OptionBuilder.withLongOpt("version")
                                .withDescription("Print the version of the application")
                                .create('v'));
 options.addOption(OptionBuilder.withLongOpt("help").create('h'));
 
 String header = "Do something useful with an input file\n\n";
 String footer = "\nPlease report issues at http://example.com/issues";
 
 HelpFormatter formatter = new HelpFormatter();
 formatter.printHelp("myapp", header, options, footer, true);
    This produces the following output: 
     usage: myapp -f <FILE> [-h] [-v]
 Do something useful with an input file
 
  -f,--file <FILE>   The file to be processed
  -h,--help
  -v,--version       Print the version of the application
 
 Please report issues at http://example.com/issues

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int DEFAULT_DESC_PAD
      number of space characters to be prefixed to each description line
      static int DEFAULT_LEFT_PAD
      Default padding to the left of each line
      static java.lang.String DEFAULT_LONG_OPT_PREFIX
      Default prefix for long Option
      static java.lang.String DEFAULT_OPT_PREFIX
      Default prefix for shortOpts
      static int DEFAULT_WIDTH
      Default number of characters per line
      protected java.util.Comparator<Option> optionComparator
      Comparator used to sort the options when they output in help text.

    • Constructor Summary

      Constructors 
      Constructor Description
      HelpFormatter​(Console console)
      Creates a help formatter.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.String getArgName()
      Returns the 'argName'.
      int getDescPadding()
      Returns the 'descPadding'.
      int getLeftPadding()
      Returns the 'leftPadding'.
      java.lang.String getLongOptPrefix()
      Returns the 'longOptPrefix'.
      java.lang.String getLongOptSeparator()
      Returns the separator displayed between a long option and its value.
      java.lang.String getNewLine()
      Returns the 'newLine'.
      java.util.Comparator<Option> getOptionComparator()
      Comparator used to sort the options when they output in help text.
      java.lang.String getOptPrefix()
      Returns the 'optPrefix'.
      java.lang.String getSyntaxPrefix()
      Returns the 'syntaxPrefix'.
      int getWidth()
      Returns the 'width'.
      void printHelp​(int width, java.lang.String cmdLineSyntax, java.lang.String header, Options options, int leftPad, int descPad, java.lang.String footer)
      Print the help for options with the specified command line syntax.
      void printHelp​(int width, java.lang.String cmdLineSyntax, java.lang.String header, Options options, int leftPad, int descPad, java.lang.String footer, boolean autoUsage)
      Print the help for options with the specified command line syntax.
      void printHelp​(int width, java.lang.String cmdLineSyntax, java.lang.String header, Options options, java.lang.String footer)
      Print the help for options with the specified command line syntax.
      void printHelp​(int width, java.lang.String cmdLineSyntax, java.lang.String header, Options options, java.lang.String footer, boolean autoUsage)
      Print the help for options with the specified command line syntax.
      void printHelp​(java.lang.String cmdLineSyntax, Options options)
      Print the help for options with the specified command line syntax.
      void printHelp​(java.lang.String cmdLineSyntax, Options options, boolean autoUsage)
      Print the help for options with the specified command line syntax.
      void printHelp​(java.lang.String cmdLineSyntax, java.lang.String header, Options options, java.lang.String footer)
      Print the help for options with the specified command line syntax.
      void printHelp​(java.lang.String cmdLineSyntax, java.lang.String header, Options options, java.lang.String footer, boolean autoUsage)
      Print the help for options with the specified command line syntax.
      void printOptions​(int width, Options options, int leftPad, int descPad)
      Print the help for the specified Options to the specified writer, using the specified width, left padding and description padding.
      void printUsage​(int width, java.lang.String cmdLineSyntax)
      Print the cmdLineSyntax to the specified writer, using the specified width.
      void printUsage​(int width, java.lang.String commandName, Options options)
      Prints the usage statement for the specified command.
      void printWrapped​(int width, int nextLineTabStop, java.lang.String text)
      Print the specified text to the specified PrintWriter.
      void printWrapped​(int width, java.lang.String text)
      Print the specified text to the specified PrintWriter.
      protected java.lang.StringBuilder renderOptions​(java.lang.StringBuilder sb, int width, Options options, int leftPad, int descPad)
      Render the specified Options and return the rendered Options in a StringBuilder.
      protected java.lang.StringBuilder renderWrappedText​(java.lang.StringBuilder sb, int width, int nextLineTabStop, java.lang.String text)
      Render the specified text and return the rendered Options in a StringBuilder.
      void setArgName​(java.lang.String name)
      Sets the 'argName'.
      void setDescPadding​(int padding)
      Sets the 'descPadding'.
      void setLeftPadding​(int padding)
      Sets the 'leftPadding'.
      void setLongOptPrefix​(java.lang.String prefix)
      Sets the 'longOptPrefix'.
      void setLongOptSeparator​(java.lang.String longOptSeparator)
      Set the separator displayed between a long option and its value.
      void setNewLine​(java.lang.String newline)
      Sets the 'newLine'.
      void setOptionComparator​(java.util.Comparator<Option> comparator)
      Set the comparator used to sort the options when they output in help text.
      void setOptPrefix​(java.lang.String prefix)
      Sets the 'optPrefix'.
      void setSyntaxPrefix​(java.lang.String prefix)
      Sets the 'syntaxPrefix'.
      void setWidth​(int width)
      Sets the 'width'.

      • 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
        Default number of characters per line
        See Also:
        Constant Field Values

      • DEFAULT_LEFT_PAD

        public static final int DEFAULT_LEFT_PAD
        Default padding to the left of each line
        See Also:
        Constant Field Values

      • DEFAULT_DESC_PAD

        public static final int DEFAULT_DESC_PAD
        number of space characters to be prefixed to each description line
        See Also:
        Constant Field Values

      • DEFAULT_OPT_PREFIX

        public static final java.lang.String DEFAULT_OPT_PREFIX
        Default prefix for shortOpts
        See Also:
        Constant Field Values

      • DEFAULT_LONG_OPT_PREFIX

        public static final java.lang.String DEFAULT_LONG_OPT_PREFIX
        Default prefix for long Option
        See Also:
        Constant Field Values

      • optionComparator

        protected java.util.Comparator<Option> optionComparator
        Comparator used to sort the options when they output in help text. Defaults to case-insensitive alphabetical sorting by option key.

    • Constructor Detail

      • HelpFormatter

        public HelpFormatter​(Console console)
        Creates a help formatter.
        Parameters:
        console - the console to which the help will be written

    • Method Detail

      • setWidth

        public void setWidth​(int width)
        Sets the 'width'.
        Parameters:
        width - the new value of 'width'

      • getWidth

        public int getWidth()
        Returns the 'width'.
        Returns:
        the 'width'

      • setLeftPadding

        public void setLeftPadding​(int padding)
        Sets the 'leftPadding'.
        Parameters:
        padding - the new value of 'leftPadding'

      • getLeftPadding

        public int getLeftPadding()
        Returns the 'leftPadding'.
        Returns:
        the 'leftPadding'

      • setDescPadding

        public void setDescPadding​(int padding)
        Sets the 'descPadding'.
        Parameters:
        padding - the new value of 'descPadding'

      • getDescPadding

        public int getDescPadding()
        Returns the 'descPadding'.
        Returns:
        the 'descPadding'

      • setSyntaxPrefix

        public void setSyntaxPrefix​(java.lang.String prefix)
        Sets the 'syntaxPrefix'.
        Parameters:
        prefix - the new value of 'syntaxPrefix'

      • getSyntaxPrefix

        public java.lang.String getSyntaxPrefix()
        Returns the 'syntaxPrefix'.
        Returns:
        the 'syntaxPrefix'

      • setNewLine

        public void setNewLine​(java.lang.String newline)
        Sets the 'newLine'.
        Parameters:
        newline - the new value of 'newLine'

      • getNewLine

        public java.lang.String getNewLine()
        Returns the 'newLine'.
        Returns:
        the 'newLine'

      • setOptPrefix

        public void setOptPrefix​(java.lang.String prefix)
        Sets the 'optPrefix'.
        Parameters:
        prefix - the new value of 'optPrefix'

      • getOptPrefix

        public java.lang.String getOptPrefix()
        Returns the 'optPrefix'.
        Returns:
        the 'optPrefix'

      • setLongOptPrefix

        public void setLongOptPrefix​(java.lang.String prefix)
        Sets the 'longOptPrefix'.
        Parameters:
        prefix - the new value of 'longOptPrefix'

      • getLongOptPrefix

        public java.lang.String getLongOptPrefix()
        Returns the 'longOptPrefix'.
        Returns:
        the 'longOptPrefix'

      • setLongOptSeparator

        public void setLongOptSeparator​(java.lang.String longOptSeparator)
        Set the separator displayed between a long option and its value. Ensure that the separator specified is supported by the parser used, typically ' ' or '='.
        Parameters:
        longOptSeparator - the separator, typically ' ' or '='.

      • getLongOptSeparator

        public java.lang.String getLongOptSeparator()
        Returns the separator displayed between a long option and its value.
        Returns:
        the separator

      • setArgName

        public void setArgName​(java.lang.String name)
        Sets the 'argName'.
        Parameters:
        name - the new value of 'argName'

      • getArgName

        public java.lang.String getArgName()
        Returns the 'argName'.
        Returns:
        the 'argName'

      • getOptionComparator

        public java.util.Comparator<Option> getOptionComparator()
        Comparator used to sort the options when they output in help text. Defaults to case-insensitive alphabetical sorting by option key.
        Returns:
        the Comparator currently in use to sort the options

      • setOptionComparator

        public void setOptionComparator​(java.util.Comparator<Option> comparator)
        Set the comparator used to sort the options when they output in help text. Passing in a null comparator will keep the options in the order they were declared.
        Parameters:
        comparator - the Comparator to use for sorting the options

      • printHelp

        public void printHelp​(java.lang.String cmdLineSyntax,
                      Options options)
        Print the help for options with the specified command line syntax. This method prints help information to System.out.
        Parameters:
        cmdLineSyntax - the syntax for this application
        options - the Options instance

      • printHelp

        public void printHelp​(java.lang.String cmdLineSyntax,
                      Options options,
                      boolean autoUsage)
        Print the help for options with the specified command line syntax. This method prints help information to System.out.
        Parameters:
        cmdLineSyntax - the syntax for this application
        options - the Options instance
        autoUsage - whether to print an automatically generated usage statement

      • printHelp

        public void printHelp​(java.lang.String cmdLineSyntax,
                      java.lang.String header,
                      Options options,
                      java.lang.String footer)
        Print the help for options with the specified command line syntax. This method prints help information to System.out.
        Parameters:
        cmdLineSyntax - the syntax for this application
        header - the banner to display at the beginning of the help
        options - the Options instance
        footer - the banner to display at the end of the help

      • printHelp

        public void printHelp​(java.lang.String cmdLineSyntax,
                      java.lang.String header,
                      Options options,
                      java.lang.String footer,
                      boolean autoUsage)
        Print the help for options with the specified command line syntax. This method prints help information to System.out.
        Parameters:
        cmdLineSyntax - the syntax for this application
        header - the banner to display at the beginning of the help
        options - the Options instance
        footer - the banner to display at the end of the help
        autoUsage - whether to print an automatically generated usage statement

      • printHelp

        public void printHelp​(int width,
                      java.lang.String cmdLineSyntax,
                      java.lang.String header,
                      Options options,
                      java.lang.String footer)
        Print the help for options with the specified command line syntax. This method prints help information to System.out.
        Parameters:
        width - the number of characters to be displayed on each line
        cmdLineSyntax - the syntax for this application
        header - the banner to display at the beginning of the help
        options - the Options instance
        footer - the banner to display at the end of the help

      • printHelp

        public void printHelp​(int width,
                      java.lang.String cmdLineSyntax,
                      java.lang.String header,
                      Options options,
                      java.lang.String footer,
                      boolean autoUsage)
        Print the help for options with the specified command line syntax. This method prints help information to System.out.
        Parameters:
        width - the number of characters to be displayed on each line
        cmdLineSyntax - the syntax for this application
        header - the banner to display at the beginning of the help
        options - the Options instance
        footer - the banner to display at the end of the help
        autoUsage - whether to print an automatically generated usage statement

      • printHelp

        public void printHelp​(int width,
                      java.lang.String cmdLineSyntax,
                      java.lang.String header,
                      Options options,
                      int leftPad,
                      int descPad,
                      java.lang.String footer)
        Print the help for options with the specified command line syntax.
        Parameters:
        width - the number of characters to be displayed on each line
        cmdLineSyntax - the syntax for this application
        header - the banner to display at the beginning of the help
        options - the Options instance
        leftPad - the number of characters of padding to be prefixed to each line
        descPad - the number of characters of padding to be prefixed to each description line
        footer - the banner to display at the end of the help
        Throws:
        java.lang.IllegalStateException - if there is no room to print a line

      • printHelp

        public void printHelp​(int width,
                      java.lang.String cmdLineSyntax,
                      java.lang.String header,
                      Options options,
                      int leftPad,
                      int descPad,
                      java.lang.String footer,
                      boolean autoUsage)
        Print the help for options with the specified command line syntax.
        Parameters:
        width - the number of characters to be displayed on each line
        cmdLineSyntax - the syntax for this application
        header - the banner to display at the beginning of the help
        options - the Options instance
        leftPad - the number of characters of padding to be prefixed to each line
        descPad - the number of characters of padding to be prefixed to each description line
        footer - the banner to display at the end of the help
        autoUsage - whether to print an automatically generated usage statement
        Throws:
        java.lang.IllegalStateException - if there is no room to print a line

      • printUsage

        public void printUsage​(int width,
                       java.lang.String commandName,
                       Options options)
        Prints the usage statement for the specified command.
        Parameters:
        width - the number of characters to display per line
        commandName - the command name
        options - the command line Options

      • printUsage

        public void printUsage​(int width,
                       java.lang.String cmdLineSyntax)
        Print the cmdLineSyntax to the specified writer, using the specified width.
        Parameters:
        width - the number of characters per line for the usage statement
        cmdLineSyntax - the usage statement

      • printOptions

        public void printOptions​(int width,
                         Options options,
                         int leftPad,
                         int descPad)
        Print the help for the specified Options to the specified writer, using the specified width, left padding and description padding.
        Parameters:
        width - the number of characters to display per line
        options - the command line Options
        leftPad - the number of characters of padding to be prefixed to each line
        descPad - the number of characters of padding to be prefixed to each description line

      • printWrapped

        public void printWrapped​(int width,
                         java.lang.String text)
        Print the specified text to the specified PrintWriter.
        Parameters:
        width - the number of characters to display per line
        text - the text to be written to the PrintWriter

      • printWrapped

        public void printWrapped​(int width,
                         int nextLineTabStop,
                         java.lang.String text)
        Print the specified text to the specified PrintWriter.
        Parameters:
        width - the number of characters to display per line
        nextLineTabStop - the position on the next line for the first tab
        text - the text to be written to the PrintWriter

      • renderOptions

        protected java.lang.StringBuilder renderOptions​(java.lang.StringBuilder sb,
                                                int width,
                                                Options options,
                                                int leftPad,
                                                int descPad)
        Render the specified Options and return the rendered Options in a StringBuilder.
        Parameters:
        sb - the StringBuilder to place the rendered Options into
        width - the number of characters to display per line
        options - the command line Options
        leftPad - the number of characters of padding to be prefixed to each line
        descPad - the number of characters of padding to be prefixed to each description line
        Returns:
        the StringBuilder with the rendered Options contents

      • renderWrappedText

        protected java.lang.StringBuilder renderWrappedText​(java.lang.StringBuilder sb,
                                                    int width,
                                                    int nextLineTabStop,
                                                    java.lang.String text)
        Render the specified text and return the rendered Options in a StringBuilder.
        Parameters:
        sb - the StringBuilder to place the rendered text into
        width - the number of characters to display per line
        nextLineTabStop - the position on the next line for the first tab
        text - the text to be rendered
        Returns:
        the StringBuilder with the rendered Options contents