Main MRPT website > C++ reference for MRPT 1.5.3
CmdLine.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-2017, 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: CmdLine.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 #ifndef TCLAP_CMDLINE_H
32 #define TCLAP_CMDLINE_H
33 
38 
43 
46 
49 
50 #include <string>
51 #include <vector>
52 #include <list>
53 #include <iostream>
54 #include <iomanip>
55 #include <algorithm>
56 
57 namespace TCLAP {
58 
59 /**
60  * The base class that manages the command line definition and passes
61  * along the parsing to the appropriate Arg classes.
62  */
63 class CmdLine : public CmdLineInterface
64 {
65  protected:
66 
67  /**
68  * The list of arguments that will be tested against the
69  * command line.
70  */
71  std::list<Arg*> _argList;
72 
73  /**
74  * The name of the program. Set to argv[0].
75  */
76  std::string _progName;
77 
78  /**
79  * A message used to describe the program. Used in the usage output.
80  */
81  std::string _message;
82 
83  /**
84  * The version to be displayed with the --version switch.
85  */
86  std::string _version;
87 
88  /**
89  * The number of arguments that are required to be present on
90  * the command line. This is set dynamically, based on the
91  * Args added to the CmdLine object.
92  */
94 
95  /**
96  * The character that is used to separate the argument flag/name
97  * from the value. Defaults to ' ' (space).
98  */
99  char _delimiter;
100 
101  /**
102  * The handler that manages xoring lists of args.
103  */
105 
106  /**
107  * A list of Args to be explicitly deleted when the destructor
108  * is called. At the moment, this only includes the three default
109  * Args.
110  */
111  std::list<Arg*> _argDeleteOnExitList;
112 
113  /**
114  * A list of Visitors to be explicitly deleted when the destructor
115  * is called. At the moment, these are the Vistors created for the
116  * default Args.
117  */
118  std::list<Visitor*> _visitorDeleteOnExitList;
119 
120  /**
121  * Object that handles all output for the CmdLine.
122  */
124 
125  /**
126  * Checks whether a name/flag string matches entirely matches
127  * the Arg::blankChar. Used when multiple switches are combined
128  * into a single argument.
129  * \param s - The message to be used in the usage.
130  */
131  bool _emptyCombined(const std::string& s);
132 
133  /**
134  * Perform a delete ptr; operation on ptr when this object is deleted.
135  */
136  void deleteOnExit(Arg* ptr);
137 
138  /**
139  * Perform a delete ptr; operation on ptr when this object is deleted.
140  */
141  void deleteOnExit(Visitor* ptr);
142 
143  private:
144 
145  /**
146  * Encapsulates the code common to the constructors (which is all
147  * of it).
148  */
149  void _constructor();
150 
151  /**
152  * Is set to true when a user sets the output object. We use this so
153  * that we don't delete objects that are created outside of this lib.
154  */
156 
157  /**
158  * Whether or not to automatically create help and version switches.
159  */
161 
162  public:
163 
164  /**
165  * Command line constructor. Defines how the arguments will be
166  * parsed.
167  * \param message - The message to be used in the usage
168  * output.
169  * \param delimiter - The character that is used to separate
170  * the argument flag/name from the value. Defaults to ' ' (space).
171  * \param version - The version number to be used in the
172  * --version switch.
173  * \param helpAndVersion - Whether or not to create the Help and
174  * Version switches. Defaults to true.
175  */
176  CmdLine(const std::string& message,
177  const char delimiter = ' ',
178  const std::string& version = "none",
179  bool helpAndVersion = true);
180 
181  /**
182  * Deletes any resources allocated by a CmdLine object.
183  */
184  virtual ~CmdLine();
185 
186  /**
187  * Adds an argument to the list of arguments to be parsed.
188  * \param a - Argument to be added.
189  */
190  void add( Arg& a );
191 
192  /**
193  * An alternative add. Functionally identical.
194  * \param a - Argument to be added.
195  */
196  void add( Arg* a );
197 
198  /**
199  * Add two Args that will be xor'd. If this method is used, add does
200  * not need to be called.
201  * \param a - Argument to be added and xor'd.
202  * \param b - Argument to be added and xor'd.
203  */
204  void xorAdd( Arg& a, Arg& b );
205 
206  /**
207  * Add a list of Args that will be xor'd. If this method is used,
208  * add does not need to be called.
209  * \param xors - List of Args to be added and xor'd.
210  */
211  void xorAdd( std::vector<Arg*>& xors );
212 
213  /**
214  * Parses the command line.
215  * \param argc - Number of arguments.
216  * \param argv - Array of arguments.
217  * \return (Added by JLBC for MRPT): Return false if the program should exit (error in args, it was --help, etc...)
218  */
219  bool parse(int argc, char** argv);
220 
221  /**
222  *
223  */
225 
226  /**
227  *
228  */
229  void setOutput(CmdLineOutput* co);
230 
231  /**
232  *
233  */
234  std::string& getVersion();
235 
236  /**
237  *
238  */
239  std::string& getProgramName();
240 
241  /**
242  *
243  */
244  std::list<Arg*>& getArgList();
245 
246  /**
247  *
248  */
250 
251  /**
252  *
253  */
254  char getDelimiter();
255 
256  /**
257  *
258  */
259  std::string& getMessage();
260 
261  /**
262  *
263  */
264  bool hasHelpAndVersion();
265 };
266 
267 
268 ///////////////////////////////////////////////////////////////////////////////
269 //Begin CmdLine.cpp
270 ///////////////////////////////////////////////////////////////////////////////
271 
272 inline CmdLine::CmdLine(const std::string& m,
273  char delim,
274  const std::string& v,
275  bool help )
276 : _progName("not_set_yet"),
277  _message(m),
278  _version(v),
279  _numRequired(0),
280  _delimiter(delim),
281  _userSetOutput(false),
282  _helpAndVersion(help)
283 {
284  _constructor();
285 }
286 
288 {
289  ArgListIterator argIter;
290  VisitorListIterator visIter;
291 
292  for( argIter = _argDeleteOnExitList.begin();
293  argIter != _argDeleteOnExitList.end();
294  ++argIter)
295  delete *argIter;
296 
297  for( visIter = _visitorDeleteOnExitList.begin();
298  visIter != _visitorDeleteOnExitList.end();
299  ++visIter)
300  delete *visIter;
301 
302  if ( !_userSetOutput )
303  delete _output;
304 }
305 
307 {
308  _output = new StdOutput;
309 
311 
312  Visitor* v;
313 
314  if ( _helpAndVersion )
315  {
316  v = new HelpVisitor( this, &_output );
317  SwitchArg* help = new SwitchArg("h","help",
318  "Displays usage information and exits.",
319  false, v);
320  add( help );
321  deleteOnExit(help);
322  deleteOnExit(v);
323 
324  v = new VersionVisitor( this, &_output );
325  SwitchArg* vers = new SwitchArg("","version",
326  "Displays version information and exits.",
327  false, v);
328  add( vers );
329  deleteOnExit(vers);
330  deleteOnExit(v);
331  }
332 
333  v = new IgnoreRestVisitor();
334  SwitchArg* ignore = new SwitchArg(Arg::flagStartString(),
336  "Ignores the rest of the labeled arguments following this flag.",
337  false, v);
338  add( ignore );
339  deleteOnExit(ignore);
340  deleteOnExit(v);
341 }
342 
343 inline void CmdLine::xorAdd( std::vector<Arg*>& ors )
344 {
345  _xorHandler.add( ors );
346 
347  for (ArgVectorIterator it = ors.begin(); it != ors.end(); it++)
348  {
349  (*it)->forceRequired();
350  (*it)->setRequireLabel( "OR required" );
351 
352  add( *it );
353  }
354 }
355 
356 inline void CmdLine::xorAdd( Arg& a, Arg& b )
357 {
358  std::vector<Arg*> ors;
359  ors.push_back( &a );
360  ors.push_back( &b );
361  xorAdd( ors );
362 }
363 
364 inline void CmdLine::add( Arg& a )
365 {
366  add( &a );
367 }
368 
369 inline void CmdLine::add( Arg* a )
370 {
371  for( ArgListIterator it = _argList.begin(); it != _argList.end(); it++ )
372  if ( *a == *(*it) )
373  throw( SpecificationException(
374  "Argument with same flag/name already exists!",
375  a->longID() ) );
376 
377  a->addToList( _argList );
378 
379  if ( a->isRequired() )
380  _numRequired++;
381 }
382 
383 inline bool CmdLine::parse(int argc, char** argv)
384 {
385  try {
386 
387  _progName = argv[0];
388 
389  // this step is necessary so that we have easy access to mutable strings.
390  std::vector<std::string> args;
391  for (int i = 1; i < argc; i++)
392  args.push_back(argv[i]);
393 
394  int requiredCount = 0;
395 
396  for (int i = 0; static_cast<unsigned int>(i) < args.size(); i++)
397  {
398  bool matched = false;
399  for (ArgListIterator it = _argList.begin(); it != _argList.end(); it++)
400  {
401  if ( (*it)->processArg( &i, args ) )
402  {
403  requiredCount += _xorHandler.check( *it );
404  matched = true;
405  break;
406  }
407  }
408 
409  // checks to see if the argument is an empty combined switch ...
410  // and if so, then we've actually matched it
411  if ( !matched && _emptyCombined( args[i] ) )
412  matched = true;
413 
414  if ( !matched && !Arg::ignoreRest() )
415  throw(CmdLineParseException("Couldn't find match for argument",
416  args[i]));
417  }
418 
419  if ( requiredCount < _numRequired )
420  throw(CmdLineParseException("One or more required arguments missing!"));
421 
422  if ( requiredCount > _numRequired )
423  throw(CmdLineParseException("Too many arguments!"));
424 
425  return true; // Ok
426 
427  }
428  catch ( ActionDoneException e )
429  {
430  return false; // Done
431  }
432  catch ( ArgException e )
433  {
434  _output->failure(*this,e);
435  return false; // Error
436  }
437 }
438 
439 inline bool CmdLine::_emptyCombined(const std::string& s)
440 {
441  if ( s[0] != Arg::flagStartChar() )
442  return false;
443 
444  for ( int i = 1; static_cast<unsigned int>(i) < s.length(); i++ )
445  if ( s[i] != Arg::blankChar() )
446  return false;
447 
448  return true;
449 }
450 
451 inline void CmdLine::deleteOnExit(Arg* ptr)
452 {
453  _argDeleteOnExitList.push_back(ptr);
454 }
455 
457 {
458  _visitorDeleteOnExitList.push_back(ptr);
459 }
460 
462 {
463  return _output;
464 }
465 
467 {
468  _userSetOutput = true;
469  _output = co;
470 }
471 
472 inline std::string& CmdLine::getVersion()
473 {
474  return _version;
475 }
476 
477 inline std::string& CmdLine::getProgramName()
478 {
479  return _progName;
480 }
481 
482 inline std::list<Arg*>& CmdLine::getArgList()
483 {
484  return _argList;
485 }
486 
488 {
489  return _xorHandler;
490 }
491 
493 {
494  return _delimiter;
495 }
496 
497 inline std::string& CmdLine::getMessage()
498 {
499  return _message;
500 }
501 
503 {
504  return _helpAndVersion;
505 }
506 
507 ///////////////////////////////////////////////////////////////////////////////
508 //End CmdLine.cpp
509 ///////////////////////////////////////////////////////////////////////////////
510 
511 
512 
513 } //namespace TCLAP
514 #endif
virtual void addToList(std::list< Arg *> &argList) const
Adds this to the specified list of Args.
Definition: Arg.h:572
std::list< Arg * > & getArgList()
Returns the argList.
Definition: CmdLine.h:482
XorHandler _xorHandler
The handler that manages xoring lists of args.
Definition: CmdLine.h:104
The interface that any output object must implement.
Definition: CmdLineOutput.h:49
void setOutput(CmdLineOutput *co)
Definition: CmdLine.h:466
std::list< Arg * >::iterator ArgListIterator
Typedef of an Arg list iterator.
Definition: Arg.h:350
std::list< Arg * > _argList
The list of arguments that will be tested against the command line.
Definition: CmdLine.h:71
void add(std::vector< Arg *> &ors)
Add a list of Arg*&#39;s that will be orred together.
Definition: XorHandler.h:103
CmdLineOutput * getOutput()
Returns the CmdLineOutput object.
Definition: CmdLine.h:461
char _delimiter
The character that is used to separate the argument flag/name from the value.
Definition: CmdLine.h:99
This class handles lists of Arg&#39;s that are to be XOR&#39;d on the command line.
Definition: XorHandler.h:46
static void setDelimiter(char c)
Sets the delimiter for all arguments.
Definition: Arg.h:224
CmdLine(const std::string &message, const char delimiter=' ', const std::string &version="none", bool helpAndVersion=true)
Command line constructor.
Definition: CmdLine.h:272
(Added by JLBC for MRPT): An exception that indicates to CmdLine::parse that help,version,...
Definition: ArgException.h:199
bool _emptyCombined(const std::string &s)
Checks whether a name/flag string matches entirely matches the Arg::blankChar.
Definition: CmdLine.h:439
Definition: Arg.h:44
int check(const Arg *a)
Checks whether the specified Arg is in one of the xor lists and if it does match one, returns the size of the xor list that the Arg matched.
Definition: XorHandler.h:108
virtual std::string longID(const std::string &valueId="val") const
Returns a long ID for the usage.
Definition: Arg.h:431
std::string & getProgramName()
Returns the program name string.
Definition: CmdLine.h:477
A virtual base class that defines the essential data for all arguments.
Definition: Arg.h:51
void xorAdd(Arg &a, Arg &b)
Add two Args that will be xor&#39;d.
Definition: CmdLine.h:356
Thrown from Arg and CmdLine when an Arg is improperly specified, e.g.
Definition: ArgException.h:175
static char flagStartChar()
The char that indicates the beginning of a flag.
Definition: Arg.h:201
A class that isolates any output from the CmdLine object so that it may be easily modified...
Definition: StdOutput.h:50
void add(Arg &a)
Adds an argument to the list of arguments to be parsed.
Definition: CmdLine.h:364
void _constructor()
Encapsulates the code common to the constructors (which is all of it).
Definition: CmdLine.h:306
int _numRequired
The number of arguments that are required to be present on the command line.
Definition: CmdLine.h:93
A simple switch argument.
Definition: SwitchArg.h:47
virtual bool isRequired() const
Indicates whether the argument is required.
Definition: Arg.h:479
virtual void failure(CmdLineInterface &c, ArgException &e)=0
Generates some sort of output for a failure.
The base class that manages the command line definition and passes along the parsing to the appropria...
Definition: CmdLine.h:63
std::vector< Arg * >::iterator ArgVectorIterator
Typedef of an Arg vector iterator.
Definition: Arg.h:355
bool _userSetOutput
Is set to true when a user sets the output object.
Definition: CmdLine.h:155
std::string _version
The version to be displayed with the –version switch.
Definition: CmdLine.h:86
virtual ~CmdLine()
Deletes any resources allocated by a CmdLine object.
Definition: CmdLine.h:287
static const std::string flagStartString()
The sting that indicates the beginning of a flag.
Definition: Arg.h:207
Thrown from CmdLine when the arguments on the command line are not properly specified, e.g.
Definition: ArgException.h:151
A Vistor that will call the version method of the given CmdLineOutput for the specified CmdLine objec...
std::list< Visitor * > _visitorDeleteOnExitList
A list of Visitors to be explicitly deleted when the destructor is called.
Definition: CmdLine.h:118
A base class that defines the interface for visitors.
Definition: Visitor.h:39
static const std::string ignoreNameString()
The name used to identify the ignore rest argument.
Definition: Arg.h:218
std::string & getVersion()
Returns the version string.
Definition: CmdLine.h:472
std::string _message
A message used to describe the program.
Definition: CmdLine.h:81
A Visitor object that calls the usage method of the given CmdLineOutput object for the specified CmdL...
Definition: HelpVisitor.h:43
void deleteOnExit(Arg *ptr)
Perform a delete ptr; operation on ptr when this object is deleted.
Definition: CmdLine.h:451
std::string _progName
The name of the program.
Definition: CmdLine.h:76
std::list< Arg * > _argDeleteOnExitList
A list of Args to be explicitly deleted when the destructor is called.
Definition: CmdLine.h:111
bool hasHelpAndVersion()
Indicates whether or not the help and version switches were created automatically.
Definition: CmdLine.h:502
CmdLineOutput * _output
Object that handles all output for the CmdLine.
Definition: CmdLine.h:123
static bool ignoreRest()
Whether to ignore the rest.
Definition: Arg.h:183
A simple class that defines and argument exception.
Definition: ArgException.h:44
std::list< Visitor * >::iterator VisitorListIterator
Typedef of a Visitor list iterator.
Definition: Arg.h:360
char getDelimiter()
Returns the delimiter string.
Definition: CmdLine.h:492
std::string & getMessage()
Returns the message string.
Definition: CmdLine.h:497
static const char * version
Definition: exprtk.hpp:37693
XorHandler & getXorHandler()
Returns the XorHandler.
Definition: CmdLine.h:487
bool _helpAndVersion
Whether or not to automatically create help and version switches.
Definition: CmdLine.h:160
A Vistor that tells the CmdLine to begin ignoring arguments after this one is parsed.
static char blankChar()
The char used as a place holder when SwitchArgs are combined.
Definition: Arg.h:196
bool parse(int argc, char **argv)
Parses the command line.
Definition: CmdLine.h:383
The base class that manages the command line definition and passes along the parsing to the appropria...



Page generated by Doxygen 1.8.13 for MRPT 1.5.3 at Mon Oct 30 10:27:08 UTC 2017