Coverage Report

Coverage Report - org.apache.commons.cli2.Option

Classes in this File

 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to You under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 package org.apache.commons.cli2;
 
 import java.util.Comparator;
 import java.util.List;
 import java.util.ListIterator;
 import java.util.Set;
 
 /**
  * The super type of all options representing a particular element of the
  * command line interface.
  */
 public interface Option {
 
     /**
      * Processes String arguments into a CommandLine.
      *
      * The iterator will initially point at the first argument to be processed
      * and at the end of the method should point to the first argument not
      * processed. This method MUST process at least one argument from the
      * ListIterator.
      *
      * @param commandLine
      *            The CommandLine object to store results in
      * @param args
      *            The arguments to process
      * @throws OptionException
      *             if any problems occur
      */
     void process(
         final WriteableCommandLine commandLine,
         final ListIterator args)
         throws OptionException;
 
     /**
      * Adds defaults to a CommandLine.
      *
      * Any defaults for this option are applied as well as the defaults for
      * any contained options
      *
      * @param commandLine
      *            The CommandLine object to store defaults in
      */
     void defaults(final WriteableCommandLine commandLine);
 
     /**
      * Indicates whether this Option will be able to process the particular
      * argument.
      *
      * @param commandLine
      *            The CommandLine to check
      * @param argument
      *            The argument to be tested
      * @return true if the argument can be processed by this Option
      */
     boolean canProcess(final WriteableCommandLine commandLine, final String argument);
 
     /**
      * Indicates whether this Option will be able to process the particular
      * argument. The ListIterator must be restored to the initial state before
      * returning the boolean.
      *
      * @see #canProcess(WriteableCommandLine,String)
      * @param commandLine
      *            the CommandLine to check
      * @param arguments
      *            the ListIterator over String arguments
      * @return true if the argument can be processed by this Option
      */
     boolean canProcess(final WriteableCommandLine commandLine, final ListIterator arguments);
 
     /**
      * Identifies the argument prefixes that should trigger this option. This
      * is used to decide which of many Options should be tried when processing
      * a given argument string.
      *
      * The returned Set must not be null.
      *
      * @return The set of triggers for this Option
      */
     Set getTriggers();
 
     /**
      * Identifies the argument prefixes that should be considered options. This
      * is used to identify whether a given string looks like an option or an
      * argument value. Typically an option would return the set [--,-] while
      * switches might offer [-,+].
      *
      * The returned Set must not be null.
      *
      * @return The set of prefixes for this Option
      */
     Set getPrefixes();
 
     /**
      * Checks that the supplied CommandLine is valid with respect to this
      * option.
      *
      * @param commandLine
      *            The CommandLine to check.
      * @throws OptionException
      *             if the CommandLine is not valid.
      */
     void validate(final WriteableCommandLine commandLine)
         throws OptionException;
 
     /**
      * Builds up a list of HelpLineImpl instances to be presented by HelpFormatter.
      *
      * @see HelpLine
      * @see org.apache.commons.cli2.util.HelpFormatter
      * @param depth
      *            the initial indent depth
      * @param helpSettings
      *            the HelpSettings that should be applied
      * @param comp
      *            a comparator used to sort options when applicable.
      * @return a List of HelpLineImpl objects
      */
     List helpLines(
         final int depth,
         final Set helpSettings,
         final Comparator comp);
 
     /**
      * Appends usage information to the specified StringBuffer
      *
      * @param buffer the buffer to append to
      * @param helpSettings a set of display settings @see DisplaySetting
      * @param comp a comparator used to sort the Options
      */
     void appendUsage(
         final StringBuffer buffer,
         final Set helpSettings,
         final Comparator comp);
 
     /**
      * The preferred name of an option is used for generating help and usage
      * information.
      *
      * @return The preferred name of the option
      */
     String getPreferredName();
 
     /**
      * Returns a description of the option. This string is used to build help
      * messages as in the HelpFormatter.
      *
      * @see org.apache.commons.cli2.util.HelpFormatter
      * @return a description of the option.
      */
     String getDescription();
 
     /**
      * Returns the id of the option.  This can be used in a loop and switch
      * construct:
      *
      * <code>
      * for(Option o : cmd.getOptions()){
      *     switch(o.getId()){
      *         case POTENTIAL_OPTION:
      *             ...
      *     }
      * }
      * </code>
      *
      * The returned value is not guarenteed to be unique.
      *
      * @return the id of the option.
      */
     int getId();
 
     /**
      * Recursively searches for an option with the supplied trigger.
      *
      * @param trigger the trigger to search for.
      * @return the matching option or null.
      */
     Option findOption(final String trigger);
 
     /**
      * Indicates whether this option is required to be present.
      * @return true iff the CommandLine will be invalid without this Option
      */
     boolean isRequired();
 
     /**
      * Returns the parent of this option. Options can be organized in a
      * hierarchical manner if they are added to groups. This method can be used
      * for obtaining the parent option of this option. The result may be
      * <b>null</b> if this option does not have a parent.
      *
      * @return the parent of this option
      */
     Option getParent();
 
     /**
      * Sets the parent of this option. This method is called when the option is
      * added to a group. Storing the parent of an option makes it possible to
      * keep track of hierarchical relations between options. For instance, if an
      * option is identified while parsing a command line, the group this option
      * belongs to can also be added to the command line.
      *
      * @param parent the parent option
      */
     void setParent(Option parent);
 }

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		}