Source for net.dpml.cli.Argument

   1: /**
   2:  * Copyright 2003-2004 The Apache Software Foundation
   3:  * Copyright 2005 Stephen McConnell
   4:  *
   5:  * Licensed under the Apache License, Version 2.0 (the "License");
   6:  * you may not use this file except in compliance with the License.
   7:  * You may obtain a copy of the License at
   8:  *
   9:  *     http://www.apache.org/licenses/LICENSE-2.0
  10:  *
  11:  * Unless required by applicable law or agreed to in writing, software
  12:  * distributed under the License is distributed on an "AS IS" BASIS,
  13:  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14:  * See the License for the specific language governing permissions and
  15:  * limitations under the License.
  16:  */
  17: package net.dpml.cli;
  18: 
  19: import java.util.ListIterator;
  20: 
  21: /**
  22:  * An Option that can process values passed on the command line in the form
  23:  * "--file README".
  24:  *
  25:  * @author <a href="@PUBLISHER-URL@">@PUBLISHER-NAME@</a>
  26:  * @version @PROJECT-VERSION@
  27:  */
  28: public interface Argument extends Option
  29: {
  30:    /**
  31:     * Returns the initial separator character or
  32:     * '\0' if no character has been set.
  33:     * 
  34:     * @return char the initial separator character
  35:     */
  36:     char getInitialSeparator();
  37:     
  38:    /**
  39:     * Processes the "README" style element of the argument.
  40:     *
  41:     * Values identified should be added to the CommandLine object in
  42:     * association with this Argument.
  43:     *
  44:     * @see WriteableCommandLine#addValue(Option,Object)
  45:     *
  46:     * @param commandLine The CommandLine object to store results in.
  47:     * @param args The arguments to process.
  48:     * @param option The option to register value against.
  49:     * @throws OptionException if any problems occur.
  50:     */
  51:     void processValues( 
  52:       WriteableCommandLine commandLine, ListIterator args, Option option )
  53:       throws OptionException;
  54:     
  55:     /**
  56:      * Adds defaults to a CommandLine.
  57:      * 
  58:      * @param commandLine the CommandLine object to store defaults in.
  59:      * @param option the Option to store the defaults against.
  60:      */
  61:     void defaultValues( WriteableCommandLine commandLine, Option option );
  62: 
  63:     /**
  64:      * Performs any necessary validation on the values added to the
  65:      * CommandLine.
  66:      *
  67:      * Validation will typically involve using the
  68:      * CommandLine.getValues(option) method to retrieve the values
  69:      * and then either checking each value.  Optionally the String
  70:      * value can be replaced by another Object such as a Number
  71:      * instance or a File instance.
  72:      *
  73:      * @see CommandLine#getValues(Option)
  74:      *
  75:      * @param commandLine The CommandLine object to query.
  76:      * @param option The option to lookup values with.
  77:      * @throws OptionException if any problems occur.
  78:      */
  79:     void validate( WriteableCommandLine commandLine, Option option )
  80:         throws OptionException;
  81: 
  82:     /**
  83:      * Indicates whether argument values must be present for the CommandLine to
  84:      * be valid.
  85:      *
  86:      * @see #getMinimum()
  87:      * @see #getMaximum()
  88:      * @return true iff the CommandLine will be invalid without at least one 
  89:      *         value
  90:      */
  91:     boolean isRequired();
  92: 
  93:     /**
  94:      * Retrieves the minimum number of values required for a valid Argument
  95:      *
  96:      * @return the minimum number of values
  97:      */
  98:     int getMinimum();
  99: 
 100:     /**
 101:      * Retrieves the maximum number of values acceptable for a valid Argument
 102:      *
 103:      * @return the maximum number of values
 104:      */
 105:     int getMaximum();
 106: }