001/**
002 * Copyright 2003-2004 The Apache Software Foundation
003 * Copyright 2005 Stephen McConnell
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package net.dpml.cli;
018
019import java.util.ListIterator;
020
021/**
022 * An Option that can process values passed on the command line in the form
023 * "--file README".
024 *
025 * @author <a href="@PUBLISHER-URL@">@PUBLISHER-NAME@</a>
026 * @version @PROJECT-VERSION@
027 */
028public interface Argument extends Option
029{
030   /**
031    * Returns the initial separator character or
032    * '\0' if no character has been set.
033    * 
034    * @return char the initial separator character
035    */
036    char getInitialSeparator();
037    
038   /**
039    * Processes the "README" style element of the argument.
040    *
041    * Values identified should be added to the CommandLine object in
042    * association with this Argument.
043    *
044    * @see WriteableCommandLine#addValue(Option,Object)
045    *
046    * @param commandLine The CommandLine object to store results in.
047    * @param args The arguments to process.
048    * @param option The option to register value against.
049    * @throws OptionException if any problems occur.
050    */
051    void processValues( 
052      WriteableCommandLine commandLine, ListIterator args, Option option )
053      throws OptionException;
054    
055    /**
056     * Adds defaults to a CommandLine.
057     * 
058     * @param commandLine the CommandLine object to store defaults in.
059     * @param option the Option to store the defaults against.
060     */
061    void defaultValues( WriteableCommandLine commandLine, Option option );
062
063    /**
064     * Performs any necessary validation on the values added to the
065     * CommandLine.
066     *
067     * Validation will typically involve using the
068     * CommandLine.getValues(option) method to retrieve the values
069     * and then either checking each value.  Optionally the String
070     * value can be replaced by another Object such as a Number
071     * instance or a File instance.
072     *
073     * @see CommandLine#getValues(Option)
074     *
075     * @param commandLine The CommandLine object to query.
076     * @param option The option to lookup values with.
077     * @throws OptionException if any problems occur.
078     */
079    void validate( WriteableCommandLine commandLine, Option option )
080        throws OptionException;
081
082    /**
083     * Indicates whether argument values must be present for the CommandLine to
084     * be valid.
085     *
086     * @see #getMinimum()
087     * @see #getMaximum()
088     * @return true iff the CommandLine will be invalid without at least one 
089     *         value
090     */
091    boolean isRequired();
092
093    /**
094     * Retrieves the minimum number of values required for a valid Argument
095     *
096     * @return the minimum number of values
097     */
098    int getMinimum();
099
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}