xdocs/manual/options.xml - commons-cli - Git at Google

 <?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

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
 -->
 <document>

   <properties>
     <author email="dev@commons.apache.org">commons-dev</author>
     <title>CLI2 - Options</title>
   </properties>

   <body>
     <section name="Options">
       <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>&lt;arg1&gt; [&lt;arg2&gt; ...]</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 &lt;arg&gt; --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>&lt;src1&gt; [&lt;src2&gt; ...] &lt;dest&gt;</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>
 </document>
	<?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

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<document>

	<properties>
	<author email="dev@commons.apache.org">commons-dev</author>
	<title>CLI2 - Options</title>
	</properties>

	<body>
	<section name="Options">
	<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>
	</document>