Compute command-line arguments with Apache Commons CLI

For a project at school, I needed to refactor an old code parsing almost 30 command line arguments. I needed to add some more arguments and change some old args, but the old code was not maintainable at all. So I decided to use a library to make the parsing. of the args.

I chose Apache Commons CLI. This is a really simple library to make that parsing. It's not perfect, but it makes the work I needed and is powerful to do that job.

With this API, you have to declare an Options instance. This class is used to describe the command line arguments of the program. Options constructor don't take any arguments.

Options options = new Options();

Then you have to use the addOption methods to add some arguments to the application. There is three versions of the methods :

• addOption(Option opt) : Add an option of the class Option.
• addOption(String opt, boolean hasArg, String description) : Add a new option to the arguments. This option has only a short name.
• addOption(String opt, String longOpt, boolean hasArg, String description) : Add a new option to the arguments. The option has a short name and a long name.

We need some explanations here. The short opt is used to define an arg with a simple dash (-shortopt) and the long opt is defined with double dash (--longopt). The hasArg indicate if the parameter accepts an argument. The description is, like its name indicates, the description of the option. It's used to print the help of the program.

Using Option instances you can configure all the properties of an option using the setters and the constructor. Here is all the setters that can be used to configure the option :

• void setArgName(String argName) : The name of the args
• void setArgs(int num) : The number of args the option takes
• void setDescription(String description) : The description of the option
• void setLongOpt(String longOpt) : The long option name
• void setOptionalArg(boolean optionalArg) : Indicate if the argument of this option is optional
• void setRequired(boolean required) : Indicate if the option is required or not
• void setType(Object type) : Set the type of the Option. Here are the supported type : File.class, Number.class, Class.class, Object.class, Url.class
• void setValueSeparator(char sep) : Set the value separator, it's used to make a system like the property of Java like -Dmaven.test.skip=true, the separator is =

There is also an other way to create Option instance, using the OptionBuilder class. It's a little weird because all the methods are static and the method returns a reference to the builder. And then you make a call to the builder instance using the static method. The method are equivalent with the methods of the Option class with different names (withXXX, hasXXX, ...). When you have configured the option, you have to call one of the create methods to create the instance and reset the OptionBuilder.

Once you filled the Options instance with the arguments of the program, you can use it. You have to use a CommandLineParser to parse the Options. There is three implementation of this interface :

• BasicParser : A very simple parser
• PosixParser : A parser to parse short options
• GnuParser : A parser to parse both long and short options

A simple example using the GnuParser :

CommandLineParser parser = new GnuParser();

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

You receive a CommandLine object representing all the arguments. The parse() method can throw a ParseException if the given arguments are not valid. With that object, you can get the options that have been passed to the application. For that, you can use the given methods :

• Object getOptionObject : Return the option value parsed to the specified type
• Properties getOptionProperties(String opt)
• String getOptionValue : Return the value of the option
• String[] getOptionValues : Return the values of the option
• Object getParsedOptionValue(String opt) : Return the option value parsed to the specified type
• boolean hasOption : Indicate if the option has been specified or not
• List getArgList() : Return all the args that are not specified args
• String[] getArgs() : Return all the args that are not specified args

With this API, you can also generate the help of the program :

HelpFormatter formatter = new HelpFormatter();

formatter.printHelp( "program", options);

With that, you display the list of arguments taken by the program.

With that example, we've seen the main features of this library.

For more information, you consult the Apache Commons CLI website.

Related articles