001 /*
002 * Copyright 2003-2005 The Apache Software Foundation
003 * Copyright 2005 Stephen McConnell
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * 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 net.dpml.cli;
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 * @author <a href="http://www.dpml.net">Digital Product Meta Library</a>
029 * @version 1.0.0
030 */
031 public interface Option
032 {
033 /**
034 * Processes String arguments into a CommandLine.
035 *
036 * The iterator will initially point at the first argument to be processed
037 * and at the end of the method should point to the first argument not
038 * processed. This method MUST process at least one argument from the
039 * ListIterator.
040 *
041 * @param commandLine the CommandLine object to store results in
042 * @param args the arguments to process
043 * @throws OptionException 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 the CommandLine object to store defaults in
057 */
058 void defaults( WriteableCommandLine commandLine );
059
060 /**
061 * Indicates whether this Option will be able to process the particular
062 * argument.
063 *
064 * @param commandLine the CommandLine object to store defaults in
065 * @param argument the argument to be tested
066 * @return true if the argument can be processed by this Option
067 */
068 boolean canProcess( WriteableCommandLine commandLine, String argument );
069
070 /**
071 * Indicates whether this Option will be able to process the particular
072 * argument. The ListIterator must be restored to the initial state before
073 * returning the boolean.
074 *
075 * @see #canProcess(WriteableCommandLine,String)
076 * @param commandLine the CommandLine object to store defaults in
077 * @param arguments the ListIterator over String arguments
078 * @return true if the argument can be processed by this Option
079 */
080 boolean canProcess( WriteableCommandLine commandLine, final ListIterator arguments );
081
082 /**
083 * Identifies the argument prefixes that should trigger this option. This
084 * is used to decide which of many Options should be tried when processing
085 * a given argument string.
086 *
087 * The returned Set must not be null.
088 *
089 * @return The set of triggers for this Option
090 */
091 Set getTriggers();
092
093 /**
094 * Identifies the argument prefixes that should be considered options. This
095 * is used to identify whether a given string looks like an option or an
096 * argument value. Typically an option would return the set [--,-] while
097 * switches might offer [-,+].
098 *
099 * The returned Set must not be null.
100 *
101 * @return The set of prefixes for this Option
102 */
103 Set getPrefixes();
104
105 /**
106 * Checks that the supplied CommandLine is valid with respect to this
107 * option.
108 *
109 * @param commandLine the CommandLine to check.
110 * @throws OptionException if the CommandLine is not valid.
111 */
112 void validate( WriteableCommandLine commandLine ) throws OptionException;
113
114 /**
115 * Builds up a list of HelpLineImpl instances to be presented by HelpFormatter.
116 *
117 * @see HelpLine
118 * @see net.dpml.cli.util.HelpFormatter
119 * @param depth the initial indent depth
120 * @param helpSettings the HelpSettings that should be applied
121 * @param comp a comparator used to sort options when applicable.
122 * @return a List of HelpLineImpl objects
123 */
124 List helpLines( int depth, Set helpSettings, Comparator comp );
125
126 /**
127 * Appends usage information to the specified StringBuffer
128 *
129 * @param buffer the buffer to append to
130 * @param helpSettings a set of display settings @see DisplaySetting
131 * @param comp a comparator used to sort the Options
132 */
133 void appendUsage( StringBuffer buffer, Set helpSettings, Comparator comp );
134
135 /**
136 * The preferred name of an option is used for generating help and usage
137 * information.
138 *
139 * @return The preferred name of the option
140 */
141 String getPreferredName();
142
143 /**
144 * Returns a description of the option. This string is used to build help
145 * messages as in the HelpFormatter.
146 *
147 * @see net.dpml.cli.util.HelpFormatter
148 * @return a description of the option.
149 */
150 String getDescription();
151
152 /**
153 * Returns the id of the option. This can be used in a loop and switch
154 * construct:
155 *
156 * <code>
157 * for(Option o : cmd.getOptions()){
158 * switch(o.getId()){
159 * case POTENTIAL_OPTION:
160 * ...
161 * }
162 * }
163 * </code>
164 *
165 * The returned value is not guarenteed to be unique.
166 *
167 * @return the id of the option.
168 */
169 int getId();
170
171 /**
172 * Recursively searches for an option with the supplied trigger.
173 *
174 * @param trigger the trigger to search for.
175 * @return the matching option or null.
176 */
177 Option findOption( String trigger );
178
179 /**
180 * Indicates whether this option is required to be present.
181 * @return true if the CommandLine will be invalid without this Option
182 */
183 boolean isRequired();
184 }