Common Java Cookbook

Edition: 0.19

Download PDF or Read on Scribd

Download Examples (ZIP)

7.4. Printing Usage Information

7.4.1. Problem

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

7.4.2. 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

7.4.3. 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.


Creative Commons License
Common Java Cookbook by Tim O'Brien is licensed under a Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 United States License.
Permissions beyond the scope of this license may be available at http://www.discursive.com/books/cjcook/reference/jakartackbk-PREFACE-1.html. Copyright 2009. Common Java Cookbook Chunked HTML Output. Some Rights Reserved.