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.Comparator;
020import java.util.List;
021import java.util.ListIterator;
022import java.util.Set;
023
024/**
025 * The super type of all options representing a particular element of the
026 * command line interface.
027 */
028public interface Option {
029
030    /**
031     * Processes String arguments into a CommandLine.
032     *
033     * The iterator will initially point at the first argument to be processed
034     * and at the end of the method should point to the first argument not
035     * processed. This method MUST process at least one argument from the
036     * ListIterator.
037     *
038     * @param commandLine
039     *            The CommandLine object to store results in
040     * @param args
041     *            The arguments to process
042     * @throws OptionException
043     *             if any problems occur
044     */
045    void process(
046        final WriteableCommandLine commandLine,
047        final ListIterator args)
048        throws OptionException;
049
050    /**
051     * Adds defaults to a CommandLine.
052     *
053     * Any defaults for this option are applied as well as the defaults for
054     * any contained options
055     *
056     * @param commandLine
057     *            The CommandLine object to store defaults in
058     */
059    void defaults(final WriteableCommandLine commandLine);
060
061    /**
062     * Indicates whether this Option will be able to process the particular
063     * argument.
064     *
065     * @param commandLine
066     *            The CommandLine to check
067     * @param argument
068     *            The argument to be tested
069     * @return true if the argument can be processed by this Option
070     */
071    boolean canProcess(final WriteableCommandLine commandLine, final String argument);
072
073    /**
074     * Indicates whether this Option will be able to process the particular
075     * argument. The ListIterator must be restored to the initial state before
076     * returning the boolean.
077     *
078     * @see #canProcess(WriteableCommandLine,String)
079     * @param commandLine
080     *            the CommandLine to check
081     * @param arguments
082     *            the ListIterator over String arguments
083     * @return true if the argument can be processed by this Option
084     */
085    boolean canProcess(final WriteableCommandLine commandLine, final ListIterator arguments);
086
087    /**
088     * Identifies the argument prefixes that should trigger this option. This
089     * is used to decide which of many Options should be tried when processing
090     * a given argument string.
091     *
092     * The returned Set must not be null.
093     *
094     * @return The set of triggers for this Option
095     */
096    Set getTriggers();
097
098    /**
099     * Identifies the argument prefixes that should be considered options. This
100     * is used to identify whether a given string looks like an option or an
101     * argument value. Typically an option would return the set [--,-] while
102     * switches might offer [-,+].
103     *
104     * The returned Set must not be null.
105     *
106     * @return The set of prefixes for this Option
107     */
108    Set getPrefixes();
109
110    /**
111     * Checks that the supplied CommandLine is valid with respect to this
112     * option.
113     *
114     * @param commandLine
115     *            The CommandLine to check.
116     * @throws OptionException
117     *             if the CommandLine is not valid.
118     */
119    void validate(final WriteableCommandLine commandLine)
120        throws OptionException;
121
122    /**
123     * Builds up a list of HelpLineImpl instances to be presented by HelpFormatter.
124     *
125     * @see HelpLine
126     * @see org.apache.commons.cli2.util.HelpFormatter
127     * @param depth
128     *            the initial indent depth
129     * @param helpSettings
130     *            the HelpSettings that should be applied
131     * @param comp
132     *            a comparator used to sort options when applicable.
133     * @return a List of HelpLineImpl objects
134     */
135    List helpLines(
136        final int depth,
137        final Set helpSettings,
138        final Comparator comp);
139
140    /**
141     * Appends usage information to the specified StringBuffer
142     *
143     * @param buffer the buffer to append to
144     * @param helpSettings a set of display settings @see DisplaySetting
145     * @param comp a comparator used to sort the Options
146     */
147    void appendUsage(
148        final StringBuffer buffer,
149        final Set helpSettings,
150        final Comparator comp);
151
152    /**
153     * The preferred name of an option is used for generating help and usage
154     * information.
155     *
156     * @return The preferred name of the option
157     */
158    String getPreferredName();
159
160    /**
161     * Returns a description of the option. This string is used to build help
162     * messages as in the HelpFormatter.
163     *
164     * @see org.apache.commons.cli2.util.HelpFormatter
165     * @return a description of the option.
166     */
167    String getDescription();
168
169    /**
170     * Returns the id of the option.  This can be used in a loop and switch
171     * construct:
172     *
173     * <code>
174     * for(Option o : cmd.getOptions()){
175     *     switch(o.getId()){
176     *         case POTENTIAL_OPTION:
177     *             ...
178     *     }
179     * }
180     * </code>
181     *
182     * The returned value is not guarenteed to be unique.
183     *
184     * @return the id of the option.
185     */
186    int getId();
187
188    /**
189     * Recursively searches for an option with the supplied trigger.
190     *
191     * @param trigger the trigger to search for.
192     * @return the matching option or null.
193     */
194    Option findOption(final String trigger);
195
196    /**
197     * Indicates whether this option is required to be present.
198     * @return true iff the CommandLine will be invalid without this Option
199     */
200    boolean isRequired();
201
202    /**
203     * Returns the parent of this option. Options can be organized in a
204     * hierarchical manner if they are added to groups. This method can be used
205     * for obtaining the parent option of this option. The result may be
206     * <b>null</b> if this option does not have a parent.
207     *
208     * @return the parent of this option
209     */
210    Option getParent();
211
212    /**
213     * Sets the parent of this option. This method is called when the option is
214     * added to a group. Storing the parent of an option makes it possible to
215     * keep track of hierarchical relations between options. For instance, if an
216     * option is identified while parsing a command line, the group this option
217     * belongs to can also be added to the command line.
218     *
219     * @param parent the parent option
220     */
221    void setParent(Option parent);
222}