Skip to content

Commit b75b00a

Browse files
author
Robert James Oxspring
committed
Added CLI2 Overview documentation
git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/cli/trunk@179921 13f79535-47bb-0310-9956-ffa450edef68
1 parent 107ea06 commit b75b00a

2 files changed

Lines changed: 250 additions & 25 deletions

File tree

‎src/test/org/apache/commons/cli2/DocumentationTest.java‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@
2727
import org.apache.commons.cli2.builder.DefaultOptionBuilder;
2828
import org.apache.commons.cli2.builder.GroupBuilder;
2929
import org.apache.commons.cli2.commandline.Parser;
30+
import org.apache.commons.cli2.option.DefaultOption;
3031
import org.apache.commons.cli2.option.PropertyOption;
3132
import org.apache.commons.cli2.util.HelpFormatter;
3233

@@ -148,6 +149,81 @@ public void testBasicUsage() throws IOException, OptionException {
148149
uoe.getMessage());
149150
}
150151
}
152+
153+
public void testManualIntroduction() {
154+
155+
DefaultOptionBuilder oBuilder = new DefaultOptionBuilder();
156+
ArgumentBuilder aBuilder = new ArgumentBuilder();
157+
GroupBuilder gBuilder = new GroupBuilder();
158+
159+
DefaultOption xmlOption =
160+
oBuilder
161+
.withLongName("xml")
162+
.withDescription("Output using xml format")
163+
.create();
164+
165+
Argument pathArgument =
166+
aBuilder
167+
.withName("path")
168+
.withMinimum(1)
169+
.withMaximum(1)
170+
.create();
171+
172+
Group outputChildren =
173+
gBuilder
174+
.withOption(xmlOption)
175+
.create();
176+
177+
Option outputOption =
178+
oBuilder
179+
.withLongName("output")
180+
.withDescription("Outputs to a file")
181+
.withArgument(pathArgument)
182+
.withChildren(outputChildren)
183+
.create();
184+
185+
///////////////////////////////////////////////////
186+
187+
try {
188+
Group options = null;
189+
HelpFormatter hf = new HelpFormatter();
190+
191+
Parser p = new Parser();
192+
p.setGroup(options);
193+
p.setHelpFormatter(hf);
194+
p.setHelpTrigger("--help");
195+
CommandLine cl = p.parseAndHelp(new String[]{});
196+
if(cl==null) {
197+
System.exit(-1);
198+
}
199+
} catch (IOException e) {
200+
// TODO Auto-generated catch block
201+
e.printStackTrace();
202+
}
203+
204+
//////////////////////////////////////////////////
205+
206+
CommandLine cl = null;
207+
208+
// if we have --output option
209+
if(cl.hasOption("--output")) {
210+
// grab the path
211+
String path = (String)cl.getValue("--output");
212+
// grab the format
213+
boolean xml = cl.hasOption("--xml");
214+
// configure the application's output
215+
configureOutput(path,xml);
216+
}
217+
218+
219+
220+
221+
}
222+
223+
private void configureOutput(String path, boolean xml) {
224+
// TODO Auto-generated method stub
225+
226+
}
151227

152228
public void testExampleAnt() throws IOException, OptionException {
153229
// Apache Ant version 1.6.1 compiled on February 12 2004

‎xdocs/manual/index.xml‎

Lines changed: 174 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0"?>
22
<!--
3-
Copyright 2004 The Apache Software Foundation
3+
Copyright 2004-2005 The Apache Software Foundation
44
55
Licensed under the Apache License, Version 2.0 (the "License");
66
you may not use this file except in compliance with the License.
@@ -15,29 +15,178 @@
1515
limitations under the License.
1616
-->
1717
<document>
18+
19+
<properties>
20+
<author email="commons-dev@jakarta.apache.org">commons-dev</author>
21+
<title>CLI2 - Overview</title>
22+
</properties>
23+
24+
<body>
25+
<section name="Overview">
26+
<p>
27+
CLI Breaks down command line processing into three distinct phases, the
28+
first of which is to create a model of the command line you wish to process. The
29+
second phase is arguably the most important as it involves processing the
30+
command line arguments of the application according to the model created.
31+
Finally the parsed command line is available to be queried by the
32+
application proper. The phases are discussed in more detail below.
33+
</p>
34+
<subsection name="Modelling the interface">
35+
<p>
36+
In CLI2 a command line is modelled as a Group composed of many Options.
37+
There are a number different Option implementations available to be
38+
used including DefaultOption, Switch and Command which may all have an
39+
Argument and/or a Group of child options associated with them. An
40+
example of where this parental relationship could be used is where you
41+
need to allow for the following scenario where one option
42+
only makes sense within the context of another:
43+
</p>
44+
<p><code>myapp --output path/to/file --xml</code></p>
45+
<p>
46+
Typically this command line would be modelled as a DefaultOption
47+
(<code>--output</code>) with an Argument (to capture
48+
<code>path/to/file</code>) and a Group of children consisting of a
49+
DefaultOption (<code>--xml</code>) since the format only applies if the
50+
output is specified
51+
</p>
52+
<p>
53+
The various Option implementations provided need careful configuration
54+
and constructors take a complex set of arguments. To ease the construction
55+
of these options *Builder classes (e.g. DefaultOptionBuilder, GroupBuilder
56+
and ArgumentBuilder) have been supplied following the
57+
<a href="http://c2.com/cgi/wiki?BuilderPattern">Builder Pattern</a>
58+
which essentially involves using the DefaultOptionBuilder class to create
59+
instances of DefaultOption using descriptive method calls instead of
60+
anonymous arguments to a constructor. The following example demonstrates how
61+
the command line shown above could be modelled in code:
62+
</p>
63+
<source>
64+
DefaultOptionBuilder oBuilder = new DefaultOptionBuilder();
65+
ArgumentBuilder aBuilder = new ArgumentBuilder();
66+
GroupBuilder gBuilder = new GroupBuilder();
1867

19-
<properties>
20-
<author email="commons-dev@jakarta.apache.org">commons-dev</author>
21-
<title>CLI2 - Overview</title>
22-
</properties>
23-
24-
<body>
25-
<section name="Overview">
26-
<p>TODO quick overview to the overview</p>
27-
<subsection name="Modelling the interface">
28-
<p>TODO terminology</p>
29-
<p>TODO basic options</p>
30-
<p>TODO option builders</p>
31-
</subsection>
32-
<subsection name="Parsing the command line">
33-
<p>TODO Parser</p>
34-
<p>TODO OptionException</p>
35-
<p>TODO HelpFormatter</p>
36-
</subsection>
37-
<subsection name="Querying the result">
38-
<p>TODO CommandLine</p>
39-
<p>TODO DefaultingCommandLine</p>
40-
</subsection>
41-
</section>
42-
</body>
68+
DefaultOption xmlOption =
69+
oBuilder
70+
.withLongName("xml")
71+
.withDescription("Output using xml format")
72+
.create();
73+
74+
Argument pathArgument =
75+
aBuilder
76+
.withName("path")
77+
.withMinimum(1)
78+
.withMaximum(1)
79+
.create();
80+
81+
Group outputChildren =
82+
gBuilder
83+
.withOption(xmlOption)
84+
.create();
85+
86+
Option outputOption =
87+
oBuilder
88+
.withLongName("output")
89+
.withDescription("Outputs to a file")
90+
.withArgument(pathArgument)
91+
.withChildren(outputChildren)
92+
.create();
93+
</source>
94+
<p>
95+
The <a href="options.html">Options</a> and
96+
<a href="builders.html">Builders</a> sections of the manual discuss these
97+
features in greater detail.
98+
</p>
99+
<p>
100+
Once all the options have been composed into a Group modelling the complete
101+
option model then we are ready to parse a command line.
102+
</p>
103+
</subsection>
104+
<subsection name="Parsing the command line">
105+
<p>
106+
The Parser class can be used to parse an array of arguments against the
107+
option model into a CommandLine. The parsing is driven by the
108+
<code>parse(String[])</code> method which delegates to the option model to do
109+
the actual parsing, with each Option implementation providing its own parsing
110+
logic. The <code>parseAndHelp(String[])</code> method attempts to simplify
111+
the use of the former method by automatically handling any <code>--help</code>
112+
options and displaying error messages where appropriate.
113+
</p>
114+
<p>
115+
The HelpFormatter class is designed to allow the option model to be described
116+
to the user in a manner typical of command line applications. The
117+
HelpFormatter is designed with flexibility in mind so it should be possible to
118+
control exactly which structures are described to the user and what level of
119+
detail to use. The HelpFormatter is discussed in detail in the
120+
<a href="utilities.html#HelpFormatter">Utilities</a> section of the manual.
121+
</p>
122+
<p>
123+
Any errors that occur while parsing result in an OptionException being thrown
124+
which attempt to provide a meaningful message describing the problem to the
125+
user. Parser's <code>parseAndHelp(String[])</code> method catches any
126+
OptionException and uses the HelpFormatter to display to the user:
127+
</p>
128+
<source>
129+
// configure the options
130+
Group options = ...;
131+
132+
// configure a HelpFormatter
133+
HelpFormatter hf = new HelpFormatter();
134+
135+
// configure a parser
136+
Parser p = new Parser();
137+
p.setGroup(options);
138+
p.setHelpFormatter(hf);
139+
p.setHelpTrigger("--help");
140+
CommandLine cl = p.parseAndHelp(new String[]{});
141+
142+
// abort application if no CommandLine was parsed
143+
if(cl==null) {
144+
System.exit(-1);
145+
}
146+
</source>
147+
148+
<p>
149+
Assuming that OptionExceptions have been averted then the next step is to have
150+
the application query the resulting CommandLine instance.
151+
</p>
152+
</subsection>
153+
<subsection name="Querying the result">
154+
<p>
155+
The CommandLine interface provides lots of ways to look up information either
156+
by Option instance or by a String representing any of the forms valid on the
157+
command line. For example if an option is configured with multiple names
158+
(e.g. <code>-?</code>, <code>-h</code>, <code>--help</code>) then any of the
159+
those strings can be used to look up the value irrespective of which form
160+
appeared on the command line.
161+
</p>
162+
<p>
163+
The <code>hasOption()</code> family of methods can be used to simply test for
164+
the presence of options, while the <code>getValues()</code> family of methods
165+
can be used to retrieve the values associated with Arguments. The status of
166+
any Switch options can be detected through the use of <code>getSwitch()</code>
167+
methods which will return a Boolean if set or null otherwise:
168+
</p>
169+
<source>
170+
// if we have --output option
171+
if(cl.hasOption("--output")) {
172+
// grab the path
173+
String path = (String)cl.getValue("--output");
174+
// grab the format
175+
boolean xml = cl.hasOption("--xml");
176+
// configure the application's output
177+
configureOutput(path,xml);
178+
}
179+
</source>
180+
<p>
181+
To enable complex CommandLine configurations alternative implementations are
182+
provided that can wrap a Properties or Preferences instance as a CommandLine.
183+
These can then be combined with the DefaultingCommandLine and the parsed
184+
CommandLine to provide a variety of different defaulting and overriding
185+
scenarios. The CommandLine interface and implementations are discussed
186+
further in the <a href="commandlines.html">CommandLines</a> section of the
187+
manual.
188+
</p>
189+
</subsection>
190+
</section>
191+
</body>
43192
</document>

0 commit comments

Comments
 (0)