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 */
017package org.apache.commons.cli2;
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 */
025public 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}