Main MRPT website > C++ reference for MRPT 1.4.0
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-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: 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
57namespace 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 */
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 */
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
272inline 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();
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
343inline 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
356inline 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
364inline void CmdLine::add( Arg& a )
365{
366 add( &a );
367}
368
369inline void CmdLine::add( Arg* a )
370{
371 for( ArgListIterator it = _argList.begin(); it != _argList.end(); it++ )
372 if ( *a == *(*it) )
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
383inline 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
439inline 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
451inline 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
472inline std::string& CmdLine::getVersion()
473{
474 return _version;
475}
476
477inline std::string& CmdLine::getProgramName()
478{
479 return _progName;
480}
481
482inline std::list<Arg*>& CmdLine::getArgList()
483{
484 return _argList;
485}
486
488{
489 return _xorHandler;
490}
491
493{
494 return _delimiter;
495}
496
497inline 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
(Added by JLBC for MRPT): An exception that indicates to CmdLine::parse that help,...
Definition: ArgException.h:200
A simple class that defines and argument exception.
Definition: ArgException.h:45
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
virtual std::string longID(const std::string &valueId="val") const
Returns a long ID for the usage.
Definition: Arg.h:431
static bool ignoreRest()
Whether to ignore the rest.
Definition: Arg.h:183
static const std::string ignoreNameString()
The name used to identify the ignore rest argument.
Definition: Arg.h:218
static char flagStartChar()
The char that indicates the beginning of a flag.
Definition: Arg.h:201
virtual void addToList(std::list< Arg * > &argList) const
Adds this to the specified list of Args.
Definition: Arg.h:572
static void setDelimiter(char c)
Sets the delimiter for all arguments.
Definition: Arg.h:224
virtual bool isRequired() const
Indicates whether the argument is required.
Definition: Arg.h:479
static const std::string flagStartString()
The sting that indicates the beginning of a flag.
Definition: Arg.h:207
The base class that manages the command line definition and passes along the parsing to the appropria...
Definition: CmdLine.h:64
bool _emptyCombined(const std::string &s)
Checks whether a name/flag string matches entirely matches the Arg::blankChar.
Definition: CmdLine.h:439
int _numRequired
The number of arguments that are required to be present on the command line.
Definition: CmdLine.h:93
std::string _version
The version to be displayed with the –version switch.
Definition: CmdLine.h:86
XorHandler _xorHandler
The handler that manages xoring lists of args.
Definition: CmdLine.h:104
std::list< Arg * > & getArgList()
Returns the argList.
Definition: CmdLine.h:482
std::string _message
A message used to describe the program.
Definition: CmdLine.h:81
char getDelimiter()
Returns the delimiter string.
Definition: CmdLine.h:492
void deleteOnExit(Arg *ptr)
Perform a delete ptr; operation on ptr when this object is deleted.
Definition: CmdLine.h:451
void setOutput(CmdLineOutput *co)
Definition: CmdLine.h:466
std::string & getProgramName()
Returns the program name string.
Definition: CmdLine.h:477
std::list< Arg * > _argList
The list of arguments that will be tested against the command line.
Definition: CmdLine.h:71
CmdLineOutput * _output
Object that handles all output for the CmdLine.
Definition: CmdLine.h:123
bool hasHelpAndVersion()
Indicates whether or not the help and version switches were created automatically.
Definition: CmdLine.h:502
char _delimiter
The character that is used to separate the argument flag/name from the value.
Definition: CmdLine.h:99
CmdLine(const std::string &message, const char delimiter=' ', const std::string &version="none", bool helpAndVersion=true)
Command line constructor.
Definition: CmdLine.h:272
std::list< Visitor * > _visitorDeleteOnExitList
A list of Visitors to be explicitly deleted when the destructor is called.
Definition: CmdLine.h:118
XorHandler & getXorHandler()
Returns the XorHandler.
Definition: CmdLine.h:487
std::string & getVersion()
Returns the version string.
Definition: CmdLine.h:472
virtual ~CmdLine()
Deletes any resources allocated by a CmdLine object.
Definition: CmdLine.h:287
std::string _progName
The name of the program.
Definition: CmdLine.h:76
std::string & getMessage()
Returns the message string.
Definition: CmdLine.h:497
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
bool _userSetOutput
Is set to true when a user sets the output object.
Definition: CmdLine.h:155
CmdLineOutput * getOutput()
Returns the CmdLineOutput object.
Definition: CmdLine.h:461
bool _helpAndVersion
Whether or not to automatically create help and version switches.
Definition: CmdLine.h:160
bool parse(int argc, char **argv)
Parses the command line.
Definition: CmdLine.h:383
std::list< Arg * > _argDeleteOnExitList
A list of Args to be explicitly deleted when the destructor is called.
Definition: CmdLine.h:111
void xorAdd(Arg &a, Arg &b)
Add two Args that will be xor'd.
Definition: CmdLine.h:356
The base class that manages the command line definition and passes along the parsing to the appropria...
The interface that any output object must implement.
Definition: CmdLineOutput.h:50
virtual void failure(CmdLineInterface &c, ArgException &e)=0
Generates some sort of output for a failure.
Thrown from CmdLine when the arguments on the command line are not properly specified,...
Definition: ArgException.h:152
A Visitor object that calls the usage method of the given CmdLineOutput object for the specified CmdL...
Definition: HelpVisitor.h:44
A Vistor that tells the CmdLine to begin ignoring arguments after this one is parsed.
Thrown from Arg and CmdLine when an Arg is improperly specified, e.g.
Definition: ArgException.h:176
A class that isolates any output from the CmdLine object so that it may be easily modified.
Definition: StdOutput.h:51
A simple switch argument.
Definition: SwitchArg.h:48
A Vistor that will call the version method of the given CmdLineOutput for the specified CmdLine objec...
A base class that defines the interface for visitors.
Definition: Visitor.h:40
This class handles lists of Arg's that are to be XOR'd on the command line.
Definition: XorHandler.h:47
int check(const Arg *a)
Checks whether the specified Arg is in one of the xor lists and if it does match one,...
Definition: XorHandler.h:108
void add(std::vector< Arg * > &ors)
Add a list of Arg*'s that will be orred together.
Definition: XorHandler.h:103
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.6 for MRPT 1.4.0 SVN: at Wed Mar 22 04:35:51 UTC 2023