1 //
2 // Option.h
3 //
4 // Library: Util
5 // Package: Options
6 // Module: Option
7 //
8 // Definition of the Option class.
9 //
10 // Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
11 // and Contributors.
12 //
13 // SPDX-License-Identifier: BSL-1.0
14 //
15
16
17 #ifndef Util_Option_INCLUDED
18 #define Util_Option_INCLUDED
19
20
21 #include "Poco/Util/Util.h"
22 #include "Poco/Util/OptionCallback.h"
23 #include "Poco/Util/AbstractConfiguration.h"
24
25
26 namespace Poco {
27 namespace Util {
28
29
30 class Application;
31 class Validator;
32
33
34 class Util_API Option
35 /// This class represents and stores the properties
36 /// of a command line option.
37 ///
38 /// An option has a full name, an optional short name,
39 /// a description (used for printing a usage statement),
40 /// and an optional argument name.
41 /// An option can be optional or required.
42 /// An option can be repeatable, which means that it can
43 /// be given more than once on the command line.
44 ///
45 /// An option can be part of an option group. At most one
46 /// option of each group may be specified on the command
47 /// line.
48 ///
49 /// An option can be bound to a configuration property.
50 /// In this case, a configuration property will automatically
51 /// receive the option's argument value.
52 ///
53 /// A callback method can be specified for options. This method
54 /// is called whenever an option is specified on the command line.
55 ///
56 /// Option argument values can be automatically validated using a
57 /// Validator.
58 ///
59 /// Option instances are value objects.
60 ///
61 /// Typically, after construction, an Option object is immediately
62 /// passed to an Options object.
63 ///
64 /// An Option object can be created by chaining the constructor
65 /// with any of the setter methods, as in the following example:
66 ///
67 /// Option versionOpt("include", "I", "specify an include directory")
68 /// .required(false)
69 /// .repeatable(true)
70 /// .argument("directory");
71 {
72 public:
73 Option();
74 /// Creates an empty Option.
75
76 Option(const Option& option);
77 /// Creates an option from another one.
78
79 Option(const std::string& fullName, const std::string& shortName);
80 /// Creates an option with the given properties.
81
82 Option(const std::string& fullName, const std::string& shortName, const std::string& description, bool required = false);
83 /// Creates an option with the given properties.
84
85 Option(const std::string& fullName, const std::string& shortName, const std::string& description, bool required, const std::string& argName, bool argRequired = false);
86 /// Creates an option with the given properties.
87
88 ~Option();
89 /// Destroys the Option.
90
91 Option& operator = (const Option& option);
92 /// Assignment operator.
93
94 void swap(Option& option);
95 /// Swaps the option with another one.
96
97 Option& shortName(const std::string& name);
98 /// Sets the short name of the option.
99
100 Option& fullName(const std::string& name);
101 /// Sets the full name of the option.
102
103 Option& description(const std::string& text);
104 /// Sets the description of the option.
105
106 Option& required(bool flag);
107 /// Sets whether the option is required (flag == true)
108 /// or optional (flag == false).
109
110 Option& repeatable(bool flag);
111 /// Sets whether the option can be specified more than once
112 /// (flag == true) or at most once (flag == false).
113
114 Option& argument(const std::string& name, bool required = true);
115 /// Specifies that the option takes an (optional or required)
116 /// argument.
117
118 Option& noArgument();
119 /// Specifies that the option does not take an argument (default).
120
121 Option& group(const std::string& group);
122 /// Specifies the option group the option is part of.
123
124 Option& binding(const std::string& propertyName);
125 /// Binds the option to the configuration property with the given name.
126 ///
127 /// The configuration will automatically receive the option's argument.
128
129 Option& binding(const std::string& propertyName, AbstractConfiguration* pConfig);
130 /// Binds the option to the configuration property with the given name,
131 /// using the given AbstractConfiguration.
132 ///
133 /// The configuration will automatically receive the option's argument.
134
135 Option& callback(const AbstractOptionCallback& cb);
136 /// Binds the option to the given method.
137 ///
138 /// The callback method will be called when the option
139 /// has been specified on the command line.
140 ///
141 /// Usage:
142 /// callback(OptionCallback<MyApplication>(this, &MyApplication::myCallback));
143
144 Option& validator(Validator* pValidator);
145 /// Sets the validator for the given option.
146 ///
147 /// The Option takes ownership of the Validator and
148 /// deletes it when it's no longer needed.
149
150 const std::string& shortName() const;
151 /// Returns the short name of the option.
152
153 const std::string& fullName() const;
154 /// Returns the full name of the option.
155
156 const std::string& description() const;
157 /// Returns the description of the option.
158
159 bool required() const;
160 /// Returns true if the option is required, false if not.
161
162 bool repeatable() const;
163 /// Returns true if the option can be specified more than
164 /// once, or false if at most once.
165
166 bool takesArgument() const;
167 /// Returns true if the options takes an (optional) argument.
168
169 bool argumentRequired() const;
170 /// Returns true if the argument is required.
171
172 const std::string& argumentName() const;
173 /// Returns the argument name, if specified.
174
175 const std::string& group() const;
176 /// Returns the option group the option is part of,
177 /// or an empty string, if the option is not part of
178 /// a group.
179
180 const std::string& binding() const;
181 /// Returns the property name the option is bound to,
182 /// or an empty string in case it is not bound.
183
184 AbstractOptionCallback* callback() const;
185 /// Returns a pointer to the callback method for the option,
186 /// or NULL if no callback has been specified.
187
188 Validator* validator() const;
189 /// Returns the option's Validator, if one has been specified,
190 /// or NULL otherwise.
191
192 AbstractConfiguration::Ptr config() const;
193 /// Returns the configuration, if specified, or NULL otherwise.
194
195 bool matchesShort(const std::string& option) const;
196 /// Returns true if the given option string matches the
197 /// short name.
198 ///
199 /// The first characters of the option string must match
200 /// the short name of the option (case sensitive),
201 /// or the option string must partially match the full
202 /// name (case insensitive).
203
204 bool matchesFull(const std::string& option) const;
205 /// Returns true if the given option string matches the
206 /// full name.
207 ///
208 /// The option string must match the full
209 /// name (case insensitive).
210
211 bool matchesPartial(const std::string& option) const;
212 /// Returns true if the given option string partially matches the
213 /// full name.
214 ///
215 /// The option string must partially match the full
216 /// name (case insensitive).
217
218 void process(const std::string& option, std::string& arg) const;
219 /// Verifies that the given option string matches the
220 /// requirements of the option, and extracts the option argument,
221 /// if present.
222 ///
223 /// If the option string is okay and carries an argument,
224 /// the argument is returned in arg.
225 ///
226 /// Throws a MissingArgumentException if a required argument
227 /// is missing. Throws an UnexpectedArgumentException if an
228 /// argument has been found, but none is expected.
229
230 private:
231 std::string _shortName;
232 std::string _fullName;
233 std::string _description;
234 bool _required;
235 bool _repeatable;
236 std::string _argName;
237 bool _argRequired;
238 std::string _group;
239 std::string _binding;
240 Validator* _pValidator;
241 AbstractOptionCallback* _pCallback;
242 AbstractConfiguration::Ptr _pConfig;
243 };
244
245
246 //
247 // inlines
248 //
249
250
shortName()251 inline const std::string& Option::shortName() const
252 {
253 return _shortName;
254 }
255
256
fullName()257 inline const std::string& Option::fullName() const
258 {
259 return _fullName;
260 }
261
262
description()263 inline const std::string& Option::description() const
264 {
265 return _description;
266 }
267
268
required()269 inline bool Option::required() const
270 {
271 return _required;
272 }
273
274
repeatable()275 inline bool Option::repeatable() const
276 {
277 return _repeatable;
278 }
279
280
takesArgument()281 inline bool Option::takesArgument() const
282 {
283 return !_argName.empty();
284 }
285
286
argumentRequired()287 inline bool Option::argumentRequired() const
288 {
289 return _argRequired;
290 }
291
292
argumentName()293 inline const std::string& Option::argumentName() const
294 {
295 return _argName;
296 }
297
298
group()299 inline const std::string& Option::group() const
300 {
301 return _group;
302 }
303
304
binding()305 inline const std::string& Option::binding() const
306 {
307 return _binding;
308 }
309
310
callback()311 inline AbstractOptionCallback* Option::callback() const
312 {
313 return _pCallback;
314 }
315
316
validator()317 inline Validator* Option::validator() const
318 {
319 return _pValidator;
320 }
321
322
config()323 inline AbstractConfiguration::Ptr Option::config() const
324 {
325 return _pConfig;
326 }
327
328
329 } } // namespace Poco::Util
330
331
332 #endif // Util_Option_INCLUDED
333