Teuchos::CommandLineProcessor Class Reference

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

#include <Teuchos_CommandLineProcessor.hpp>

List of all members.

Public Types

Public types

enum EParseCommandLineReturn { PARSE_SUCCESSFUL = 0, PARSE_HELP_PRINTED = 1, PARSE_UNRECOGNIZED_OPTION = 2 }

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

Public Member Functions

Constructors

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

Default Constructor.

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 are being 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[], double *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 *enum_opt_names[], const char documentation[]=NULL, 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.

Miscellaneous

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

Print the help message.

Related Functions

(Note that these are not member functions.)

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..

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

Examples:: CommandLineProcessor/cxx_main.cpp, and FancyOutputting_test.cpp.

Member Enumeration Documentation

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().

Enumeration values:

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.

Constructor & Destructor Documentation

Teuchos::CommandLineProcessor::CommandLineProcessor ( bool throwExceptions = true,

bool recogniseAllOptions = true,

bool addOutputSetupOptions = false

)

Default Constructor.

Parameters:

throwExceptions [in] If true then this->parse() with throw exceptions instead of returning !=PARSE_SUCCESSFUL.

recogniseAllOptions [in] If true then this->parse() with simply ignore options that it does not recognize.

addOutputSetupOptions [in] If true then options will be automatically added to setup Teuchos::VerboseObjectBase::getDefaultOStream().

Member Function Documentation

void Teuchos::CommandLineProcessor::throwExceptions ( const bool & throwExceptions ) [inline]

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

Examples:
CommandLineProcessor/cxx_main.cpp.

bool Teuchos::CommandLineProcessor::throwExceptions ( ) const [inline]

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

void Teuchos::CommandLineProcessor::recogniseAllOptions ( const bool & recogniseAllOptions ) [inline]

Set if all options must be recognized or not.

Examples:
CommandLineProcessor/cxx_main.cpp.

bool Teuchos::CommandLineProcessor::recogniseAllOptions ( ) const [inline]

Returns true if all options are being recognized by the parser.

void Teuchos::CommandLineProcessor::addOutputSetupOptions ( const bool & addOutputSetupOptions ) [inline]

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

bool Teuchos::CommandLineProcessor::addOutputSetupOptions ( ) const [inline]

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

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

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

Examples:
CommandLineProcessor/cxx_main.cpp.

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.

Examples:
CommandLineProcessor/cxx_main.cpp.

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.

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.

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.

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 * enum_opt_names[],

const char documentation[] = NULL,

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 give the default value of the enumeration (used for printing in --help). After parse() finished 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 std::string names for each option. The strings in this function are what is used in the commandline.

documentation [in] If !=NULL, then this null terminated std::string gives the documentation for the option.

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

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().
Examples:
CommandLineProcessor/cxx_main.cpp.

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.
Examples:
CommandLineProcessor/cxx_main.cpp.

Friends And Related Function Documentation

void setVerbosityLevelOption ( const std::string & optionName,

EVerbosityLevel * verbLevel,

const std::string & docString,

CommandLineProcessor * clp,

const bool required = false

) [related]

Set a verbosity level parameter on a CommandLineProcessor object..

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

Teuchos_CommandLineProcessor.hpp
Teuchos_CommandLineProcessor.cpp
Teuchos_VerbosityLevelCommandLineProcessorHelpers.hpp

Generated on Sun Nov 23 12:11:32 2008 for Teuchos - Trilinos Tools Package by

1.3.9.1


Public Types
Public types
enum	EParseCommandLineReturn { PARSE_SUCCESSFUL = 0, PARSE_HELP_PRINTED = 1, PARSE_UNRECOGNIZED_OPTION = 2 }
	Return value for `CommandLineProcessor::parse()`. Note: These enums are all given non-negative values since they are designed to be returned from main(). More...
Public Member Functions
Constructors
	CommandLineProcessor (bool throwExceptions=true, bool recogniseAllOptions=true, bool addOutputSetupOptions=false)
	Default Constructor.
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 are being 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[], double *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 enum_opt_names[], const char documentation[]=NULL, 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.
Miscellaneous
void	printHelpMessage (const char program_name[], std::ostream &out) const
	Print the help message.
Related Functions
(Note that these are not member functions.)
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..