Apache commons cli java

Apache Commons CLI

The Apache Commons CLI library provides an API for parsing command line options passed to programs. It’s also able to print help messages detailing the options available for a command line tool.

Commons CLI supports different types of options:

POSIX like options, for example tar -zxvf foo.tar.gz
GNU like long options, for example du —human-readable —max-depth=1
Java like properties, for example java -Djava.awt.headless=true -Djava.net.useSystemProxies=true Foo
Short options with value attached, for example gcc -O2 foo.c
long options with single hyphen, for example ant -projecthelp

A typical help message displayed by Commons CLI looks like this:

usage: ls -A,--almost-all do not list implied . and .. -a,--all do not hide entries starting with . -B,--ignore-backups do not list implied entried ending with ~ -b,--escape print octal escapes for nongraphic characters --block-size use SIZE-byte blocks -c with -lt: sort by, and show, ctime (time of last modification of file status information) with -l:show ctime and sort by name otherwise: sort by ctime -C list entries by columns

Check out the introduction page for a detailed presentation.

Documentation

A full User’s Guide is available as are various project reports.

The Javadoc API documents are available online:

Releases

Download the latest version.
The release notes are also available.

For previous releases, see the Apache Archive.

Support

The commons mailing lists act as the main support forum. The user list is suitable for most library usage queries. The dev list is intended for the development discussion. Please remember that the lists are shared between all commons components, so prefix your email subject by [cli] .

Issues may be reported via the ASF JIRA.

CLI 2?

Commons CLI 1.0 was formed from the merger of ideas and code from three different libraries — Werken, Avalon and Optz. In dealing with the bugs and the feature requests a freshly designed and not backwards compatible CLI 2 was created in 2004, but never finished or released.

The current plan is to continue to maintain the 1.x line. The CLI2 work may be found in the Commons Sandbox.

Apache Commons, Apache Commons CLI, Apache, the Apache feather logo, and the Apache Commons project logos are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.

Источник

Apache commons cli java

Using Apache Commons CLI

The following sections describe some example scenarios on how to use CLI in applications.

Using a boolean option

A boolean option is represented on a command line by the presence of the option, i.e. if the option is found then the option value is true , otherwise the value is false .

The DateApp utility prints the current date to standard output. If the -t option is present the current time is also printed.

Creating the Options

An Options object must be created and the Option must be added to it.

// create Options object Options options = new Options(); // add t option options.addOption("t", false, "display current time");

The addOption method has three parameters. The first parameter is a java.lang.String that represents the option. The second parameter is a boolean that specifies whether the option requires an argument or not. In the case of a boolean option (sometimes referred to as a flag) an argument value is not present so false is passed. The third parameter is the description of the option. This description will be used in the usage text of the application.

Parsing the command line arguments

The parse methods of CommandLineParser are used to parse the command line arguments. There may be several implementations of the CommandLineParser interface, the recommended one is the DefaultParser .

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

Now we need to check if the t option is present. To do this we will interrogate the CommandLine object. The hasOption method takes a java.lang.String parameter and returns true if the option represented by the java.lang.String is present, otherwise it returns false .

Note.

As of version 1.5, the DefaultParser ‘s constructor now has an override with the signature DefaultParser(final boolean allowPartialMatching) . Given the following code:

final Options options = new Options(); options.addOption(new Option("d", "debug", false, "Turn on debug.")); options.addOption(new Option("e", "extract", false, "Turn on extract.")); options.addOption(new Option("o", "option", true, "Turn on option with argument."));

we define «partial matching» as -de only matching the «debug» option. We can consequently, now, turn this off and have -de match both the debug option as well as the extract option.

International Time

The InternationalDateApp utility extends the DateApp utility by providing the ability to print the date and time in any country in the world. To facilitate this a new command line option, c , has been introduced.

// add c option options.addOption("c", true, "country code");

The second parameter is true this time. This specifies that the c option requires an argument value. If the required option argument value is specified on the command line it is returned, otherwise null is returned.

Retrieving the argument value

The getOptionValue methods of CommandLine are used to retrieve the argument values of options.

// get c option value String countryCode = cmd.getOptionValue("c"); if(countryCode == null) < // print default date >else < // print date for country specified by countryCode >

Using Ant as an Example

Ant will be used here to illustrate how to create the Options required. The following is the help output for Ant.

ant [options] [target [target2 [target3] . ]] Options: -help print this message -projecthelp print project help information -version print the version information and exit -quiet be extra quiet -verbose be extra verbose -debug print debugging information -emacs produce logging information without adornments -logfile use given file for log -logger the class which is to perform logging -listener add an instance of class as a project listener -buildfile use given buildfile -D= use value for given property -find search for buildfile towards the root of the filesystem and use it

Defining Boolean Options

Lets create the boolean options for the application as they are the easiest to create. For clarity the constructors for Option are used here.

Option help = new Option("help", "print this message"); Option projecthelp = new Option("projecthelp", "print project help information"); Option version = new Option("version", "print the version information and exit"); Option quiet = new Option("quiet", "be extra quiet"); Option verbose = new Option("verbose", "be extra verbose"); Option debug = new Option("debug", "print debugging information"); Option emacs = new Option("emacs", "produce logging information without adornments");

Defining Argument Options

The argument options are created using the Option#Builder .

Option logfile = Option.builder("logfile") .argName("file") .hasArg() .desc("use given file for log") .build(); Option logger = Option.builder("logger") .argName("classname") .hasArg() .desc("the class which it to perform logging") .build(); Option listener = Option.builder("listener") .argName("classname") .hasArg() .desc("add an instance of class as " + "a project listener") .build(); Option buildfile = Option.builder("buildfile") .argName("file") .hasArg() .desc("use given buildfile") .build(); Option find = Option.builde("find") .argName("file") .hasArg() .desc("search for buildfile towards the " + "root of the filesystem and use it") .build();

Defining Java Property Option

The last option to create is the Java property and it is also created using the OptionBuilder.

Option property = Option property = Option.builder("D") .hasArgs() .valueSeparator('=') .build();

The map of properties specified by this option can later be retrieved by calling getOptionProperties(«D») on the CommandLine .

Creating the Options

Now that we have created each Option we need to create the Options instance. This is achieved using the addOption method of Options .

Options options = new Options(); options.addOption(help); options.addOption(projecthelp); options.addOption(version); options.addOption(quiet); options.addOption(verbose); options.addOption(debug); options.addOption(emacs); options.addOption(logfile); options.addOption(logger); options.addOption(listener); options.addOption(buildfile); options.addOption(find); options.addOption(property);

All the preperation is now complete and we are now ready to parse the command line arguments.

Creating the Parser

We now need to create a CommandLineParser . This will parse the command line arguments, using the rules specified by the Options and return an instance of CommandLine.

public static void main(String[] args) < // create the parser CommandLineParser parser = new DefaultParser(); try < // parse the command line arguments CommandLine line = parser.parse(options, args); >catch (ParseException exp) < // oops, something went wrong System.err.println("Parsing failed. Reason: " + exp.getMessage()); >>

Querying the commandline

To see if an option has been passed the hasOption method is used. The argument value can be retrieved using the getOptionValue method.

// has the buildfile argument been passed? if(line.hasOption("buildfile")) < // initialise the member variable this.buildfile = line.getOptionValue("buildfile"); >

Displaying Usage and Help

CLI also provides the means to automatically generate usage and help information. This is achieved with the HelpFormatter class.

// automatically generate the help statement HelpFormatter formatter = new HelpFormatter(); formatter.printHelp("ant", options);

When executed the following output is produced:

usage: ant -D use value for given property -buildfile use given buildfile -debug print debugging information -emacs produce logging information without adornments -file search for buildfile towards the root of the filesystem and use it -help print this message -listener add an instance of class as a project listener -logger the class which it to perform logging -projecthelp print project help information -quiet be extra quiet -verbose be extra verbose -version print the version information and exit

If you also require to have a usage statement printed then calling formatter.printHelp(«ant», options, true) will generate a usage statment as well as the help information.

Читайте также: Table in tkinter python

Creating an ls Example

One of the most widely used command line applications in the *nix world is ls . Due to the large number of options required for ls this example will only cover a small proportion of the options. The following is a section of the help output.

Usage: ls [OPTION]. [FILE]. List information about the FILEs (the current directory by default). Sort entries alphabetically if none of -cftuSUX nor --sort. -a, --all do not hide entries starting with . -A, --almost-all do not list implied . and .. -b, --escape print octal escapes for non-graphic characters --block-size=SIZE use SIZE-byte blocks -B, --ignore-backups do not list implied entries ending with ~ -c with -lt: sort by, and show, ctime (time of last modification of file status information) with -l: show ctime and sort by name otherwise: sort by ctime -C list entries by columns

The following is the code that is used to create the Options for this example.

// create the command line parser CommandLineParser parser = new DefaultParser(); // create the Options Options options = new Options(); options.addOption(«a», «all», false, «do not hide entries starting with .»); options.addOption(«A», «almost-all», false, «do not list implied . and ..»); options.addOption(«b», «escape», false, «print octal escapes for non-graphic » + «characters»); options.addOption(Option.builder(«SIZE»).longOpt(«block-size») .desc(«use SIZE-byte blocks») .hasArg() .build()); options.addOption(«B», «ignore-backups», false, «do not list implied entries » + «ending with ~»); options.addOption(«c», false, «with -lt: sort by, and show, ctime (time of last » + «modification of file status information) with » + «-l:show ctime and sort by name otherwise: sort » + «by ctime»); options.addOption(«C», false, «list entries by columns»); String[] args = new String[]< "--block-size=10" >; try < // parse the command line arguments CommandLine line = parser.parse(options, args); // validate that block-size has been set if (line.hasOption("block-size")) < // print the value of block-size System.out.println(line.getOptionValue("block-size")); >> catch (ParseException exp)

Источник