Skip to main content Link Menu Expand (external link) Document Search Copy Copied
Syntax Savvy

Using Help

Header Image

Ahoy there mateys! Today we’re going to talk about a feature that will help your crewmates navigate your command line interface with ease. We’re talking about none other than adding help text to the command line parser.

Imagine you’re the captain of a ship, and you’ve just updated your command line interface with some new options. Your crewmates are used to the old options, and they’re feeling a bit lost. You can’t have them running around the deck like a bunch of landlubbers! That’s where help text comes in.

Adding Help Text

Adding help text to your command line interface is easy with Apache Commons CLI. You can provide a brief description of each option, along with usage examples and any other relevant information that will help your crewmates understand how to use your command line interface.

Options options = new Options();

Option foo = new Option("f", "foo", true, "Specify foo");
foo.setRequired(true);
options.addOption(foo);

Option bar = new Option("b", "bar", true, "Specify bar");
bar.setRequired(true);
options.addOption(bar);

Option help = new Option("h", "help", false, "Print help message");
options.addOption(help);

CommandLineParser parser = new DefaultParser();

try {
    CommandLine cmd = parser.parse(options, args);

    if (cmd.hasOption("h")) {
        HelpFormatter formatter = new HelpFormatter();
        formatter.printHelp("myapp", options);
        System.exit(0);
    }

    String fooValue = cmd.getOptionValue("f");
    String barValue = cmd.getOptionValue("b");

    // ... do something with fooValue and barValue ...

} catch (ParseException e) {
    System.err.println(e.getMessage());
    System.exit(1);
}

In the example above, we’ve added a help option to our command line interface. If the user includes the -h or --help option, we print out a usage message that explains how to use the interface. We’ve used the HelpFormatter class to format the output of the help message.

Displaying Help Information to the User

Now that we’ve covered adding help text to the command line parser, let’s talk about how to display that help information to the user. After all, what good is help text if your crewmates don’t know how to access it?

In the previous example, we used the HelpFormatter class to format the output of the help message. We passed the name of our application, "myapp", and the Options object to the printHelp method, and it produced a nicely formatted usage message.

HelpFormatter formatter = new HelpFormatter();
formatter.printHelp("myapp", options);

We could also provide additional information to the printHelp method, such as a header and footer message. This can be useful for providing additional context or instructions to the user.

HelpFormatter formatter = new HelpFormatter();
formatter.printHelp("myapp", "A command line interface for managing my ship", options, "The pirate's code is more what you'd call 'guidelines' than actual rules.", true);

The printHelp method takes several arguments:

  • String cmdLineSyntax: The name of your command line application.
  • String header: A header message to include at the top of the help output.
  • Options options: The Options object that contains the option definitions.
  • String footer: A footer message to include at the bottom of the help output.
  • boolean autoUsage: Whether to print the usage message automatically.

With these options, you can customize the help output to provide the information that your crewmates need to understand and use your command line interface.

Conclusion

In this article, we’ve covered how to add help text to your command line interface using Apache Commons CLI. We’ve also discussed how to display that help information to the user using the HelpFormatter class.

By providing clear and concise usage messages, you can help your crewmates navigate your command line interface with ease. And by using the HelpFormatter class, you can format those messages in a way that is both informative and visually appealing.

Now go forth, me hearties, and make your command line interfaces the envy of all the seven seas!