001    /**
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  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     */
017    package org.apache.commons.cli2;
018    
019    import 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    public interface Argument extends Option {
026    
027        /**
028         * Returns the initial separator character or
029         * '\0' if no character has been set.
030         *
031         * @return char the initial separator character
032         */
033        char getInitialSeparator();
034    
035        /**
036         * Processes the "README" style element of the argument.
037         *
038         * Values identified should be added to the CommandLine object in
039         * association with this Argument.
040         *
041         * @see WriteableCommandLine#addValue(Option,Object)
042         *
043         * @param commandLine The CommandLine object to store results in.
044         * @param args The arguments to process.
045         * @param option The option to register value against.
046         * @throws OptionException if any problems occur.
047         */
048        void processValues(
049            final WriteableCommandLine commandLine,
050            final ListIterator args,
051            final Option option)
052                throws OptionException;
053    
054        /**
055         * Adds defaults to a CommandLine.
056         *
057         * @param commandLine
058         *            The CommandLine object to store defaults in.
059         * @param option
060         *            The Option to store the defaults against.
061         */
062        void defaultValues(final WriteableCommandLine commandLine, final Option option);
063    
064        /**
065         * Performs any necessary validation on the values added to the
066         * CommandLine.
067         *
068         * Validation will typically involve using the
069         * CommandLine.getValues(option) method to retrieve the values
070         * and then either checking each value.  Optionally the String
071         * value can be replaced by another Object such as a Number
072         * instance or a File instance.
073         *
074         * @see CommandLine#getValues(Option)
075         *
076         * @param commandLine The CommandLine object to query.
077         * @param option The option to lookup values with.
078         * @throws OptionException if any problems occur.
079         */
080        void validate(final WriteableCommandLine commandLine, final Option option)
081            throws OptionException;
082    
083        /**
084         * Indicates whether argument values must be present for the CommandLine to
085         * be valid.
086         *
087         * @see #getMinimum()
088         * @see #getMaximum()
089         * @return true iff the CommandLine will be invalid without at least one
090         *         value
091         */
092        boolean isRequired();
093    
094        /**
095         * Retrieves the minimum number of values required for a valid Argument
096         *
097         * @return the minimum number of values
098         */
099        int getMinimum();
100    
101        /**
102         * Retrieves the maximum number of values acceptable for a valid Argument
103         *
104         * @return the maximum number of values
105         */
106        int getMaximum();
107    }