commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From roxspr...@apache.org
Subject cvs commit: jakarta-commons/cli/xdocs/manual options.xml
Date Tue, 05 Oct 2004 23:10:31 GMT
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>&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>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message