roxspring 2004/10/05 16:10:31
Modified: cli/xdocs/manual options.xml
Log:
Documented the various options and their properties
Revision Changes Path
1.2 +330 -0 jakarta-commons/cli/xdocs/manual/options.xml
Index: options.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/cli/xdocs/manual/options.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- options.xml 2 Sep 2004 13:58:02 -0000 1.1
+++ options.xml 5 Oct 2004 23:10:31 -0000 1.2
@@ -25,22 +25,352 @@
<section name="Options">
<img src="../images/options.jpg"/>
<subsection name="Option">
+ <p>
+ In CLI2 every element of the command line interface is modelled as an
+ Option instance, and has the following readonly properties that are
+ inherited by all other Option implementations:
+ </p>
+ <table>
+ <tr>
+ <th>Property</th><th>Type</th><th>Description</th>
+ </tr>
+ <tr>
+ <td>id</td>
+ <td>int</td>
+ <td>
+ Some people find it useful to give each option a unique identifer
+ so that they can use the options within a java <code>switch</code>
+ statement. This value is entirely optional and it is up to the
+ user to ensure any uniqueness.
+ </td>
+ </tr>
+ <tr>
+ <td>preferredName</td>
+ <td>String</td>
+ <td>
+ Every option has a preferred name that can be used for the minimal
+ <code>toString()</code> implementation. Options can usually have
+ many additional names too.
+ </td>
+ </tr>
+ <tr>
+ <td>required</td>
+ <td>boolean</td>
+ <td>
+ True here indicates that the command line is invalid if this
+ option doesn't appear on it.
+ </td>
+ </tr>
+ </table>
</subsection>
+
<subsection name="Group">
+ <source>-a|-b|-c|-d|-e</source>
+ <p>
+ Groups are possible the least intuitive form of Option since they
+ actually represent a collection of other options. Most member Options
+ can appear on a command line in any order with the exception of
+ Arguments; they must appear in the given order as there is no other
+ way to identify one from another. An additional restriction of the
+ standard Group implementation is that only the final argument can have
+ variable size (differing minimum and maximum).
+ </p>
+ <p>
+ Groups inherit all the properties of Options.
+ </p>
+ <table>
+ <tr>
+ <th>Property</th><th>Type</th><th>Description</th>
+ </tr>
+ <tr>
+ <td>minimum</td>
+ <td>int</td>
+ <td>
+ The minimum number of member options that must be present on the
+ command line for this group to be valid. Typically this will
+ either be 0 where the group is optional or 1 to indicate at least
+ one of them is needed. This value does not count anonymous
+ options.
+ </td>
+ </tr>
+ <tr>
+ <td>maximum</td>
+ <td>int</td>
+ <td>
+ The maximum number of options from this Group that can appear in a
+ command line. This would typically be used if you wanted to
+ create an exclusive group where a maximum of 1 member is allowed
+ to appear. This value does not count anonymous options.
+ </td>
+ </tr>
+ </table>
</subsection>
+
<subsection name="Argument">
+ <source><arg1> [<arg2> ...]</source>
+ <p>
+ Arguments are used to pass in values from the command line, for
+ example to pass in a list of files to be operated on. Arguments can
+ appear in two different situations within an option model, the most
+ frequently used situation is where the value found should be associated
+ with a Parent option; in this situation the value is expected to
+ immediately follow the Parent in the command line. The second
+ scenario where Arguments are used is when they are added to a Group
+ directly rather than being composed with a Parent first. These
+ 'anonymous' arguments have nothing that identifies them on the
+ command line other than the order in which they appear.
+ </p>
+ <p>
+ Multiple values may be parsed by a single argument and the minimum
+ and maximum attributes can used to control their validity,
+ additionally a Validator may be used to identify whether individual
+ values are valid. In some situations it can be useful to parse the
+ supplied string into multiple values and so the initialSeparator and
+ subsequentSeparator attributes can be used; assuming an
+ initialSeparator of '=' and a subsequentSeparator of ',', the
+ string '--file=a,b,c' would be split into a parent option '--file',
+ and the values 'a', 'b' and 'c'.
+ </p>
+ <p>
+ Arguments inherit all the properties of Options.
+ </p>
+ <table>
+ <tr>
+ <th>Property</th><th>Type</th><th>Description</th>
+ </tr>
+ <tr>
+ <td>minimum</td>
+ <td>int</td>
+ <td>
+ The minimum number of values that must be present for the
+ Argument to be valid. The default of 0 implies that the argument
+ is optional.
+ </td>
+ </tr>
+ <tr>
+ <td>maximum</td>
+ <td>int</td>
+ <td>
+ The maximum number of values that can appear in a valid command
+ line. A value less than minimum is not allowed.
+ </td>
+ </tr>
+ <tr>
+ <td>consumeRemaining</td>
+ <td>String</td>
+ <td>
+ A string that can be used to avoid parsing of the remaining
+ values as options. Typically '--' is used and allows file names
+ to be used as values even though they look like options.
+ </td>
+ </tr>
+ <tr>
+ <td>initialSeparator</td>
+ <td>char</td>
+ <td>
+ A character used to indicate the end of the parent option and the
+ beginning of the values.
+ </td>
+ </tr>
+ <tr>
+ <td>subsequentSeparator</td>
+ <td>char</td>
+ <td>
+ A character used to indicate the boundry between two values in a
+ single string.
+ </td>
+ </tr>
+ <tr>
+ <td>defaultValue</td>
+ <td>Object</td>
+ <td>
+ A value to be used when no other is supplied.
+ </td>
+ </tr>
+ </table>
</subsection>
+
<subsection name="Parent">
+ <source>--parent <arg> --child1|--child2</source>
+ <p>
+ Parent options allow an argument to be tied to some othe option,
+ additionally a group of child options can also be added to the parent.
+ The argument and child options are only valid in the presence of the
+ parent option, must appear on the command line with the child options
+ following the argument.
+ </p>
+ <p>
+ Parents are not usable in themselves but DefaultOption, Switch and
+ Command all inherit the parent features. Parents inherit the
+ properties of Options.
+ </p>
+ <table>
+ <tr>
+ <th>Property</th><th>Type</th><th>Description</th>
+ </tr>
+ <tr>
+ <td>argument</td>
+ <td>Argument</td>
+ <td>
+ The Argument to delegate value processing to. This property is
+ optional.
+ </td>
+ </tr>
+ <tr>
+ <td>children</td>
+ <td>Group</td>
+ <td>
+ The Group to delegate child processing to. This property is
+ optional.
+ </td>
+ </tr>
+ </table>
</subsection>
+
+
+
<subsection name="DefaultOption">
+ <source>--file (-f)</source>
+ <p>
+ The default option allows an option to exist with both long and short
+ aliases. Ordinarily the short aliases would be a single character
+ long and allow a series of options <code>-x -v -f</code> to be
+ concatenated into a single element <code>-xvf</code> on the command
+ line. This bursting of concatenated options can be turned off if
+ necessary and the single character restriction can be ignored where
+ bursting is not required.
+ </p>
+ <p>
+ DefaultOptions inherit all the properties of Options and Parents.
+ </p>
+ <table>
+ <tr>
+ <th>Property</th><th>Type</th><th>Description</th>
+ </tr>
+ <tr>
+ <td>shortName</td>
+ <td>String</td>
+ <td>
+ The short name of the option. At least one short or long name is
+ required.
+ </td>
+ </tr>
+ <tr>
+ <td>longName</td>
+ <td>String</td>
+ <td>
+ The long name of the option. At least one short or long name is
+ required.
+ </td>
+ </tr>
+ <tr>
+ <td>burstEnabled</td>
+ <td>boolean</td>
+ <td>
+ Whether to allow this option to be concatenated with others.
+ </td>
+ </tr>
+ </table>
</subsection>
+
+
<subsection name="Command">
+ <source>update (up,upd)</source>
+ <p>
+ Commands are basically an option without an identifying prefix and
+ are usually found in applications that implement a suite of tools
+ within a single application. Any of a number of aliases can appear
+ on the command line with idenentical meaning.
+ </p>
+ <p>
+ Commands inherit all the properties of Options and Parents.
+ </p>
</subsection>
+
<subsection name="Switch">
+ <source>+display|-display</source>
+ <p>
+ Switches allow the user to turn a feature on or off. This becomes
+ useful when the value would otherwise be taken from a different
+ source and could change, for example the default value could be
+ configurable by the user. A default switch value can be supplied in
+ case no other source exists and the application writer has a
+ preference.
+ </p>
+ <p>
+ Switches inherit all the properties of Options and Parents.
+ </p>
+ <table>
+ <tr>
+ <th>Property</th><th>Type</th><th>Description</th>
+ </tr>
+ <tr>
+ <td>defaultSwitch</td>
+ <td>Boolean</td>
+ <td>
+ The value to be used if the option has not been configured. If
+ not set the value <code>null</code> is used.
+ </td>
+ </tr>
+ </table>
</subsection>
+
<subsection name="PropertyOption">
+ <source>-Dproperty=value</source>
+ <p>
+ Property options allow arbitrary name value pairs to be passed in by
+ the user. This style of option is often used to emulate the java
+ <code>-D</code> option.
+ </p>
+ <p>
+ PropertyOptions inherit the properties of Options.
+ </p>
+ <table>
+ <tr>
+ <th>Property</th><th>Type</th><th>Description</th>
+ </tr>
+ <tr>
+ <td>optionString</td>
+ <td>String</td>
+ <td>
+ The prefix for this option, defaults to <code>-D</code>.
+ </td>
+ </tr>
+ </table>
</subsection>
+
<subsection name="SourceDestArgument">
+
+
+
+ <source><src1> [<src2> ...] <dest></source>
+ <p>
+ Groups have the restriction that only the final argument can have
+ variable size. Using the SourceDestArgument this rule can appear
+ to be relaxed by shifting the variable size argument to an earlier
+ position. A SourceDestArgument is implemented by composing two other
+ options together. This option would typically be used when modelling
+ commands like the unix cp command,
+ </p>
+ <table>
+ <tr>
+ <th>Property</th><th>Type</th><th>Description</th>
+ </tr>
+ <tr>
+ <td>source</td>
+ <td>Argument</td>
+ <td>
+ The variable size first argument.
+ </td>
+ </tr>
+ <tr>
+ <td>dest</td>
+ <td>Argument</td>
+ <td>
+ The fixed size last argument.
+ </td>
+ </tr>
+ </table>
</subsection>
</section>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
