Main MRPT website > C++ reference for MRPT 1.4.0
Arg.h
Go to the documentation of this file.
1/* +---------------------------------------------------------------------------+
2 | Mobile Robot Programming Toolkit (MRPT) |
3 | http://www.mrpt.org/ |
4 | |
5 | Copyright (c) 2005-2016, Individual contributors, see AUTHORS file |
6 | See: http://www.mrpt.org/Authors - All rights reserved. |
7 | Released under BSD License. See details in http://www.mrpt.org/License |
8 +---------------------------------------------------------------------------+ */
9
10/******************************************************************************
11 *
12 * file: Arg.h
13 *
14 * Copyright (c) 2003, Michael E. Smoot .
15 * Copyright (c) 2004, Michael E. Smoot, Daniel Aarno .
16 * All rights reverved.
17 *
18 * See the file COPYING in the top directory of this distribution for
19 * more information.
20 *
21 * THE SOFTWARE IS PROVIDED _AS IS_, WITHOUT WARRANTY OF ANY KIND, EXPRESS
22 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
24 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
26 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
27 * DEALINGS IN THE SOFTWARE.
28 *
29 *****************************************************************************/
30
31
32#ifndef TCLAP_ARGUMENT_H
33#define TCLAP_ARGUMENT_H
34
35#include <string>
36#include <vector>
37#include <list>
38#include <iostream>
39
43
44namespace TCLAP {
45
46/**
47 * A virtual base class that defines the essential data for all arguments.
48 * This class, or one of its existing children, must be subclassed to do
49 * anything.
50 */
51class Arg
52{
53 private:
54
55 /**
56 * Indicates whether the rest of the arguments should be ignored.
57 */
58 static bool& ignoreRestRef() { static bool ign = false; return ign; }
59
60 /**
61 * The delimiter that separates an argument flag/name from the
62 * value.
63 */
64 static char& delimiterRef() { static char delim = ' '; return delim; }
65
66 protected:
67
68 /**
69 * The single char flag used to identify the argument.
70 * This value (preceded by a dash {-}), can be used to identify
71 * an argument on the command line. The _flag can be blank,
72 * in fact this is how unlabeled args work. Unlabeled args must
73 * override appropriate functions to get correct handling. Note
74 * that the _flag does NOT include the dash as part of the flag.
75 */
76 std::string _flag;
77
78 /**
79 * A single work namd indentifying the argument.
80 * This value (preceded by two dashed {--}) can also be used
81 * to identify an argument on the command line. Note that the
82 * _name does NOT include the two dashes as part of the _name. The
83 * _name cannot be blank.
84 */
85 std::string _name;
86
87 /**
88 * Description of the argument.
89 */
90 std::string _description;
91
92 /**
93 * Indicating whether the argument is required.
94 */
96
97 /**
98 * Label to be used in usage description. Normally set to
99 * "required", but can be changed when necessary.
100 */
101 std::string _requireLabel;
102
103 /**
104 * Indicates whether a value is required for the argument.
105 * Note that the value may be required but the argument/value
106 * combination may not be, as specified by _required.
107 */
109
110 /**
111 * Indicates whether the argument has been set.
112 * Indicates that a value on the command line has matched the
113 * name/flag of this argument and the values have been set accordingly.
114 */
116
117 /**
118 * A pointer to a vistitor object.
119 * The visitor allows special handling to occur as soon as the
120 * argument is matched. This defaults to NULL and should not
121 * be used unless absolutely necessary.
122 */
124
125 /**
126 * Whether this argument can be ignored, if desired.
127 */
129
130 /**
131 * Indicates that the arg was set as part of an XOR and not on the
132 * command line.
133 */
135
137
138 /**
139 * Performs the special handling described by the Vistitor.
140 */
141 void _checkWithVisitor() const;
142
143 /**
144 * Primary constructor. YOU (yes you) should NEVER construct an Arg
145 * directly, this is a base class that is extended by various children
146 * that are meant to be used. Use SwitchArg, ValueArg, MultiArg,
147 * UnlabeledValueArg, or UnlabeledMultiArg instead.
148 *
149 * \param flag - The flag identifying the argument.
150 * \param name - The name identifying the argument.
151 * \param desc - The description of the argument, used in the usage.
152 * \param req - Whether the argument is required.
153 * \param valreq - Whether the a value is required for the argument.
154 * \param v - The visitor checked by the argument. Defaults to NULL.
155 */
156 Arg( const std::string& flag,
157 const std::string& name,
158 const std::string& desc,
159 bool req,
160 bool valreq,
161 Visitor* v = NULL );
162
163 public:
164 /**
165 * Destructor.
166 */
167 virtual ~Arg();
168
169 /**
170 * Adds this to the specified list of Args.
171 * \param argList - The list to add this to.
172 */
173 virtual void addToList( std::list<Arg*>& argList ) const;
174
175 /**
176 * Begin ignoring arguments since the "--" argument was specified.
177 */
178 static void beginIgnoring() { ignoreRestRef() = true; }
179
180 /**
181 * Whether to ignore the rest.
182 */
183 static bool ignoreRest() { return ignoreRestRef(); }
184
185 /**
186 * The delimiter that separates an argument flag/name from the
187 * value.
188 */
189 static char delimiter() { return delimiterRef(); }
190
191 /**
192 * The char used as a place holder when SwitchArgs are combined.
193 * Currently set to '*', which shouldn't cause many problems since
194 * *'s are expanded by most shells on the command line.
195 */
196 static char blankChar() { return '*'; }
197
198 /**
199 * The char that indicates the beginning of a flag. Currently '-'.
200 */
201 static char flagStartChar() { return '-'; }
202
203 /**
204 * The sting that indicates the beginning of a flag. Currently "-".
205 * Should be identical to flagStartChar.
206 */
207 static const std::string flagStartString() { return "-"; }
208
209 /**
210 * The sting that indicates the beginning of a name. Currently "--".
211 * Should be flagStartChar twice.
212 */
213 static const std::string nameStartString() { return "--"; }
214
215 /**
216 * The name used to identify the ignore rest argument.
217 */
218 static const std::string ignoreNameString() { return "ignore_rest"; }
219
220 /**
221 * Sets the delimiter for all arguments.
222 * \param c - The character that delimits flags/names from values.
223 */
224 static void setDelimiter( char c ) { delimiterRef() = c; }
225
226 /**
227 * Pure virtual method meant to handle the parsing and value assignment
228 * of the string on the command line.
229 * \param i - Pointer the the current argument in the list.
230 * \param args - Mutable list of strings. What is
231 * passed in from main.
232 */
233 virtual bool processArg(int *i, std::vector<std::string>& args) = 0;
234
235 /**
236 * Operator ==.
237 * Equality operator. Must be virtual to handle unlabeled args.
238 * \param a - The Arg to be compared to this.
239 */
240 virtual bool operator==(const Arg& a) const;
241
242 /**
243 * Returns the argument flag.
244 */
245 const std::string& getFlag() const;
246
247 /**
248 * Returns the argument name.
249 */
250 const std::string& getName() const;
251
252 /**
253 * Returns the argument description.
254 */
255 std::string getDescription() const;
256
257 /**
258 * Indicates whether the argument is required.
259 */
260 virtual bool isRequired() const;
261
262 /**
263 * Sets _required to true. This is used by the XorHandler.
264 * You really have no reason to ever use it.
265 */
266 void forceRequired();
267
268 /**
269 * Sets the _alreadySet value to true. This is used by the XorHandler.
270 * You really have no reason to ever use it.
271 */
272 void xorSet();
273
274 /**
275 * Indicates whether a value must be specified for argument.
276 */
277 bool isValueRequired() const;
278
279 /**
280 * Indicates whether the argument has already been set. Only true
281 * if the arg has been matched on the command line.
282 */
283 bool isSet() const;
284
285 /**
286 * Indicates whether the argument can be ignored, if desired.
287 */
288 bool isIgnoreable() const;
289
290 /**
291 * A method that tests whether a string matches this argument.
292 * This is generally called by the processArg() method. This
293 * method could be re-implemented by a child to change how
294 * arguments are specified on the command line.
295 * \param s - The string to be compared to the flag/name to determine
296 * whether the arg matches.
297 */
298 virtual bool argMatches( const std::string& s ) const;
299
300 /**
301 * Returns a simple string representation of the argument.
302 * Primarily for debugging.
303 */
304 virtual std::string toString() const;
305
306 /**
307 * Returns a short ID for the usage.
308 * \param valueId - The value used in the id.
309 */
310 virtual std::string shortID( const std::string& valueId = "val" ) const;
311
312 /**
313 * Returns a long ID for the usage.
314 * \param valueId - The value used in the id.
315 */
316 virtual std::string longID( const std::string& valueId = "val" ) const;
317
318 /**
319 * Trims a value off of the flag.
320 * \param flag - The string from which the flag and value will be
321 * trimmed. Contains the flag once the value has been trimmed.
322 * \param value - Where the value trimmed from the string will
323 * be stored.
324 */
325 virtual void trimFlag( std::string& flag, std::string& value ) const;
326
327 /**
328 * Checks whether a given string has blank chars, indicating that
329 * it is a combined SwitchArg. If so, return true, otherwise return
330 * false.
331 * \param s - string to be checked.
332 */
333 bool _hasBlanks( const std::string& s ) const;
334
335 /**
336 * Sets the requireLabel. Used by XorHandler. You shouldn't ever
337 * use this.
338 * \param s - Set the requireLabel to this value.
339 */
340 void setRequireLabel( const std::string& s );
341
342 virtual bool allowMore();
343 virtual bool acceptsMultipleValues();
344
345};
346
347/**
348 * Typedef of an Arg list iterator.
349 */
350typedef std::list<Arg*>::iterator ArgListIterator;
351
352/**
353 * Typedef of an Arg vector iterator.
354 */
355typedef std::vector<Arg*>::iterator ArgVectorIterator;
356
357/**
358 * Typedef of a Visitor list iterator.
359 */
360typedef std::list<Visitor*>::iterator VisitorListIterator;
361
362
363//////////////////////////////////////////////////////////////////////
364//BEGIN Arg.cpp
365//////////////////////////////////////////////////////////////////////
366
367inline Arg::Arg(const std::string& flag,
368 const std::string& name,
369 const std::string& desc,
370 bool req,
371 bool valreq,
372 Visitor* v) :
373 _flag(flag),
374 _name(name),
375 _description(desc),
376 _required(req),
377 _requireLabel("required"),
378 _valueRequired(valreq),
379 _alreadySet(false),
380 _visitor( v ),
381 _ignoreable(true),
382 _xorSet(false),
383 _acceptsMultipleValues(false)
384{
385 if ( _flag.length() > 1 )
387 "Argument flag can only be one character long", toString() ) );
388
389 if ( _name != ignoreNameString() &&
390 ( _flag == Arg::flagStartString() ||
392 _flag == " " ) )
393 throw(SpecificationException("Argument flag cannot be either '" +
394 Arg::flagStartString() + "' or '" +
395 Arg::nameStartString() + "' or a space.",
396 toString() ) );
397
398 if ( /*( _name.find( Arg::flagStartString(), 0 ) != std::string::npos ) || */
399 ( _name.find( Arg::nameStartString(), 0 ) != std::string::npos ) ||
400 ( _name.find( " ", 0 ) != std::string::npos ) )
401 throw(SpecificationException("Argument name cannot contain either '" +
402 Arg::flagStartString() + "' or '" +
403 Arg::nameStartString() + "' or space.",
404 toString() ) );
405
406}
407
408inline Arg::~Arg() { }
409
410inline std::string Arg::shortID( const std::string& valueId ) const
411{
412 std::string id = "";
413
414 if ( _flag != "" )
416 else
418
419 std::string delim = " ";
420 delim[0] = Arg::delimiter(); // ugly!!!
421
422 if ( _valueRequired )
423 id += delim + "<" + valueId + ">";
424
425 if ( !_required )
426 id = "[" + id + "]";
427
428 return id;
429}
430
431inline std::string Arg::longID( const std::string& valueId ) const
432{
433 std::string id = "";
434
435 if ( _flag != "" )
436 {
437 id += Arg::flagStartString() + _flag;
438
439 if ( _valueRequired )
440 id += " <" + valueId + ">";
441
442 id += ", ";
443 }
444
445 id += Arg::nameStartString() + _name;
446
447 if ( _valueRequired )
448 id += " <" + valueId + ">";
449
450 return id;
451
452}
453
454inline bool Arg::operator==(const Arg& a) const
455{
456 if ( ( _flag != "" && _flag == a._flag ) || _name == a._name)
457 return true;
458 else
459 return false;
460}
461
462inline std::string Arg::getDescription() const
463{
464 std::string desc = "";
465 if ( _required )
466 desc = "(" + _requireLabel + ") ";
467
468// if ( _valueRequired )
469// desc += "(value required) ";
470
471 desc += _description;
472 return desc;
473}
474
475inline const std::string& Arg::getFlag() const { return _flag; }
476
477inline const std::string& Arg::getName() const { return _name; }
478
479inline bool Arg::isRequired() const { return _required; }
480
481inline bool Arg::isValueRequired() const { return _valueRequired; }
482
483inline bool Arg::isSet() const
484{
485 if ( _alreadySet && !_xorSet )
486 return true;
487 else
488 return false;
489}
490
491inline bool Arg::isIgnoreable() const { return _ignoreable; }
492
493inline void Arg::setRequireLabel( const std::string& s)
494{
495 _requireLabel = s;
496}
497
498inline bool Arg::argMatches( const std::string& argFlag ) const
499{
500 if ( ( argFlag == Arg::flagStartString() + _flag && _flag != "" ) ||
501 argFlag == Arg::nameStartString() + _name )
502 return true;
503 else
504 return false;
505}
506
507inline std::string Arg::toString() const
508{
509 std::string s = "";
510
511 if ( _flag != "" )
512 s += Arg::flagStartString() + _flag + " ";
513
514 s += "(" + Arg::nameStartString() + _name + ")";
515
516 return s;
517}
518
519inline void Arg::_checkWithVisitor() const
520{
521 if ( _visitor != NULL )
522 _visitor->visit();
523}
524
525/**
526 * Implementation of trimFlag.
527 */
528inline void Arg::trimFlag(std::string& flag, std::string& value) const
529{
530 int stop = 0;
531 for ( int i = 0; static_cast<unsigned int>(i) < flag.length(); i++ )
532 if ( flag[i] == Arg::delimiter() )
533 {
534 stop = i;
535 break;
536 }
537
538 if ( stop > 1 )
539 {
540 value = flag.substr(stop+1);
541 flag = flag.substr(0,stop);
542 }
543
544}
545
546/**
547 * Implementation of _hasBlanks.
548 */
549inline bool Arg::_hasBlanks( const std::string& s ) const
550{
551 for ( int i = 1; static_cast<unsigned int>(i) < s.length(); i++ )
552 if ( s[i] == Arg::blankChar() )
553 return true;
554
555 return false;
556}
557
559{
560 _required = true;
561}
562
563inline void Arg::xorSet()
564{
565 _alreadySet = true;
566 _xorSet = true;
567}
568
569/**
570 * Overridden by Args that need to added to the end of the list.
571 */
572inline void Arg::addToList( std::list<Arg*>& argList ) const
573{
574 argList.push_front( const_cast<Arg*>(this) );
575}
576
577inline bool Arg::allowMore()
578{
579 return false;
580}
581
583{
585}
586
587//////////////////////////////////////////////////////////////////////
588//END Arg.cpp
589//////////////////////////////////////////////////////////////////////
590
591} //namespace TCLAP
592
593#endif
594
A virtual base class that defines the essential data for all arguments.
Definition Arg.h:52
static char blankChar()
The char used as a place holder when SwitchArgs are combined.
Definition Arg.h:196
void _checkWithVisitor() const
Performs the special handling described by the Vistitor.
Definition Arg.h:519
bool _acceptsMultipleValues
Definition Arg.h:136
virtual ~Arg()
Destructor.
Definition Arg.h:408
bool isSet() const
Indicates whether the argument has already been set.
Definition Arg.h:483
virtual std::string longID(const std::string &valueId="val") const
Returns a long ID for the usage.
Definition Arg.h:431
static const std::string nameStartString()
The sting that indicates the beginning of a name.
Definition Arg.h:213
static void beginIgnoring()
Begin ignoring arguments since the "--" argument was specified.
Definition Arg.h:178
std::string _requireLabel
Label to be used in usage description.
Definition Arg.h:101
bool _hasBlanks(const std::string &s) const
Checks whether a given string has blank chars, indicating that it is a combined SwitchArg.
Definition Arg.h:549
static bool ignoreRest()
Whether to ignore the rest.
Definition Arg.h:183
bool isIgnoreable() const
Indicates whether the argument can be ignored, if desired.
Definition Arg.h:491
void forceRequired()
Sets _required to true.
Definition Arg.h:558
virtual bool processArg(int *i, std::vector< std::string > &args)=0
Pure virtual method meant to handle the parsing and value assignment of the string on the command lin...
const std::string & getFlag() const
Returns the argument flag.
Definition Arg.h:475
static const std::string ignoreNameString()
The name used to identify the ignore rest argument.
Definition Arg.h:218
bool _valueRequired
Indicates whether a value is required for the argument.
Definition Arg.h:108
bool isValueRequired() const
Indicates whether a value must be specified for argument.
Definition Arg.h:481
static char flagStartChar()
The char that indicates the beginning of a flag.
Definition Arg.h:201
bool _alreadySet
Indicates whether the argument has been set.
Definition Arg.h:115
bool _ignoreable
Whether this argument can be ignored, if desired.
Definition Arg.h:128
std::string _description
Description of the argument.
Definition Arg.h:90
virtual void addToList(std::list< Arg * > &argList) const
Adds this to the specified list of Args.
Definition Arg.h:572
virtual bool allowMore()
Definition Arg.h:577
const std::string & getName() const
Returns the argument name.
Definition Arg.h:477
Visitor * _visitor
A pointer to a vistitor object.
Definition Arg.h:123
static char delimiter()
The delimiter that separates an argument flag/name from the value.
Definition Arg.h:189
void setRequireLabel(const std::string &s)
Sets the requireLabel.
Definition Arg.h:493
std::string getDescription() const
Returns the argument description.
Definition Arg.h:462
Arg(const std::string &flag, const std::string &name, const std::string &desc, bool req, bool valreq, Visitor *v=NULL)
Primary constructor.
Definition Arg.h:367
bool _xorSet
Indicates that the arg was set as part of an XOR and not on the command line.
Definition Arg.h:134
static char & delimiterRef()
The delimiter that separates an argument flag/name from the value.
Definition Arg.h:64
std::string _name
A single work namd indentifying the argument.
Definition Arg.h:85
virtual bool argMatches(const std::string &s) const
A method that tests whether a string matches this argument.
Definition Arg.h:498
static bool & ignoreRestRef()
Indicates whether the rest of the arguments should be ignored.
Definition Arg.h:58
static void setDelimiter(char c)
Sets the delimiter for all arguments.
Definition Arg.h:224
bool _required
Indicating whether the argument is required.
Definition Arg.h:95
virtual bool acceptsMultipleValues()
Definition Arg.h:582
virtual void trimFlag(std::string &flag, std::string &value) const
Trims a value off of the flag.
Definition Arg.h:528
virtual std::string toString() const
Returns a simple string representation of the argument.
Definition Arg.h:507
std::string _flag
The single char flag used to identify the argument.
Definition Arg.h:76
void xorSet()
Sets the _alreadySet value to true.
Definition Arg.h:563
virtual bool isRequired() const
Indicates whether the argument is required.
Definition Arg.h:479
virtual std::string shortID(const std::string &valueId="val") const
Returns a short ID for the usage.
Definition Arg.h:410
virtual bool operator==(const Arg &a) const
Operator ==.
Definition Arg.h:454
static const std::string flagStartString()
The sting that indicates the beginning of a flag.
Definition Arg.h:207
Thrown from Arg and CmdLine when an Arg is improperly specified, e.g.
A base class that defines the interface for visitors.
Definition Visitor.h:40
virtual void visit()
Does nothing.
Definition Visitor.h:56
Definition Arg.h:44
std::vector< Arg * >::iterator ArgVectorIterator
Typedef of an Arg vector iterator.
Definition Arg.h:355
std::list< Visitor * >::iterator VisitorListIterator
Typedef of a Visitor list iterator.
Definition Arg.h:360
std::list< Arg * >::iterator ArgListIterator
Typedef of an Arg list iterator.
Definition Arg.h:350



Page generated by Doxygen 1.9.7 for MRPT 1.4.0 SVN: at Tue Jun 27 17:12:06 UTC 2023