tclap 1.6.0
Classes | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
TCLAP::CmdLine Class Reference

The base class that manages the command line definition and passes along the parsing to the appropriate Arg classes. More...

#include <CmdLine.h>

Inheritance diagram for TCLAP::CmdLine:
Inheritance graph
[legend]
Collaboration diagram for TCLAP::CmdLine:
Collaboration graph
[legend]

Classes

struct  MessageTranslator
 Optional callback used to localize user-facing strings. More...
 
struct  MessageTranslatorImpl
 
class  Registration
 

Public Member Functions

 CmdLine (const CmdLine &rhs)=delete
 Prevent accidental copying.
 
CmdLine & operator= (const CmdLine &rhs)=delete
 
 CmdLine (std::string message, const char delimiter=' ', std::string version="none", bool helpAndVersion=true)
 Command line constructor.
 
 ~CmdLine () override=default
 Deletes any resources allocated by a CmdLine object.
 
ArgContainer & add (Arg &a) override
 Adds an argument to the list of arguments to be parsed.
 
ArgContainer & add (Arg *a) override
 An alternative add.
 
ArgContainer & add (ArgGroup &args) override
 Adds an argument group to the list of arguments to be parsed.
 
void addToArgList (Arg *a) override
 
void xorAdd (Arg &a, Arg &b) override
 
void xorAdd (const std::vector< Arg * > &xors) override
 
void parse (int argc, const char *const *argv) override
 Parses the command line.
 
void parse (std::vector< std::string > &args)
 Parses the command line.
 
void setOutput (CmdLineOutput *co) override
 
std::string getVersion () const override
 Returns the version string.
 
std::string getProgramName () const override
 Returns the program name string.
 
std::list< Arg * > getArgList () const override
 
std::list< ArgGroup * > getArgGroups () override
 Returns the list of ArgGroups.
 
char getDelimiter () const override
 Returns the delimiter string.
 
std::string getMessage () const override
 Returns the message string.
 
bool hasHelpAndVersion () const override
 Indicates whether or not the help and version switches were created automatically.
 
void setExceptionHandling (const bool state)
 Disables or enables CmdLine's internal parsing exception handling.
 
bool hasExceptionHandling () const
 Returns the current state of the internal exception handling.
 
void reset () override
 Allows the CmdLine object to be reused.
 
void ignoreUnmatched (const bool ignore)
 Allows unmatched args to be ignored.
 
template<typename T >
void setMessageTranslator (const T &translator)
 Sets an optional message translator callback.
 
std::string translateMessage (const std::string &messageId, const std::string &fallback) const override
 Translates a built-in message.
 
void beginIgnoring () override
 Begin ignoring arguments since the "--" argument was specified.
 
bool ignoreRest () override
 Whether to ignore the rest.
 
- Public Member Functions inherited from TCLAP::CmdLineInterface
 ~CmdLineInterface () override=default
 Destructor.
 
void parse (std::vector< std::string > &args)
 Parses the command line.
 
- Public Member Functions inherited from TCLAP::ArgContainer
virtual ~ArgContainer ()=default
 

Protected Member Functions

bool attachGroup (ArgGroup &group) override
 
void missingArgsException (const std::list< ArgGroup * > &missing)
 Throws an exception listing the missing args.
 
bool _emptyCombined (const std::string &s)
 Checks whether a name/flag string matches entirely matches the Arg::blankChar.
 

Protected Attributes

std::list< Arg * > _argList
 The list of arguments that will be tested against the command line.
 
StandaloneArgs _standaloneArgs
 
StandaloneArgs _autoArgs
 
std::list< ArgGroup * > _argGroups
 Some args have set constraints on them (i.e., exactly or at most one must be specified.
 
std::string _progName
 The name of the program.
 
std::string _message
 A message used to describe the program.
 
std::string _version
 The version to be displayed with the –version switch.
 
int _numRequired
 The number of arguments that are required to be present on the command line.
 
char _delimiter
 The character that is used to separate the argument flag/name from the value.
 
bool _hasOptionalUnlabeledArg
 
bool _registrationActive
 
DeferDelete _deleteOnExit
 Add pointers that should be deleted as part of cleanup when this object is destroyed.
 
StdOutput _defaultOutput
 Default output handler if nothing is specified.
 
CmdLineOutput * _output
 Object that handles all output for the CmdLine.
 
bool _handleExceptions
 Should CmdLine handle parsing exceptions internally?
 
std::unique_ptr< MessageTranslator > _messageTranslator
 
SwitchArg * _ignoreArg
 Built-in arguments whose descriptions may need refreshing when the translator changes.
 
SwitchArg * _helpArg
 
SwitchArg * _versionArg
 

Detailed Description

The base class that manages the command line definition and passes along the parsing to the appropriate Arg classes.

Definition at line 86 of file CmdLine.h.

Constructor & Destructor Documentation

◆ CmdLine() [1/2]

TCLAP::CmdLine::CmdLine ( const CmdLine &  rhs)
delete

Prevent accidental copying.

◆ CmdLine() [2/2]

TCLAP::CmdLine::CmdLine ( std::string  message,
const char  delimiter = ' ',
std::string  version = "none",
bool  helpAndVersion = true 
)
inline

Command line constructor.

Defines how the arguments will be parsed.

Parameters
message- The message to be used in the usage output.
delimiter- The character that is used to separate the argument flag/name from the value. Defaults to ' ' (space).
version- The version number to be used in the –version switch.
helpAndVersion- Whether or not to create the Help and Version switches. Defaults to true.

Definition at line 402 of file CmdLine.h.

◆ ~CmdLine()

TCLAP::CmdLine::~CmdLine ( )
overridedefault

Deletes any resources allocated by a CmdLine object.

Member Function Documentation

◆ _emptyCombined()

bool TCLAP::CmdLine::_emptyCombined ( const std::string &  s)
inlineprotected

Checks whether a name/flag string matches entirely matches the Arg::blankChar.

Used when multiple switches are combined into a single argument.

Parameters
s- The message to be used in the usage.

Definition at line 725 of file CmdLine.h.

References TCLAP::Arg::blankChar(), and TCLAP::Arg::flagStartChar().

Here is the call graph for this function:

◆ add() [1/3]

ArgContainer & TCLAP::CmdLine::add ( Arg &  a)
inlineoverridevirtual

Adds an argument to the list of arguments to be parsed.

Parameters
a- Argument to be added.
Return values
Areference to this so that add calls can be chained

Implements TCLAP::CmdLineInterface.

Definition at line 666 of file CmdLine.h.

References add().

Referenced by add(), and attachGroup().

Here is the call graph for this function:

◆ add() [2/3]

ArgContainer & TCLAP::CmdLine::add ( Arg *  a)
inlineoverridevirtual

An alternative add.

Functionally identical.

Parameters
a- Argument to be added.
Return values
Areference to this so that add calls can be chained

Implements TCLAP::CmdLineInterface.

Definition at line 674 of file CmdLine.h.

References TCLAP::ArgGroup::_args, _standaloneArgs, TCLAP::CmdLine::Registration::add(), and TCLAP::CmdLine::Registration::commit().

Here is the call graph for this function:

◆ add() [3/3]

ArgContainer & TCLAP::CmdLine::add ( ArgGroup &  args)
inlineoverridevirtual

Adds an argument group to the list of arguments to be parsed.

All arguments in the group are added and the ArgGroup object will validate that the input matches its constraints.

Parameters
args- Argument group to be added.
Return values
Areference to this so that add calls can be chained

Implements TCLAP::CmdLineInterface.

Definition at line 653 of file CmdLine.h.

References _argGroups, TCLAP::ArgGroup::_parser, TCLAP::CmdLine::Registration::add(), and TCLAP::CmdLine::Registration::commit().

Here is the call graph for this function:

◆ addToArgList()

void TCLAP::CmdLine::addToArgList ( Arg *  a)
inlineoverridevirtual

Implements TCLAP::CmdLineInterface.

Definition at line 668 of file CmdLine.h.

References TCLAP::CmdLine::Registration::add(), and TCLAP::CmdLine::Registration::commit().

Here is the call graph for this function:

◆ attachGroup()

bool TCLAP::CmdLine::attachGroup ( ArgGroup &  group)
inlineoverrideprotectedvirtual

Reimplemented from TCLAP::CmdLineInterface.

Definition at line 135 of file CmdLine.h.

References add().

Here is the call graph for this function:

◆ beginIgnoring()

void TCLAP::CmdLine::beginIgnoring ( )
inlineoverridevirtual

Begin ignoring arguments since the "--" argument was specified.

Implements TCLAP::CmdLineInterface.

Definition at line 394 of file CmdLine.h.

◆ getArgGroups()

std::list< ArgGroup * > TCLAP::CmdLine::getArgGroups ( )
inlineoverridevirtual

Returns the list of ArgGroups.

Implements TCLAP::CmdLineInterface.

Definition at line 331 of file CmdLine.h.

References _argGroups, and _autoArgs.

◆ getArgList()

std::list< Arg * > TCLAP::CmdLine::getArgList ( ) const
inlineoverridevirtual

Implements TCLAP::CmdLineInterface.

Definition at line 328 of file CmdLine.h.

References _argList.

◆ getDelimiter()

char TCLAP::CmdLine::getDelimiter ( ) const
inlineoverridevirtual

Returns the delimiter string.

Implements TCLAP::CmdLineInterface.

Definition at line 337 of file CmdLine.h.

References _delimiter.

◆ getMessage()

std::string TCLAP::CmdLine::getMessage ( ) const
inlineoverridevirtual

Returns the message string.

Implements TCLAP::CmdLineInterface.

Definition at line 338 of file CmdLine.h.

References _message.

◆ getProgramName()

std::string TCLAP::CmdLine::getProgramName ( ) const
inlineoverridevirtual

Returns the program name string.

Implements TCLAP::CmdLineInterface.

Definition at line 323 of file CmdLine.h.

References _progName.

◆ getVersion()

std::string TCLAP::CmdLine::getVersion ( ) const
inlineoverridevirtual

Returns the version string.

Implements TCLAP::CmdLineInterface.

Definition at line 321 of file CmdLine.h.

References _version.

◆ hasExceptionHandling()

bool TCLAP::CmdLine::hasExceptionHandling ( ) const
inline

Returns the current state of the internal exception handling.

Return values
trueParsing exceptions are handled internally.
falseParsing exceptions are propagated to the caller.

Definition at line 356 of file CmdLine.h.

References _handleExceptions.

◆ hasHelpAndVersion()

bool TCLAP::CmdLine::hasHelpAndVersion ( ) const
inlineoverridevirtual

Indicates whether or not the help and version switches were created automatically.

Implements TCLAP::CmdLineInterface.

Definition at line 339 of file CmdLine.h.

◆ ignoreRest()

bool TCLAP::CmdLine::ignoreRest ( )
inlineoverridevirtual

Whether to ignore the rest.

Implements TCLAP::CmdLineInterface.

Definition at line 395 of file CmdLine.h.

◆ ignoreUnmatched()

void TCLAP::CmdLine::ignoreUnmatched ( const bool  ignore)
inline

Allows unmatched args to be ignored.

By default false.

Parameters
ignoreIf true the cmdline will ignore any unmatched args and if false it will behave as normal.

Definition at line 778 of file CmdLine.h.

◆ missingArgsException()

void TCLAP::CmdLine::missingArgsException ( const std::list< ArgGroup * > &  missing)
inlineprotected

Throws an exception listing the missing args.

Definition at line 731 of file CmdLine.h.

References _argList, and translateMessage().

Here is the call graph for this function:

◆ operator=()

CmdLine & TCLAP::CmdLine::operator= ( const CmdLine &  rhs)
delete

◆ parse() [1/2]

void TCLAP::CmdLine::parse ( int  argc,
const char *const *  argv 
)
inlineoverridevirtual

Parses the command line.

Parameters
argc- Number of arguments.
argv- Array of arguments.

Implements TCLAP::CmdLineInterface.

Definition at line 684 of file CmdLine.h.

References parse().

Referenced by parse().

Here is the call graph for this function:

◆ parse() [2/2]

void TCLAP::CmdLine::parse ( std::vector< std::string > &  args)
inline

Parses the command line.

Parameters
args- A vector of strings representing the args. args[0] is still the program name.

Definition at line 692 of file CmdLine.h.

References _handleExceptions, _output, TCLAP::CmdLineOutput::failure(), and TCLAP::ExitException::getExitStatus().

Here is the call graph for this function:

◆ reset()

void TCLAP::CmdLine::reset ( )
inlineoverridevirtual

Allows the CmdLine object to be reused.

Implements TCLAP::CmdLineInterface.

Definition at line 771 of file CmdLine.h.

References _argList, and _progName.

◆ setExceptionHandling()

void TCLAP::CmdLine::setExceptionHandling ( const bool  state)
inline

Disables or enables CmdLine's internal parsing exception handling.

Parameters
stateShould CmdLine handle parsing exceptions internally?

Definition at line 767 of file CmdLine.h.

References _handleExceptions.

◆ setMessageTranslator()

template<typename T >
void TCLAP::CmdLine::setMessageTranslator ( const T &  translator)
inline

Sets an optional message translator callback.

Definition at line 377 of file CmdLine.h.

References _messageTranslator.

◆ setOutput()

void TCLAP::CmdLine::setOutput ( CmdLineOutput *  co)
inlineoverridevirtual
Parameters
co- CmdLineOutput object that we want to use instead.

Implements TCLAP::CmdLineInterface.

Definition at line 765 of file CmdLine.h.

References _output.

◆ translateMessage()

std::string TCLAP::CmdLine::translateMessage ( const std::string &  messageId,
const std::string &  fallback 
) const
inlineoverridevirtual

Translates a built-in message.

Implements TCLAP::CmdLineInterface.

Definition at line 385 of file CmdLine.h.

References _messageTranslator.

Referenced by missingArgsException().

◆ xorAdd() [1/2]

void TCLAP::CmdLine::xorAdd ( Arg &  a,
Arg &  b 
)
inlineoverridevirtual
Deprecated:
Use OneOf instead.

Implements TCLAP::CmdLineInterface.

Definition at line 573 of file CmdLine.h.

References xorAdd().

Referenced by xorAdd().

Here is the call graph for this function:

◆ xorAdd() [2/2]

void TCLAP::CmdLine::xorAdd ( const std::vector< Arg * > &  xors)
inlineoverridevirtual
Deprecated:
Use OneOf instead.

Implements TCLAP::CmdLineInterface.

Definition at line 564 of file CmdLine.h.

References _deleteOnExit.

Member Data Documentation

◆ _argGroups

std::list<ArgGroup *> TCLAP::CmdLine::_argGroups
protected

Some args have set constraints on them (i.e., exactly or at most one must be specified.

Definition at line 101 of file CmdLine.h.

Referenced by add(), and getArgGroups().

◆ _argList

std::list<Arg *> TCLAP::CmdLine::_argList
protected

The list of arguments that will be tested against the command line.

Definition at line 92 of file CmdLine.h.

Referenced by TCLAP::CmdLine::Registration::commit(), getArgList(), missingArgsException(), and reset().

◆ _autoArgs

StandaloneArgs TCLAP::CmdLine::_autoArgs
protected

Definition at line 95 of file CmdLine.h.

Referenced by getArgGroups().

◆ _defaultOutput

StdOutput TCLAP::CmdLine::_defaultOutput
protected

Default output handler if nothing is specified.

Definition at line 150 of file CmdLine.h.

◆ _deleteOnExit

DeferDelete TCLAP::CmdLine::_deleteOnExit
protected

Add pointers that should be deleted as part of cleanup when this object is destroyed.

Definition at line 145 of file CmdLine.h.

Referenced by xorAdd().

◆ _delimiter

char TCLAP::CmdLine::_delimiter
protected

The character that is used to separate the argument flag/name from the value.

Defaults to ' ' (space).

Definition at line 129 of file CmdLine.h.

Referenced by TCLAP::CmdLine::Registration::add(), and getDelimiter().

◆ _handleExceptions

bool TCLAP::CmdLine::_handleExceptions
protected

Should CmdLine handle parsing exceptions internally?

Definition at line 160 of file CmdLine.h.

Referenced by hasExceptionHandling(), parse(), and setExceptionHandling().

◆ _hasOptionalUnlabeledArg

bool TCLAP::CmdLine::_hasOptionalUnlabeledArg
protected

Definition at line 132 of file CmdLine.h.

Referenced by TCLAP::CmdLine::Registration::commit().

◆ _helpArg

SwitchArg* TCLAP::CmdLine::_helpArg
protected

Definition at line 189 of file CmdLine.h.

◆ _ignoreArg

SwitchArg* TCLAP::CmdLine::_ignoreArg
protected

Built-in arguments whose descriptions may need refreshing when the translator changes.

Definition at line 188 of file CmdLine.h.

◆ _message

std::string TCLAP::CmdLine::_message
protected

A message used to describe the program.

Used in the usage output.

Definition at line 111 of file CmdLine.h.

Referenced by getMessage().

◆ _messageTranslator

std::unique_ptr<MessageTranslator> TCLAP::CmdLine::_messageTranslator
protected

Definition at line 182 of file CmdLine.h.

Referenced by setMessageTranslator(), and translateMessage().

◆ _numRequired

int TCLAP::CmdLine::_numRequired
protected

The number of arguments that are required to be present on the command line.

This is set dynamically, based on the Args added to the CmdLine object.

Definition at line 123 of file CmdLine.h.

Referenced by TCLAP::CmdLine::Registration::commit().

◆ _output

CmdLineOutput* TCLAP::CmdLine::_output
protected

Object that handles all output for the CmdLine.

Definition at line 155 of file CmdLine.h.

Referenced by parse(), and setOutput().

◆ _progName

std::string TCLAP::CmdLine::_progName
protected

The name of the program.

Set to argv[0].

Definition at line 106 of file CmdLine.h.

Referenced by getProgramName(), and reset().

◆ _registrationActive

bool TCLAP::CmdLine::_registrationActive
protected

◆ _standaloneArgs

StandaloneArgs TCLAP::CmdLine::_standaloneArgs
protected

Definition at line 94 of file CmdLine.h.

Referenced by add().

◆ _version

std::string TCLAP::CmdLine::_version
protected

The version to be displayed with the –version switch.

Definition at line 116 of file CmdLine.h.

Referenced by getVersion().

◆ _versionArg

SwitchArg* TCLAP::CmdLine::_versionArg
protected

Definition at line 190 of file CmdLine.h.


The documentation for this class was generated from the following file: