Main MRPT website > C++ reference for MRPT 1.3.2
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-2015, 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
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.12 for MRPT 1.3.2 SVN: at Thu Nov 10 13:46:27 UTC 2016