1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.cli2;
18
19 import java.util.Comparator;
20 import java.util.List;
21 import java.util.ListIterator;
22 import java.util.Set;
23
24 /**
25 * The super type of all options representing a particular element of the
26 * command line interface.
27 */
28 public interface Option {
29
30 /**
31 * Processes String arguments into a CommandLine.
32 *
33 * The iterator will initially point at the first argument to be processed
34 * and at the end of the method should point to the first argument not
35 * processed. This method MUST process at least one argument from the
36 * ListIterator.
37 *
38 * @param commandLine
39 * The CommandLine object to store results in
40 * @param args
41 * The arguments to process
42 * @throws OptionException
43 * if any problems occur
44 */
45 void process(
46 final WriteableCommandLine commandLine,
47 final ListIterator args)
48 throws OptionException;
49
50 /**
51 * Adds defaults to a CommandLine.
52 *
53 * Any defaults for this option are applied as well as the defaults for
54 * any contained options
55 *
56 * @param commandLine
57 * The CommandLine object to store defaults in
58 */
59 void defaults(final WriteableCommandLine commandLine);
60
61 /**
62 * Indicates whether this Option will be able to process the particular
63 * argument.
64 *
65 * @param commandLine
66 * The CommandLine to check
67 * @param argument
68 * The argument to be tested
69 * @return true if the argument can be processed by this Option
70 */
71 boolean canProcess(final WriteableCommandLine commandLine, final String argument);
72
73 /**
74 * Indicates whether this Option will be able to process the particular
75 * argument. The ListIterator must be restored to the initial state before
76 * returning the boolean.
77 *
78 * @see #canProcess(WriteableCommandLine,String)
79 * @param commandLine
80 * the CommandLine to check
81 * @param arguments
82 * the ListIterator over String arguments
83 * @return true if the argument can be processed by this Option
84 */
85 boolean canProcess(final WriteableCommandLine commandLine, final ListIterator arguments);
86
87 /**
88 * Identifies the argument prefixes that should trigger this option. This
89 * is used to decide which of many Options should be tried when processing
90 * a given argument string.
91 *
92 * The returned Set must not be null.
93 *
94 * @return The set of triggers for this Option
95 */
96 Set getTriggers();
97
98 /**
99 * 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 }