blob: b9c83f3909539e30c5350748a27d747d5517a6f7 [file] [log] [blame]
<?xml version="1.0"?>
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.
<author email="">commons-dev</author>
<title>CLI2 - Overview</title>
<section name="Overview">
CLI Breaks down command line processing into three distinct phases, the
first of which is to create a model of the command line you wish to process. The
second phase is arguably the most important as it involves processing the
command line arguments of the application according to the model created.
Finally the parsed command line is available to be queried by the
application proper. The phases are discussed in more detail below.
<subsection name="Modelling the interface">
In CLI2 a command line is modelled as a Group composed of many Options.
There are a number different Option implementations available to be
used including DefaultOption, Switch and Command which may all have an
Argument and/or a Group of child options associated with them. An
example of where this parental relationship could be used is where you
need to allow for the following scenario where one option
only makes sense within the context of another:
<p><code>myapp --output path/to/file --xml</code></p>
Typically this command line would be modelled as a DefaultOption
(<code>--output</code>) with an Argument (to capture
<code>path/to/file</code>) and a Group of children consisting of a
DefaultOption (<code>--xml</code>) since the format only applies if the
output is specified
The various Option implementations provided need careful configuration
and constructors take a complex set of arguments. To ease the construction
of these options *Builder classes (e.g. DefaultOptionBuilder, GroupBuilder
and ArgumentBuilder) have been supplied following the
<a href="">Builder Pattern</a>
which essentially involves using the DefaultOptionBuilder class to create
instances of DefaultOption using descriptive method calls instead of
anonymous arguments to a constructor. The following example demonstrates how
the command line shown above could be modelled in code:
DefaultOptionBuilder oBuilder = new DefaultOptionBuilder();
ArgumentBuilder aBuilder = new ArgumentBuilder();
GroupBuilder gBuilder = new GroupBuilder();
DefaultOption xmlOption =
.withDescription("Output using xml format")
Argument pathArgument =
Group outputChildren =
Option outputOption =
.withDescription("Outputs to a file")
The <a href="options.html">Options</a> and
<a href="builders.html">Builders</a> sections of the manual discuss these
features in greater detail.
Once all the options have been composed into a Group modelling the complete
option model then we are ready to parse a command line.
<subsection name="Parsing the command line">
The Parser class can be used to parse an array of arguments against the
option model into a CommandLine. The parsing is driven by the
<code>parse(String[])</code> method which delegates to the option model to do
the actual parsing, with each Option implementation providing its own parsing
logic. The <code>parseAndHelp(String[])</code> method attempts to simplify
the use of the former method by automatically handling any <code>--help</code>
options and displaying error messages where appropriate.
The HelpFormatter class is designed to allow the option model to be described
to the user in a manner typical of command line applications. The
HelpFormatter is designed with flexibility in mind so it should be possible to
control exactly which structures are described to the user and what level of
detail to use.
Any errors that occur while parsing result in an OptionException being thrown
which attempt to provide a meaningful message describing the problem to the
user. Parser's <code>parseAndHelp(String[])</code> method catches any
OptionException and uses the HelpFormatter to display to the user:
// configure the options
Group options = ...;
// configure a HelpFormatter
HelpFormatter hf = new HelpFormatter();
// configure a parser
Parser p = new Parser();
CommandLine cl = p.parseAndHelp(new String[]{});
// abort application if no CommandLine was parsed
if(cl==null) {
Assuming that OptionExceptions have been averted then the next step is to have
the application query the resulting CommandLine instance.
<subsection name="Querying the result">
The CommandLine interface provides lots of ways to look up information either
by Option instance or by a String representing any of the forms valid on the
command line. For example if an option is configured with multiple names
(e.g. <code>-?</code>, <code>-h</code>, <code>--help</code>) then any of the
those strings can be used to look up the value irrespective of which form
appeared on the command line.
The <code>hasOption()</code> family of methods can be used to simply test for
the presence of options, while the <code>getValues()</code> family of methods
can be used to retrieve the values associated with Arguments. The status of
any Switch options can be detected through the use of <code>getSwitch()</code>
methods which will return a Boolean if set or null otherwise:
// if we have --output option
if(cl.hasOption("--output")) {
// grab the path
String path = (String)cl.getValue("--output");
// grab the format
boolean xml = cl.hasOption("--xml");
// configure the application's output
To enable complex CommandLine configurations alternative implementations are
provided that can wrap a Properties or Preferences instance as a CommandLine.
These can then be combined with the DefaultingCommandLine and the parsed
CommandLine to provide a variety of different defaulting and overriding