cmnCommandLineOptions Class Reference

Set command line options and parse command line arguments. More...

#include <cmnCommandLineOptions.h>

Inheritance diagram for cmnCommandLineOptions:

Classes
class	OptionBase
class	OptionNoValue
class	OptionOneValueBase
class	OptionOneValue
class	OptionMultipleValuesBase
class	OptionMultipleValues

Public Types
enum	RequiredType { REQUIRED_OPTION , OPTIONAL_OPTION , SQUASH_REQUIRED_OPTION }

Public Member Functions
	cmnCommandLineOptions (void)
	~cmnCommandLineOptions ()
bool	AddOptionNoValue (const std::string &shortOption, const std::string &longOption, const std::string &description, RequiredType required=OPTIONAL_OPTION)
template<typename _elementType>
bool	AddOptionOneValue (const std::string &shortOption, const std::string &longOption, const std::string &description, RequiredType required, _elementType *value)
template<typename _elementType>
bool	AddOptionMultipleValues (const std::string &shortOption, const std::string &longOption, const std::string &description, RequiredType required, std::list< _elementType > *value)
bool	Parse (int argc, const char *argv[], std::string &errorMessage)
bool	Parse (int argc, char *argv[], std::string &errorMessage)
bool	Parse (const std::vector< std::string > &arguments, std::string &errorMessage)
bool	Parse (int argc, char *argv[], std::ostream &outputStream)
bool	Parse (const std::vector< std::string > &arguments, std::ostream &outputStream)
void	PrintUsage (std::ostream &outputStream)
bool	IsSet (const std::string &option)
void	PrintParsedArguments (std::string &parsedArguments) const
Public Member Functions inherited from cmnGenericObject
virtual	~cmnGenericObject (void)
virtual const cmnClassServicesBase *	Services (void) const =0
bool	ReconstructFrom (const cmnGenericObject &other)
std::string	ToString (void) const
virtual void	ToStream (std::ostream &outputStream) const
virtual void	ToStreamRaw (std::ostream &outputStream, const char delimiter=' ', bool headerOnly=false, const std::string &headerPrefix="") const
virtual bool	FromStreamRaw (std::istream &inputStream, const char delimiter=' ')
virtual void	SerializeRaw (std::ostream &outputStream) const
virtual void	DeSerializeRaw (std::istream &inputStream)
virtual cmnLogger::StreamBufType *	GetLogMultiplexer (void) const
virtual size_t	ScalarNumber (void) const
virtual bool	ScalarNumberIsFixed (void) const
virtual double	Scalar (const size_t CMN_UNUSED(index)) const CISST_THROW(std
virtual std::string	ScalarDescription (const size_t CMN_UNUSED(index), const std::string &CMN_UNUSED(userDescription)) const

Protected Types
typedef std::list< OptionBase * >	OptionsType

Protected Member Functions
OptionBase *	GetShortNoDash (const std::string &shortOption)
OptionBase *	GetLongNoDashDash (const std::string &longOption)
bool	ValidOptions (const std::string &shortOption, const std::string &longOption, std::string &cleanedShort, std::string &cleanedLong)
OptionBase *	Get (const std::string &option)

Protected Attributes
std::string	ProgramName
OptionsType	Options

Detailed Description

Set command line options and parse command line arguments.

This class should facilitate the development of command line tools requiring arguments. For example, it can be used to parse parameters such as "my_program -v --file path/file.h --iterations 2".

cmnCommandLineOptions options;
bool verbose;
std::string filename;
int iterations;
std::list<double> someNumbers;
options.AddOptionNoValue("v", "verbose", "more messages");
options.AddOptionOneValue("f", "file", "file name", cmnCommandLineOptions::REQUIRED_OPTION, &filename);
options.AddOptionOneValue("i", "iterations", "number of iterations", cmnCommandLineOptions::REQUIRED_OPTION, &iterations);
options.AddOptionMultipleValues("n", "number", "one or many numbers", cmnCommandLineOptions::REQUIRED_OPTION, &someNumbers);
 
std::string errorMessage;
if (!options.Parse(argc, argv, errorMessage)) {
    std::cerr << "Error: " << errorMessage << std::endl;
    options.PrintUsage(std::cerr);
    return -1;
}
 
verbose = options.IsSet("v"); // or IsSet("verbose")

In this example, note that the first option added doesn't require a value, i.e. the caller should just use the short option (-v) or the long one (–verbose).

The second and third options are required, i.e. the "Parse" call will return false if one or more required option is not found. Both options are added as "option with one value" which means that the parser expect a value and this option can not be use twice (such as "my_program -i 2 -i 3). The last parameter of "AddOptionOneValue" can be a string, an integer, a double or anything the C++ operator

can stream in using a single argument of the command line.

The "Parse" method takes the argc and argv of the "main" function. It also requires an empty string passed by reference to generate an error message in case the parse fails. If parsing the command line options fails, one can use PrintUsage to display all the valid options.

Member Typedef Documentation

OptionsType

typedef std::list<OptionBase *> cmnCommandLineOptions::OptionsType

protected

Member Enumeration Documentation

RequiredType

enum cmnCommandLineOptions::RequiredType

Enumerator
REQUIRED_OPTION
OPTIONAL_OPTION
SQUASH_REQUIRED_OPTION

Constructor & Destructor Documentation

cmnCommandLineOptions()

cmnCommandLineOptions::cmnCommandLineOptions

(

void

)

~cmnCommandLineOptions()

cmnCommandLineOptions::~cmnCommandLineOptions

(

)

Member Function Documentation

AddOptionMultipleValues()

template<typename _elementType>

bool cmnCommandLineOptions::AddOptionMultipleValues ( const std::string & shortOption, const std::string & longOption, const std::string & description, RequiredType required, std::list< _elementType > * value )

inline

AddOptionNoValue()

bool cmnCommandLineOptions::AddOptionNoValue	(	const std::string &	shortOption,
		const std::string &	longOption,
		const std::string &	description,
		RequiredType	required = OPTIONAL_OPTION )

AddOptionOneValue()

template<typename _elementType>

bool cmnCommandLineOptions::AddOptionOneValue ( const std::string & shortOption, const std::string & longOption, const std::string & description, RequiredType required, _elementType * value )

inline

Get()

OptionBase * cmnCommandLineOptions::Get ( const std::string & option )

protected

GetLongNoDashDash()

OptionBase * cmnCommandLineOptions::GetLongNoDashDash ( const std::string & longOption )

protected

GetShortNoDash()

OptionBase * cmnCommandLineOptions::GetShortNoDash ( const std::string & shortOption )

protected

IsSet()

bool cmnCommandLineOptions::IsSet

(

const std::string &

option

)

Check if an option has been set. This can be used after Parse to check if an optional value has been set or not. The option name can be either the short or long one.

Parse() [1/5]

bool cmnCommandLineOptions::Parse	(	const std::vector< std::string > &	arguments,
		std::ostream &	outputStream )

Parse() [2/5]

bool cmnCommandLineOptions::Parse	(	const std::vector< std::string > &	arguments,
		std::string &	errorMessage )

Parse() [3/5]

bool cmnCommandLineOptions::Parse	(	int	argc,
		char *	argv[],
		std::ostream &	outputStream )

Parse and display error messages as well as usage if an error is found.

Parse() [4/5]

bool cmnCommandLineOptions::Parse	(	int	argc,
		char *	argv[],
		std::string &	errorMessage )

Parse using an array of non const C strings. This is the default for most applications using C like main function. Internally it created an array of const char * pointing to the existing arrays and then call the other Parse method.

Parse() [5/5]

bool cmnCommandLineOptions::Parse	(	int	argc,
		const char *	argv[],
		std::string &	errorMessage )

Parse using an array of const C strings. This class doesn't modify any of the parameters so it is a bit safer. This also allows to create unit tests using static arrays of strings without warnings.

PrintParsedArguments()

void cmnCommandLineOptions::PrintParsedArguments

(

std::string &

parsedArguments

)

const

PrintUsage()

void cmnCommandLineOptions::PrintUsage

(

std::ostream &

outputStream

)

Print list of options with description to any C++ ostream. For example, options.PrintUsage(std::cout).

ValidOptions()

bool cmnCommandLineOptions::ValidOptions ( const std::string & shortOption, const std::string & longOption, std::string & cleanedShort, std::string & cleanedLong )

protected

Member Data Documentation

Options

OptionsType cmnCommandLineOptions::Options

protected

ProgramName

std::string cmnCommandLineOptions::ProgramName

protected

---

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

• tmp/cisst-saw/cisst/cisstCommon/cmnCommandLineOptions.h