Skip to content

Commit 4ee78d5

Browse files
author
Robert James Oxspring
committed
Documented the various options and their properties
git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/cli/trunk@130096 13f79535-47bb-0310-9956-ffa450edef68
1 parent 0d140b6 commit 4ee78d5

1 file changed

Lines changed: 330 additions & 0 deletions

File tree

‎xdocs/manual/options.xml‎

Lines changed: 330 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,22 +25,352 @@
2525
<section name="Options">
2626
<img src="../images/options.jpg"/>
2727
<subsection name="Option">
28+
<p>
29+
In CLI2 every element of the command line interface is modelled as an
30+
Option instance, and has the following readonly properties that are
31+
inherited by all other Option implementations:
32+
</p>
33+
<table>
34+
<tr>
35+
<th>Property</th><th>Type</th><th>Description</th>
36+
</tr>
37+
<tr>
38+
<td>id</td>
39+
<td>int</td>
40+
<td>
41+
Some people find it useful to give each option a unique identifer
42+
so that they can use the options within a java <code>switch</code>
43+
statement. This value is entirely optional and it is up to the
44+
user to ensure any uniqueness.
45+
</td>
46+
</tr>
47+
<tr>
48+
<td>preferredName</td>
49+
<td>String</td>
50+
<td>
51+
Every option has a preferred name that can be used for the minimal
52+
<code>toString()</code> implementation. Options can usually have
53+
many additional names too.
54+
</td>
55+
</tr>
56+
<tr>
57+
<td>required</td>
58+
<td>boolean</td>
59+
<td>
60+
True here indicates that the command line is invalid if this
61+
option doesn't appear on it.
62+
</td>
63+
</tr>
64+
</table>
2865
</subsection>
66+
2967
<subsection name="Group">
68+
<source>-a|-b|-c|-d|-e</source>
69+
<p>
70+
Groups are possible the least intuitive form of Option since they
71+
actually represent a collection of other options. Most member Options
72+
can appear on a command line in any order with the exception of
73+
Arguments; they must appear in the given order as there is no other
74+
way to identify one from another. An additional restriction of the
75+
standard Group implementation is that only the final argument can have
76+
variable size (differing minimum and maximum).
77+
</p>
78+
<p>
79+
Groups inherit all the properties of Options.
80+
</p>
81+
<table>
82+
<tr>
83+
<th>Property</th><th>Type</th><th>Description</th>
84+
</tr>
85+
<tr>
86+
<td>minimum</td>
87+
<td>int</td>
88+
<td>
89+
The minimum number of member options that must be present on the
90+
command line for this group to be valid. Typically this will
91+
either be 0 where the group is optional or 1 to indicate at least
92+
one of them is needed. This value does not count anonymous
93+
options.
94+
</td>
95+
</tr>
96+
<tr>
97+
<td>maximum</td>
98+
<td>int</td>
99+
<td>
100+
The maximum number of options from this Group that can appear in a
101+
command line. This would typically be used if you wanted to
102+
create an exclusive group where a maximum of 1 member is allowed
103+
to appear. This value does not count anonymous options.
104+
</td>
105+
</tr>
106+
</table>
30107
</subsection>
108+
31109
<subsection name="Argument">
110+
<source>&lt;arg1&gt; [&lt;arg2&gt; ...]</source>
111+
<p>
112+
Arguments are used to pass in values from the command line, for
113+
example to pass in a list of files to be operated on. Arguments can
114+
appear in two different situations within an option model, the most
115+
frequently used situation is where the value found should be associated
116+
with a Parent option; in this situation the value is expected to
117+
immediately follow the Parent in the command line. The second
118+
scenario where Arguments are used is when they are added to a Group
119+
directly rather than being composed with a Parent first. These
120+
'anonymous' arguments have nothing that identifies them on the
121+
command line other than the order in which they appear.
122+
</p>
123+
<p>
124+
Multiple values may be parsed by a single argument and the minimum
125+
and maximum attributes can used to control their validity,
126+
additionally a Validator may be used to identify whether individual
127+
values are valid. In some situations it can be useful to parse the
128+
supplied string into multiple values and so the initialSeparator and
129+
subsequentSeparator attributes can be used; assuming an
130+
initialSeparator of '=' and a subsequentSeparator of ',', the
131+
string '--file=a,b,c' would be split into a parent option '--file',
132+
and the values 'a', 'b' and 'c'.
133+
</p>
134+
<p>
135+
Arguments inherit all the properties of Options.
136+
</p>
137+
<table>
138+
<tr>
139+
<th>Property</th><th>Type</th><th>Description</th>
140+
</tr>
141+
<tr>
142+
<td>minimum</td>
143+
<td>int</td>
144+
<td>
145+
The minimum number of values that must be present for the
146+
Argument to be valid. The default of 0 implies that the argument
147+
is optional.
148+
</td>
149+
</tr>
150+
<tr>
151+
<td>maximum</td>
152+
<td>int</td>
153+
<td>
154+
The maximum number of values that can appear in a valid command
155+
line. A value less than minimum is not allowed.
156+
</td>
157+
</tr>
158+
<tr>
159+
<td>consumeRemaining</td>
160+
<td>String</td>
161+
<td>
162+
A string that can be used to avoid parsing of the remaining
163+
values as options. Typically '--' is used and allows file names
164+
to be used as values even though they look like options.
165+
</td>
166+
</tr>
167+
<tr>
168+
<td>initialSeparator</td>
169+
<td>char</td>
170+
<td>
171+
A character used to indicate the end of the parent option and the
172+
beginning of the values.
173+
</td>
174+
</tr>
175+
<tr>
176+
<td>subsequentSeparator</td>
177+
<td>char</td>
178+
<td>
179+
A character used to indicate the boundry between two values in a
180+
single string.
181+
</td>
182+
</tr>
183+
<tr>
184+
<td>defaultValue</td>
185+
<td>Object</td>
186+
<td>
187+
A value to be used when no other is supplied.
188+
</td>
189+
</tr>
190+
</table>
32191
</subsection>
192+
33193
<subsection name="Parent">
194+
<source>--parent &lt;arg&gt; --child1|--child2</source>
195+
<p>
196+
Parent options allow an argument to be tied to some othe option,
197+
additionally a group of child options can also be added to the parent.
198+
The argument and child options are only valid in the presence of the
199+
parent option, must appear on the command line with the child options
200+
following the argument.
201+
</p>
202+
<p>
203+
Parents are not usable in themselves but DefaultOption, Switch and
204+
Command all inherit the parent features. Parents inherit the
205+
properties of Options.
206+
</p>
207+
<table>
208+
<tr>
209+
<th>Property</th><th>Type</th><th>Description</th>
210+
</tr>
211+
<tr>
212+
<td>argument</td>
213+
<td>Argument</td>
214+
<td>
215+
The Argument to delegate value processing to. This property is
216+
optional.
217+
</td>
218+
</tr>
219+
<tr>
220+
<td>children</td>
221+
<td>Group</td>
222+
<td>
223+
The Group to delegate child processing to. This property is
224+
optional.
225+
</td>
226+
</tr>
227+
</table>
34228
</subsection>
229+
230+
231+
35232
<subsection name="DefaultOption">
233+
<source>--file (-f)</source>
234+
<p>
235+
The default option allows an option to exist with both long and short
236+
aliases. Ordinarily the short aliases would be a single character
237+
long and allow a series of options <code>-x -v -f</code> to be
238+
concatenated into a single element <code>-xvf</code> on the command
239+
line. This bursting of concatenated options can be turned off if
240+
necessary and the single character restriction can be ignored where
241+
bursting is not required.
242+
</p>
243+
<p>
244+
DefaultOptions inherit all the properties of Options and Parents.
245+
</p>
246+
<table>
247+
<tr>
248+
<th>Property</th><th>Type</th><th>Description</th>
249+
</tr>
250+
<tr>
251+
<td>shortName</td>
252+
<td>String</td>
253+
<td>
254+
The short name of the option. At least one short or long name is
255+
required.
256+
</td>
257+
</tr>
258+
<tr>
259+
<td>longName</td>
260+
<td>String</td>
261+
<td>
262+
The long name of the option. At least one short or long name is
263+
required.
264+
</td>
265+
</tr>
266+
<tr>
267+
<td>burstEnabled</td>
268+
<td>boolean</td>
269+
<td>
270+
Whether to allow this option to be concatenated with others.
271+
</td>
272+
</tr>
273+
</table>
36274
</subsection>
275+
276+
37277
<subsection name="Command">
278+
<source>update (up,upd)</source>
279+
<p>
280+
Commands are basically an option without an identifying prefix and
281+
are usually found in applications that implement a suite of tools
282+
within a single application. Any of a number of aliases can appear
283+
on the command line with idenentical meaning.
284+
</p>
285+
<p>
286+
Commands inherit all the properties of Options and Parents.
287+
</p>
38288
</subsection>
289+
39290
<subsection name="Switch">
291+
<source>+display|-display</source>
292+
<p>
293+
Switches allow the user to turn a feature on or off. This becomes
294+
useful when the value would otherwise be taken from a different
295+
source and could change, for example the default value could be
296+
configurable by the user. A default switch value can be supplied in
297+
case no other source exists and the application writer has a
298+
preference.
299+
</p>
300+
<p>
301+
Switches inherit all the properties of Options and Parents.
302+
</p>
303+
<table>
304+
<tr>
305+
<th>Property</th><th>Type</th><th>Description</th>
306+
</tr>
307+
<tr>
308+
<td>defaultSwitch</td>
309+
<td>Boolean</td>
310+
<td>
311+
The value to be used if the option has not been configured. If
312+
not set the value <code>null</code> is used.
313+
</td>
314+
</tr>
315+
</table>
40316
</subsection>
317+
41318
<subsection name="PropertyOption">
319+
<source>-Dproperty=value</source>
320+
<p>
321+
Property options allow arbitrary name value pairs to be passed in by
322+
the user. This style of option is often used to emulate the java
323+
<code>-D</code> option.
324+
</p>
325+
<p>
326+
PropertyOptions inherit the properties of Options.
327+
</p>
328+
<table>
329+
<tr>
330+
<th>Property</th><th>Type</th><th>Description</th>
331+
</tr>
332+
<tr>
333+
<td>optionString</td>
334+
<td>String</td>
335+
<td>
336+
The prefix for this option, defaults to <code>-D</code>.
337+
</td>
338+
</tr>
339+
</table>
42340
</subsection>
341+
43342
<subsection name="SourceDestArgument">
343+
344+
345+
346+
<source>&lt;src1&gt; [&lt;src2&gt; ...] &lt;dest&gt;</source>
347+
<p>
348+
Groups have the restriction that only the final argument can have
349+
variable size. Using the SourceDestArgument this rule can appear
350+
to be relaxed by shifting the variable size argument to an earlier
351+
position. A SourceDestArgument is implemented by composing two other
352+
options together. This option would typically be used when modelling
353+
commands like the unix cp command,
354+
</p>
355+
<table>
356+
<tr>
357+
<th>Property</th><th>Type</th><th>Description</th>
358+
</tr>
359+
<tr>
360+
<td>source</td>
361+
<td>Argument</td>
362+
<td>
363+
The variable size first argument.
364+
</td>
365+
</tr>
366+
<tr>
367+
<td>dest</td>
368+
<td>Argument</td>
369+
<td>
370+
The fixed size last argument.
371+
</td>
372+
</tr>
373+
</table>
44374
</subsection>
45375
</section>
46376
</body>

0 commit comments

Comments
 (0)