7.4. Printing Usage Information

Problem

You need to provide the user with a formatted list of available options.

Solution

Pass an Options object to a HelpFormatter and print a usage message. Example 7-1 creates the same Options object from Recipe 7.3. If the help option is specified, or if there is a problem parsing the program arguments, the printUsage() method is called to print usage information to System.out.

Example 7-1. Printing usage information with HelpFormatter

                  import org.apache.commons.cli.CommandLineParser;
                  import org.apache.commons.cli.BasicParser;
                  import org.apache.commons.cli.Options;
                  import org.apache.commons.cli.OptionBuilder;
                  import org.apache.commons.cli.OptionGroup;
                  import org.apache.commons.cli.CommandLine;
                  import org.apache.commons.cli.HelpFormatter;

                  public class SomeApp {
                      private static final String USAGE = "[-h] [-v] [-f <file> | -m <email>]";
                      private static final String HEADER =
                          "SomeApp - A fancy and expensive program, Copyright 2010 Blah.";
                      private static final String FOOTER =
                          "For more instructions, see our website at: http://www.blah123.org";

                      public 
                  static 
                  void main(String[] args) throws Exception {

        // Create a Parser
        CommandLineParser parser = new BasicParser( );
        Options options = new Options( );
        options.addOption("h", "help", false, "Print this usage 
                                                                      information");
        options.addOption("v", "verbose", false, "Print out VERBOSE 
                                                                         information" );

        OptionGroup optionGroup = new OptionGroup( ); 
        optionGroup.addOption( OptionBuilder.hasArg(true).withArgName("file")
                                            .withLongOpt("file").create('f') );
        optionGroup.addOption( OptionBuilder.hasArg(true).withArgName("email")
                                            .withLongOpt("email").create('m') );
        options.addOptionGroup( optionGroup );
           // Parse the program arguments
        try {
            CommandLine commandLine = parser.parse( options, args );

            if( commandLine.hasOption('h') ) {
                printUsage( options );
                System.exit(0);
            }
    
               // ... do important stuff ...
        } catch( Exception e ) {
            System.out.println( "You provided bad program arguments!" );
            printUsage( options );
            System.exit(1);
        }
    }

    private static void printUsage(Options options) {
        HelpFormatter helpFormatter = new HelpFormatter( );
        helpFormatter.setWidth( 80 );
        helpFormatter.printHelp( USAGE, HEADER, options, FOOTER );
    }
}

When this application is executed and the parser encounters an unexpected program argument, the following output is produced:

You provided bad program arguments!
usage: [-h] [-v] [-f <file> | -m <email>]
SomeApp - A fancy and expensive program, Copyright 2010 Blah.
 -f,--file <file>
 -h,--help            Print this usage information
 -m,--email <email>
 -v,--verbose         Print out VERBOSE information
For more instructions, see our website at: http://www.blah123.org

Discussion

If an exception is thrown during parser.parse( ), the application will print an error message and call printUsage( ), which creates a HelpFormatter object and sets the display width to 80 characters. helpFormatter.printHelp( ) prints to standard out and takes five parameters, including the Options object, which contains configuration for the CommandLineParser. The first parameter specified a usage string, which is an abbreviated specification of the program arguments: -h, -v, and -f <file> | -m <email>. The second argument is a header to print before the list of available options. The third parameter is the same Options object passed to the CommandLineParser. HelpFormatter will use this Options object to print out the short name, long name, and description of each option. The fourth parameter is a footer to display after the list of options.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.144.242.235