blob: 0557d37a1a12530109000e6f9e286018741bc5e9 [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
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
<author email="">commons-dev</author>
<section name="Introduction">
There are three stages to command line processing. They are the
definition, parsing and interrogation stages. The following
sections will discuss each of these stages in turn, and discuss how
to implement them with CLI.
<section name="Definition Stage">
Each command line must define the set of options that will be used
to define the interface to the application.
CLI uses the <a href="api-1.2/org/apache/commons/cli/Options.html">
Options</a> class, as a container for
<a href="api-1.2/org/apache/commons/cli/Option.html">
Option</a> instances. There are two ways to create
<code>Option</code>s in CLI. One of them is via the constructors,
the other way is via the factory methods defined in
The <a href="usage.html">Usage Scenarios</a> document provides
examples how to create an <code>Options</code> object and also
provides some real world examples.
The result of the definition stage is an <code>Options</code>
<section name="Parsing Stage">
The parsing stage is where the text passed into the
application via the command line is processed. The text is
processed according to the rules defined by the parser
The <code>parse</code> method defined on
<a href="api-1.2/org/apache/commons/cli/CommandLineParser.html">
CommandLineParser</a> takes an <code>Options</code>
instance and a <code>String[]</code> of arguments and
returns a
<a href="api-1.2/org/apache/commons/cli/CommandLine.html">
The result of the parsing stage is a <code>CommandLine</code>
<section name="Interrogation Stage">
The interrogation stage is where the application querys the
<code>CommandLine</code> to decide what execution branch to
take depending on boolean options and uses the option values
to provide the application data.
This stage is implemented in the user code. The accessor methods
on <code>CommandLine</code> provide the interrogation capability
to the user code.
The result of the interrogation stage is that the user code
is fully informed of all the text that was supplied on the command
line and processed according to the parser and <code>Options</code>