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.Comparator;
020    import java.util.List;
021    import java.util.ListIterator;
022    import java.util.Set;
023    
024    /**
025     * The super type of all options representing a particular element of the
026     * command line interface.
027     */
028    public 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    }