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 
44 namespace 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  */
51 class 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  */
95  bool _required;
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  */
134  bool _xorSet;
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  */
351 
352 /**
353  * Typedef of an Arg vector iterator.
354  */
356 
357 /**
358  * Typedef of a Visitor list iterator.
359  */
361 
362 
363 //////////////////////////////////////////////////////////////////////
364 //BEGIN Arg.cpp
365 //////////////////////////////////////////////////////////////////////
366 
367 inline 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() ||
391  _flag == Arg::nameStartString() ||
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 
408 inline Arg::~Arg() { }
409 
410 inline std::string Arg::shortID( const std::string& valueId ) const
411 {
412  std::string id = "";
413 
414  if ( _flag != "" )
415  id = Arg::flagStartString() + _flag;
416  else
417  id = Arg::nameStartString() + _name;
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 
431 inline 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 
454 inline 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 
462 inline 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 
475 inline const std::string& Arg::getFlag() const { return _flag; }
476 
477 inline const std::string& Arg::getName() const { return _name; }
478 
479 inline bool Arg::isRequired() const { return _required; }
480 
481 inline bool Arg::isValueRequired() const { return _valueRequired; }
482 
483 inline bool Arg::isSet() const
484 {
485  if ( _alreadySet && !_xorSet )
486  return true;
487  else
488  return false;
489 }
490 
491 inline bool Arg::isIgnoreable() const { return _ignoreable; }
492 
493 inline void Arg::setRequireLabel( const std::string& s)
494 {
495  _requireLabel = s;
496 }
497 
498 inline 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 
507 inline 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 
519 inline void Arg::_checkWithVisitor() const
520 {
521  if ( _visitor != NULL )
522  _visitor->visit();
523 }
524 
525 /**
526  * Implementation of trimFlag.
527  */
528 inline 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  */
549 inline 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 
558 inline void Arg::forceRequired()
559 {
560  _required = true;
561 }
562 
563 inline 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  */
572 inline void Arg::addToList( std::list<Arg*>& argList ) const
573 {
574  argList.push_front( const_cast<Arg*>(this) );
575 }
576 
577 inline bool Arg::allowMore()
578 {
579  return false;
580 }
581 
583 {
584  return _acceptsMultipleValues;
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
static char & delimiterRef()
The delimiter that separates an argument flag/name from the value.
Definition: Arg.h:64
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
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 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
static bool & ignoreRestRef()
Indicates whether the rest of the arguments should be ignored.
Definition: Arg.h:58
Thrown from Arg and CmdLine when an Arg is improperly specified, e.g.
Definition: ArgException.h:176
A base class that defines the interface for visitors.
Definition: Visitor.h:40
virtual void visit()
Does nothing.
Definition: Visitor.h:56
Scalar * iterator
Definition: eigen_plugins.h:23
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.1 for MRPT 1.4.0 SVN: at Mon Apr 18 04:07:33 UTC 2022