Class that helps parse command line input arguments from (argc,argv[]) and set options. More...

#include <Teuchos_CommandLineProcessor.hpp>

Classes
class	ParseError
	Thrown if a parse std::exception occurs and throwExceptions==true. More...
class	HelpPrinted
	Thrown if –help was specified and throwExceptions==true. More...
class	UnrecognizedOption
	Thrown if an unrecognized option was found and throwExceptions==true. More...
struct	opt_val_val_t
struct	opt_doc_t
struct	enum_opt_data_t
class	TimeMonitorSurrogate
	Interface by which CommandLineProcessor may use TimeMonitor. More...

Related Symbols
(Note that these are not member symbols.)
void	setVerbosityLevelOption (const std::string &optionName, EVerbosityLevel verbLevel, const std::string &docString, CommandLineProcessor clp, const bool required=false)
	Set a verbosity level parameter on a CommandLineProcessor object..

Public types
enum	EParseCommandLineReturn { PARSE_SUCCESSFUL = 0 , PARSE_HELP_PRINTED = 1 , PARSE_UNRECOGNIZED_OPTION = 2 , PARSE_ERROR = 3 }
	Return value for CommandLineProcessor::parse(). Note: These enums are all given non-negative values since they are designed to be returned from main(). More...

Miscellaneous
enum	EOptType { OPT_NONE , OPT_BOOL_TRUE , OPT_BOOL_FALSE , OPT_INT , OPT_LONG_INT , OPT_SIZE_T , OPT_LONG_LONG_INT , OPT_DOUBLE , OPT_FLOAT , OPT_STRING , OPT_ENUM_INT }
typedef Teuchos::map< std::string, opt_val_val_t >	options_list_t
typedef std::vector< opt_doc_t >	options_documentation_list_t
typedef std::vector< enum_opt_data_t >	enum_opt_data_list_t
bool	throwExceptions_
bool	recogniseAllOptions_
bool	addOutputSetupOptions_
std::string	doc_string_
options_list_t	options_list_
options_documentation_list_t	options_documentation_list_
enum_opt_data_list_t	enum_opt_data_list_
bool	output_all_front_matter_
bool	output_show_line_prefix_
bool	output_show_tab_count_
bool	output_show_proc_rank_
int	output_to_root_rank_only_
bool	print_rcpnode_statistics_on_exit_
bool	show_timer_summary_on_exit_
bool	printed_timer_summary_
bool	added_extra_output_setup_options_
bool	in_add_extra_output_setup_options_
static const bool	output_all_front_matter_default_
static const bool	output_show_line_prefix_default_
static const bool	output_show_tab_count_default_
static const bool	output_show_proc_rank_default_
static const int	output_to_root_rank_only_default_
static const bool	print_rcpnode_statistics_on_exit_default_
static const bool	show_timer_summary_on_exit_default_
void	printHelpMessage (const char program_name[], std::ostream &out) const
	Print the help message.
void	printFinalTimerSummary (const Ptr< std::ostream > &out=null)
	Call to print timers so that they don't get printed in the destructor.
void	add_extra_output_setup_options () const
void	setEnumOption (const char enum_option_name[], int enum_option_val, const int num_enum_opt_values, const int enum_opt_values[], const char const enum_opt_names[], const char documentation[], const bool required)
bool	set_enum_value (int argv_i, char argv[], const std::string &enum_opt_name, const int enum_id, const std::string &enum_str_val, std::ostream errout) const
void	print_enum_opt_names (const int enum_id, std::ostream &out) const
std::string	enum_opt_default_val_name (const std::string &enum_name, const int enum_id, std::ostream *errout) const
int	find_enum_opt_index (const std::string &enum_opt_name, const int opt_value, const enum_opt_data_t &enum_data, std::ostream *errout) const
bool	get_opt_val (const char str[], std::string opt_name, std::string opt_val_str) const
std::string	opt_type_str (EOptType) const
void	print_bad_opt (int argv_i, char argv[], std::ostream errout) const
static void	setTimeMonitorSurrogate (const RCP< TimeMonitorSurrogate > &timeMonitorSurrogate)
static RCP< TimeMonitorSurrogate >	getTimeMonitorSurrogate ()
static RCP< TimeMonitorSurrogate > &	getRawTimeMonitorSurrogate ()

Constructors
	CommandLineProcessor (bool throwExceptions=true, bool recogniseAllOptions=true, bool addOutputSetupOptions=false)
	Default Constructor.
	~CommandLineProcessor ()
	Destructor.

Behavior modes
void	throwExceptions (const bool &throwExceptions)
	Set if an std::exception is thrown, there is a parse error, or help is printed.
bool	throwExceptions () const
	Returns true if an std::exception is thrown, there is a parse error, or help is printed.
void	recogniseAllOptions (const bool &recogniseAllOptions)
	Set if all options must be recognized or not.
bool	recogniseAllOptions () const
	Returns true if all options must be recognized by the parser.
void	addOutputSetupOptions (const bool &addOutputSetupOptions)
	Set if options will be automatically added to setup Teuchos::VerboseObjectBase::getDefaultOStream().
bool	addOutputSetupOptions () const
	Returns true options will be automatically added to setup Teuchos::VerboseObjectBase::getDefaultOStream().

Set up options
void	setDocString (const char doc_string[])
	Set a documentation sting for the entire program printed when –help is specified.
void	setOption (const char option_true[], const char option_false[], bool *option_val, const char documentation[]=NULL)
	Set a boolean option.
void	setOption (const char option_name[], int *option_val, const char documentation[]=NULL, const bool required=false)
	Set an integer option.
void	setOption (const char option_name[], long int *option_val, const char documentation[]=NULL, const bool required=false)
	Set a long integer option.
void	setOption (const char option_name[], size_t *option_val, const char documentation[]=NULL, const bool required=false)
	Set a size_t option.
void	setOption (const char option_name[], long long int *option_val, const char documentation[]=NULL, const bool required=false)
	Set a long long integer option.
void	setOption (const char option_name[], double *option_val, const char documentation[]=NULL, const bool required=false)
	Set a floating-point option.
void	setOption (const char option_name[], float *option_val, const char documentation[]=NULL, const bool required=false)
	Set a floating-point option.
void	setOption (const char option_name[], std::string *option_val, const char documentation[]=NULL, const bool required=false)
	Set a std::string option.
template<class EType>
void	setOption (const char enum_option_name[], EType enum_option_val, const int num_enum_opt_values, const EType enum_opt_values[], const char const enum_opt_names[], const char documentation[]=nullptr, const bool required=false)
	Set an enumeration option (templated by enumeration type).

Parse
EParseCommandLineReturn	parse (int argc, char argv[], std::ostream errout=&std::cerr) const
	Parse a command line.

Detailed Description

Class that helps parse command line input arguments from (argc,argv[]) and set options.

This class will process command-line arguments in the form of (argc,argv[]) and set user-defined options. This class can also work in a number of modes. This processor can require that all options be recognized or not.

This class object will also setup the behavior of Teuchos::VerboseObjectBase::getDefaultOStream() if this->addOutputSetupOptions()==true

Warning, the option –show-timer-summary is only enabled if the subpackage TeuchosComm is enabled!

Definition at line 76 of file Teuchos_CommandLineProcessor.hpp.

Member Typedef Documentation

◆ options_list_t

typedef Teuchos::map<std::string,opt_val_val_t> Teuchos::CommandLineProcessor::options_list_t

private

Definition at line 474 of file Teuchos_CommandLineProcessor.hpp.

◆ options_documentation_list_t

typedef std::vector<opt_doc_t> Teuchos::CommandLineProcessor::options_documentation_list_t

private

Definition at line 494 of file Teuchos_CommandLineProcessor.hpp.

◆ enum_opt_data_list_t

typedef std::vector<enum_opt_data_t> Teuchos::CommandLineProcessor::enum_opt_data_list_t

private

Definition at line 521 of file Teuchos_CommandLineProcessor.hpp.

Member Enumeration Documentation

◆ EParseCommandLineReturn

enum Teuchos::CommandLineProcessor::EParseCommandLineReturn

Return value for CommandLineProcessor::parse(). Note: These enums are all given non-negative values since they are designed to be returned from main().

Enumerator
PARSE_SUCCESSFUL	Parsing the command line was successful.
PARSE_HELP_PRINTED	The help statement was printed for the command line parser.
PARSE_UNRECOGNIZED_OPTION	The command line parser encountered an unrecognized option.
PARSE_ERROR	The command line parser encountered an error.

Definition at line 98 of file Teuchos_CommandLineProcessor.hpp.

◆ EOptType

enum Teuchos::CommandLineProcessor::EOptType

Enumerator
OPT_NONE
OPT_BOOL_TRUE
OPT_BOOL_FALSE
OPT_INT
OPT_LONG_INT
OPT_SIZE_T
OPT_LONG_LONG_INT
OPT_DOUBLE
OPT_FLOAT
OPT_STRING
OPT_ENUM_INT

Definition at line 439 of file Teuchos_CommandLineProcessor.hpp.

Constructor & Destructor Documentation

◆ CommandLineProcessor()

Teuchos::CommandLineProcessor::CommandLineProcessor	(	bool	throwExceptions = true,
		bool	recogniseAllOptions = true,
		bool	addOutputSetupOptions = false )

Default Constructor.

Parameters

throwExceptions	[in] If true then this->parse() will throw exceptions instead of returning !=PARSE_SUCCESSFUL.
recogniseAllOptions	[in] If true then this->parse() will return the appropriate error for any option it does not recognize. If false, then this->parse() will simply ignore options that it does not recognize. However, a warning will be printed for any unrecognized option, but no errors will be returned.
addOutputSetupOptions	[in] If true then options will be automatically added to setup Teuchos::VerboseObjectBase::getDefaultOStream().

Definition at line 94 of file Teuchos_CommandLineProcessor.cpp.

◆ ~CommandLineProcessor()

Teuchos::CommandLineProcessor::~CommandLineProcessor ( )

Destructor.

Definition at line 115 of file Teuchos_CommandLineProcessor.cpp.

Member Function Documentation

◆ throwExceptions() [1/2]

void Teuchos::CommandLineProcessor::throwExceptions ( const bool & throwExceptions )

inline

Set if an std::exception is thrown, there is a parse error, or help is printed.

Definition at line 693 of file Teuchos_CommandLineProcessor.hpp.

◆ throwExceptions() [2/2]

bool Teuchos::CommandLineProcessor::throwExceptions ( ) const

inline

Returns true if an std::exception is thrown, there is a parse error, or help is printed.

Definition at line 698 of file Teuchos_CommandLineProcessor.hpp.

◆ recogniseAllOptions() [1/2]

void Teuchos::CommandLineProcessor::recogniseAllOptions ( const bool & recogniseAllOptions )

inline

Set if all options must be recognized or not.

Definition at line 703 of file Teuchos_CommandLineProcessor.hpp.

◆ recogniseAllOptions() [2/2]

bool Teuchos::CommandLineProcessor::recogniseAllOptions ( ) const

inline

Returns true if all options must be recognized by the parser.

Definition at line 708 of file Teuchos_CommandLineProcessor.hpp.

◆ addOutputSetupOptions() [1/2]

void Teuchos::CommandLineProcessor::addOutputSetupOptions ( const bool & addOutputSetupOptions )

inline

Set if options will be automatically added to setup Teuchos::VerboseObjectBase::getDefaultOStream().

Definition at line 713 of file Teuchos_CommandLineProcessor.hpp.

◆ addOutputSetupOptions() [2/2]

bool Teuchos::CommandLineProcessor::addOutputSetupOptions ( ) const

inline

Returns true options will be automatically added to setup Teuchos::VerboseObjectBase::getDefaultOStream().

Definition at line 718 of file Teuchos_CommandLineProcessor.hpp.

◆ setDocString()

void Teuchos::CommandLineProcessor::setDocString ( const char doc_string[] )

Set a documentation sting for the entire program printed when –help is specified.

Definition at line 124 of file Teuchos_CommandLineProcessor.cpp.

◆ setOption() [1/9]

void Teuchos::CommandLineProcessor::setOption	(	const char	option_true[],
		const char	option_false[],
		bool *	option_val,
		const char	documentation[] = NULL )

Set a boolean option.

Parameters

option_true	[in] (null terminated std::string) If this option is found then *option_val = true will be set.
option_false	[in] (null terminated std::string) If this option is found then *option_val = false will be set.
option_val	[in/out] On input, *option_val gives the default value of the option (used for printing in –help). On output, will be set according to (argc,argv[]).
documentation	[in] If !=NULL, then this null terminated std::string gives the documentation for the option.

Definition at line 130 of file Teuchos_CommandLineProcessor.cpp.

◆ setOption() [2/9]

void Teuchos::CommandLineProcessor::setOption	(	const char	option_name[],
		int *	option_val,
		const char	documentation[] = NULL,
		const bool	required = false )

Set an integer option.

Parameters

option_name	[in] (null terminated std::string) The name of the option (without the leading '–' or trailing '=').
option_val	[in/out] On input, *option_val gives the default value of the option (used for printing in –help). On output, will be set according to (argc,argv[]).
documentation	[in] If !=NULL, then this null terminated std::string gives the documentation for the option.

Definition at line 150 of file Teuchos_CommandLineProcessor.cpp.

◆ setOption() [3/9]

void Teuchos::CommandLineProcessor::setOption	(	const char	option_name[],
		long int *	option_val,
		const char	documentation[] = NULL,
		const bool	required = false )

Set a long integer option.

Parameters

option_name	[in] (null terminated std::string) The name of the option (without the leading '–' or trailing '=').
option_val	[in/out] On input, *option_val gives the default value of the option (used for printing in –help). On output, will be set according to (argc,argv[]).
documentation	[in] If !=NULL, then this null terminated std::string gives the documentation for the option.

Definition at line 168 of file Teuchos_CommandLineProcessor.cpp.

◆ setOption() [4/9]

void Teuchos::CommandLineProcessor::setOption	(	const char	option_name[],
		size_t *	option_val,
		const char	documentation[] = NULL,
		const bool	required = false )

Set a size_t option.

Parameters

option_name	[in] (null terminated std::string) The name of the option (without the leading '–' or trailing '=').
option_val	[in/out] On input, *option_val gives the default value of the option (used for printing in –help). On output, will be set according to (argc,argv[]).
documentation	[in] If !=NULL, then this null terminated std::string gives the documentation for the option.

Definition at line 186 of file Teuchos_CommandLineProcessor.cpp.

◆ setOption() [5/9]

void Teuchos::CommandLineProcessor::setOption	(	const char	option_name[],
		long long int *	option_val,
		const char	documentation[] = NULL,
		const bool	required = false )

Set a long long integer option.

Parameters

option_name	[in] (null terminated std::string) The name of the option (without the leading '–' or trailing '=').
option_val	[in/out] On input, *option_val gives the default value of the option (used for printing in –help). On output, will be set according to (argc,argv[]).
documentation	[in] If !=NULL, then this null terminated std::string gives the documentation for the option.

Definition at line 203 of file Teuchos_CommandLineProcessor.cpp.

◆ setOption() [6/9]

void Teuchos::CommandLineProcessor::setOption	(	const char	option_name[],
		double *	option_val,
		const char	documentation[] = NULL,
		const bool	required = false )

Set a floating-point option.

Parameters

option_name	[in] (null terminated std::string) The name of the option (without the leading '–' or trailing '=').
option_val	[in/out] On input, *option_val gives the default value of the option (used for printing in –help). On output, will be set according to (argc,argv[]).
documentation	[in] If !=NULL, then this null terminated std::string gives the documentation for the option.

Definition at line 220 of file Teuchos_CommandLineProcessor.cpp.

◆ setOption() [7/9]

void Teuchos::CommandLineProcessor::setOption	(	const char	option_name[],
		float *	option_val,
		const char	documentation[] = NULL,
		const bool	required = false )

Set a floating-point option.

Parameters

option_name	[in] (null terminated std::string) The name of the option (without the leading '–' or trailing '=').
option_val	[in/out] On input, *option_val gives the default value of the option (used for printing in –help). On output, will be set according to (argc,argv[]).
documentation	[in] If !=NULL, then this null terminated std::string gives the documentation for the option.

Definition at line 237 of file Teuchos_CommandLineProcessor.cpp.

◆ setOption() [8/9]

void Teuchos::CommandLineProcessor::setOption	(	const char	option_name[],
		std::string *	option_val,
		const char	documentation[] = NULL,
		const bool	required = false )

Set a std::string option.

Parameters

option_name	[in] (null terminated std::string) The name of the option (without the leading '–' or trailing '=').
option_val	[in/out] On input, *option_val gives the default value of the option (used for printing in –help). On output, will be set according to (argc,argv[]).
documentation	[in] If !=NULL, then this null terminated std::string gives the documentation for the option.

Definition at line 254 of file Teuchos_CommandLineProcessor.cpp.

◆ setOption() [9/9]

template<class EType>

void Teuchos::CommandLineProcessor::setOption	(	const char	enum_option_name[],
		EType *	enum_option_val,
		const int	num_enum_opt_values,
		const EType	enum_opt_values[],
		const char *const	enum_opt_names[],
		const char	documentation[] = nullptr,
		const bool	required = false )

inline

Set an enumeration option (templated by enumeration type).

Parameters

enum_option_name	[in] (null terminated std::string) The name of the option (without the leading '–' or trailing '=').
enum_option_val	[in/out] On input, enum_option_val gives the default value of the enumeration (used for printing in –help). After parse() finishes executing successfully, enum_option_val will contain the user-selected value of the enumeration.
num_enum_opt_values	[in] Gives the number of possible option values to select
enum_opt_values	[in] Array (length num_enum_opt_values) that gives the numeric values for each option. The values in this array are used to set the actual option *enum_option_val.
enum_opt_names	[in] Array (length num_enum_opt_values) that gives the char string names for each option. The strings in this function are what is used in the commandline.
documentation	[in] If !=NULL, then this array of null-terminated char string gives the documentation for the option.

Warning! Only use an enum or int for EType. Using any other type for EType could be trouble!

Definition at line 724 of file Teuchos_CommandLineProcessor.hpp.

◆ parse()

CommandLineProcessor::EParseCommandLineReturn Teuchos::CommandLineProcessor::parse	(	int	argc,
		char *	argv[],
		std::ostream *	errout = &std::cerr ) const

Parse a command line.

Parameters

argc	[in] number of entries in argv[]
argv	[in/out] array (length argc) of command line arguments. argv[0] should be the name of the program on the shell as usual.
errout	[out] If !=NULL then error and help messages are sent here. The default is set to &std::cerr.

Postconditions:

If an unrecognized option is found
- If this->recogniseAllOptions()==true
  - An error message will be printed to *errout and parsing will stop as follows:
  - If this->throwExceptions()==true
    - This method will throw an UnrecognizedOption std::exception
  - else
    - This method will return PARSE_UNRECOGNIZED_OPTION
  - endif
- else
  - A warning message will be printed to *errout and parsing will continue
- endif
else if the option –help is found
- If this->throwExceptions()==true
  - This method will throw a HelpPrinted std::exception
- else
  - This method will return PARSE_HELP_PRINTED
- endif
else
- This method will return PARSE_SUCCESSFUL
endif

Note that if the option –pause-for-debugging is present, then std::string Type 0 and press enter to continue : will be printed to standard error (std::cerr) and execution will be suspended until the user enters any non-null character(s). This option is designed to make it easier to attach a debugger, especially in a parallel MPI program. If HAVE_MPI is defined, then output/input is only performed with the process with rank 0 and then MPI calls insure that all processors wait (using MPI_Barrier(MPI_COMM_WORLD)) until the user has entered something. This allows the user to attach a debugger to one or more parallel MPI processes and set breakpoints before execution resumes. Note that the stream *errout is not used for this output/input but instead std::cerr is directly used.

If Teuchos::VerboseObjectBase::getDefaultOStream().get()!=NULL and this->addOutputSetupOptions(), then any of the default setup options for Teuchos::VerboseObjectBase::getDefaultOStream() that are set on the commandline will be set on Teuchos::VerboseObjectBase::getDefaultOStream().

Definition at line 276 of file Teuchos_CommandLineProcessor.cpp.

◆ printHelpMessage()

void Teuchos::CommandLineProcessor::printHelpMessage	(	const char	program_name[],
		std::ostream &	out ) const

Print the help message.

Parameters

out	[in/out] The stream the documentation will be printed to.

This will print a formatted set of documentation that shows what options are set, what their default values are and any user-supplied documentation about each option.

Definition at line 432 of file Teuchos_CommandLineProcessor.cpp.

◆ printFinalTimerSummary()

void Teuchos::CommandLineProcessor::printFinalTimerSummary ( const Ptr< std::ostream > & out = null )

Call to print timers so that they don't get printed in the destructor.

Calling this function after the first call has no effect.

Definition at line 601 of file Teuchos_CommandLineProcessor.cpp.

◆ add_extra_output_setup_options()

void Teuchos::CommandLineProcessor::add_extra_output_setup_options ( ) const

private

Definition at line 622 of file Teuchos_CommandLineProcessor.cpp.

◆ setEnumOption()

void Teuchos::CommandLineProcessor::setEnumOption	(	const char	enum_option_name[],
		int *	enum_option_val,
		const int	num_enum_opt_values,
		const int	enum_opt_values[],
		const char *const	enum_opt_names[],
		const char	documentation[],
		const bool	required )

private

Definition at line 681 of file Teuchos_CommandLineProcessor.cpp.

◆ set_enum_value()

bool Teuchos::CommandLineProcessor::set_enum_value	(	int	argv_i,
		char *	argv[],
		const std::string &	enum_opt_name,
		const int	enum_id,
		const std::string &	enum_str_val,
		std::ostream *	errout ) const

private

Definition at line 711 of file Teuchos_CommandLineProcessor.cpp.

◆ print_enum_opt_names()

void Teuchos::CommandLineProcessor::print_enum_opt_names	(	const int	enum_id,
		std::ostream &	out ) const

private

Definition at line 748 of file Teuchos_CommandLineProcessor.cpp.

◆ enum_opt_default_val_name()

std::string Teuchos::CommandLineProcessor::enum_opt_default_val_name	(	const std::string &	enum_name,
		const int	enum_id,
		std::ostream *	errout ) const

private

Definition at line 770 of file Teuchos_CommandLineProcessor.cpp.

◆ find_enum_opt_index()

int Teuchos::CommandLineProcessor::find_enum_opt_index	(	const std::string &	enum_opt_name,
		const int	opt_value,
		const enum_opt_data_t &	enum_data,
		std::ostream *	errout ) const

private

Definition at line 786 of file Teuchos_CommandLineProcessor.cpp.

◆ get_opt_val()

bool Teuchos::CommandLineProcessor::get_opt_val	(	const char	str[],
		std::string *	opt_name,
		std::string *	opt_val_str ) const

private

Definition at line 812 of file Teuchos_CommandLineProcessor.cpp.

◆ opt_type_str()

std::string Teuchos::CommandLineProcessor::opt_type_str ( EOptType opt_type ) const

inlineprivate

Definition at line 755 of file Teuchos_CommandLineProcessor.hpp.

◆ print_bad_opt()

void Teuchos::CommandLineProcessor::print_bad_opt	(	int	argv_i,
		char *	argv[],
		std::ostream *	errout ) const

private

Definition at line 838 of file Teuchos_CommandLineProcessor.cpp.

◆ setTimeMonitorSurrogate()

void Teuchos::CommandLineProcessor::setTimeMonitorSurrogate ( const RCP< TimeMonitorSurrogate > & timeMonitorSurrogate )

static

Definition at line 860 of file Teuchos_CommandLineProcessor.cpp.

◆ getTimeMonitorSurrogate()

RCP< CommandLineProcessor::TimeMonitorSurrogate > Teuchos::CommandLineProcessor::getTimeMonitorSurrogate ( )

static

Definition at line 868 of file Teuchos_CommandLineProcessor.cpp.

◆ getRawTimeMonitorSurrogate()

RCP< CommandLineProcessor::TimeMonitorSurrogate > & Teuchos::CommandLineProcessor::getRawTimeMonitorSurrogate ( )

staticprivate

Definition at line 875 of file Teuchos_CommandLineProcessor.cpp.

◆ setVerbosityLevelOption()

void setVerbosityLevelOption	(	const std::string &	optionName,
		EVerbosityLevel *	verbLevel,
		const std::string &	docString,
		CommandLineProcessor *	clp,
		const bool	required = false )