1 /*
2 OptionWithArgument.java
3 Creation date : 2/06/2010
4 Copyright © Benjamin Croizet (graffity2199@yahoo.fr)
5
6 This program is free software; you can redistribute it and/or
7 modify it under the terms of the GNU General Public License
8 or GNU Lesser General Public License as published by the
9 Free Software Foundation; either version 3 of the License,
10 or (at your option) any later version.
11
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
16
17 You should have received copies of the GNU General Public License
18 and GNU Lesser General Public License along with this program;
19 if not, write to the Free Software Foundation, Inc.,
20 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
21 http://www.fsf.org/licensing/licenses/gpl.html
22 http://www.gnu.org/licenses/lgpl.html
23 */
24
25 package net.sourceforge.plantumldependency.commoncli.option;
26
27 import net.sourceforge.plantumldependency.commoncli.command.CommandLine;
28 import net.sourceforge.plantumldependency.commoncli.exception.CommandLineException;
29 import net.sourceforge.plantumldependency.commoncli.option.argument.OptionArgument;
30
31 /**
32 * The interface which describes a command line option with an argument.
33 *
34 * @param <A>
35 * the argument type to parse.
36 * @author Benjamin Croizet (<a href="mailto:graffity2199@yahoo.fr>graffity2199@yahoo.fr</a>)
37 * @since 1.3.0
38 * @version 1.4.0
39 */
40 public interface OptionWithArgument < A > extends Option {
41
42 /**
43 * Parses the input {@link CommandLine} and try to find the argument which has been set. If the
44 * argument isn't specified or if the option hasn't been specified, it return the default
45 * argument, returned by the {@link #getDefaultArgumentIfOptionSpecified(CommandLine)} or
46 * {@link #getDefaultArgumentIfOptionNotSpecified(CommandLine)} methods.
47 *
48 * @param commandLine
49 * the {@link CommandLine} to parse, mustn't be <code>null</code>.
50 * @return the parsed option argument or the default one if not found.
51 * @throws CommandLineException
52 * if any error occurs when reading or parsing the command line. It can also be
53 * thrown if the option or the argument are not found but mandatory.
54 * @since 1.3.0
55 */
56 A findAndParseArgumentOrGetDefaultArgument(CommandLine commandLine) throws CommandLineException;
57
58 /**
59 * Parses the input {@link CommandLine} and try to find the argument which has been set. If the
60 * argument isn't specified or if the option hasn't been specified, it return the default
61 * argument as a {@link String}, returned by the
62 * {@link #getDefaultArgumentAsStringIfOptionSpecified(CommandLine)} or
63 * {@link #getDefaultArgumentAsStringIfOptionNotSpecified(CommandLine)} methods.
64 *
65 * @param commandLine
66 * the {@link CommandLine} to parse, mustn't be <code>null</code>.
67 * @return the parsed option argument or the default one as a {@link String} if not found.
68 * @throws CommandLineException
69 * if any error occurs when reading or parsing the command line. It can also be
70 * thrown if the option or the argument are not found but mandatory.
71 * @since 1.4.0
72 */
73 String findAndParseArgumentAsStringOrGetDefaultArgument(CommandLine commandLine) throws CommandLineException;
74
75 /**
76 * Gets the default argument as a {@link String} (like in the command line) associated to the
77 * option if the option has not been specified. <i>Note : this method is usually used when both
78 * the option and the argument are not mandatory and not specified.</i>
79 *
80 * @param commandLine
81 * the {@link CommandLine} if needed, may be <code>null</code>. This parameter is
82 * mainly used when the default option argument depends on other command line options
83 * / arguments.
84 * @return the default argument as a {@link String} associated to the option.
85 * @throws CommandLineException
86 * if any error occurs when reading and parsing the command line (if needed).
87 * @see #getDefaultArgumentIfOptionSpecified(CommandLine)
88 * @since 1.3.0
89 */
90 String getDefaultArgumentAsStringIfOptionNotSpecified(CommandLine commandLine) throws CommandLineException;
91
92 /**
93 * Gets the default argument as a {@link String} (like in the command line) associated to the
94 * option if the option has been specified. <i>Note : this method is usually used when the
95 * argument is not mandatory and not specified.</i>
96 *
97 * @param commandLine
98 * the {@link CommandLine} if needed, may be <code>null</code>. This parameter is
99 * mainly used when the default option argument depends on other command line options
100 * / arguments.
101 * @return the default argument as a {@link String} associated to the option.
102 * @throws CommandLineException
103 * if any error occurs when reading and parsing the command line (if needed).
104 * @see #getDefaultArgumentIfOptionSpecified(CommandLine)
105 * @since 1.3.0
106 */
107 String getDefaultArgumentAsStringIfOptionSpecified(CommandLine commandLine) throws CommandLineException;
108
109 /**
110 * Gets the default argument instance associated to the option if the option has not been
111 * specified. Most of the time, this method return an instance of the argument which is returned
112 * by the {@link #getDefaultArgumentAsStringIfOptionSpecified(CommandLine)} method. <i>Note :
113 * this method is usually used when both the option and the argument are not mandatory and not
114 * specified.</i>
115 *
116 * @param commandLine
117 * the {@link CommandLine} if needed, may be <code>null</code>. This parameter is
118 * mainly used when the default option argument depends on other command line options
119 * / arguments.
120 * @return the default argument instance associated to the option.
121 * @throws CommandLineException
122 * if any error occurs when reading and parsing the command line (if needed).
123 * @see #getDefaultArgumentAsStringIfOptionSpecified(CommandLine)
124 * @since 1.3.0
125 */
126 A getDefaultArgumentIfOptionNotSpecified(CommandLine commandLine) throws CommandLineException;
127
128 /**
129 * Gets the default argument instance associated to the option if the option has been specified.
130 * Most of the time, this method return an instance of the argument which is returned by the
131 * {@link #getDefaultArgumentAsStringIfOptionSpecified(CommandLine)} method. <i>Note : this
132 * method is usually used when the argument is not mandatory and not specified.</i>
133 *
134 * @param commandLine
135 * the {@link CommandLine} if needed, may be <code>null</code>. This parameter is
136 * mainly used when the default option argument depends on other command line options
137 * / arguments.
138 * @return the default argument instance associated to the option.
139 * @throws CommandLineException
140 * if any error occurs when reading and parsing the command line (if needed).
141 * @see #getDefaultArgumentAsStringIfOptionSpecified(CommandLine)
142 * @since 1.3.0
143 */
144 A getDefaultArgumentIfOptionSpecified(CommandLine commandLine) throws CommandLineException;
145
146 /**
147 * Gets the option argument.
148 *
149 * @return the {@link OptionArgument} of the option.
150 * @since 1.3.0
151 */
152 OptionArgument < A > getOptionArgument();
153
154 /**
155 * Gets the option - argument separator. Most of the time, it is a single space " " but it may
156 * be "=" or "-".
157 *
158 * @return the option - argument separator, as a {@link String}.
159 * @since 1.3.0
160 */
161 String getValueSeparator();
162 }