(argc,argv[])
and set options.
More...
#include <Teuchos_CommandLineProcessor.hpp>
Classes | |
class | HelpPrinted |
Thrown if --help was specified and throwExceptions==true. More... | |
class | ParseError |
Thrown if a parse std::exception occurs and throwExceptions==true. More... | |
class | UnrecognizedOption |
Thrown if an unrecognized option was found and throwExceptions==true. More... | |
Public Types | |
enum | EOptType { OPT_NONE, OPT_BOOL_TRUE, OPT_BOOL_FALSE, OPT_INT, OPT_DOUBLE, OPT_STRING, OPT_ENUM_INT } |
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.. |
(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
CommandLineProcessor/cxx_main.cpp, and FancyOutputting_test.cpp.
Definition at line 63 of file Teuchos_CommandLineProcessor.hpp.
Definition at line 344 of file Teuchos_CommandLineProcessor.hpp.
Return value for CommandLineProcessor::parse()
. Note: These enums are all given non-negative values since they are designed to be returned from main().
Definition at line 85 of file Teuchos_CommandLineProcessor.hpp.
Teuchos::CommandLineProcessor::CommandLineProcessor | ( | bool | throwExceptions = true , |
|
bool | recogniseAllOptions = true , |
|||
bool | addOutputSetupOptions = false | |||
) |
Default Constructor.
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() . |
Definition at line 65 of file Teuchos_CommandLineProcessor.cpp.
bool Teuchos::CommandLineProcessor::addOutputSetupOptions | ( | ) | const [inline] |
Returns true options will be automatically added to setup Teuchos::VerboseObjectBase::getDefaultOStream()
.
Definition at line 543 of file Teuchos_CommandLineProcessor.hpp.
void Teuchos::CommandLineProcessor::addOutputSetupOptions | ( | const bool & | addOutputSetupOptions | ) | [inline] |
Set if options will be automatically added to setup Teuchos::VerboseObjectBase::getDefaultOStream()
.
Definition at line 539 of file Teuchos_CommandLineProcessor.hpp.
CommandLineProcessor::EParseCommandLineReturn Teuchos::CommandLineProcessor::parse | ( | int | argc, | |
char * | argv[], | |||
std::ostream * | errout = &std::cerr | |||
) | const |
Parse a command line.
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 . |
this->recogniseAllOptions()==true
*errout
and parsing will stop as follows: this->throwExceptions()==true
UnrecognizedOption
std::exceptionPARSE_UNRECOGNIZED_OPTION
*errout
and parsing will continue--help
is found this->throwExceptions()==true
HelpPrinted
std::exceptionPARSE_HELP_PRINTED
PARSE_SUCCESSFUL
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 154 of file Teuchos_CommandLineProcessor.cpp.
void Teuchos::CommandLineProcessor::printHelpMessage | ( | const char | program_name[], | |
std::ostream & | out | |||
) | const |
Print the help message.
out | [in/out] The stream the documentation will be printed to. |
Definition at line 275 of file Teuchos_CommandLineProcessor.cpp.
bool Teuchos::CommandLineProcessor::recogniseAllOptions | ( | ) | const [inline] |
Returns true if all options are being recognized by the parser.
Definition at line 535 of file Teuchos_CommandLineProcessor.hpp.
void Teuchos::CommandLineProcessor::recogniseAllOptions | ( | const bool & | recogniseAllOptions | ) | [inline] |
Set if all options must be recognized or not.
Definition at line 531 of file Teuchos_CommandLineProcessor.hpp.
void Teuchos::CommandLineProcessor::setDocString | ( | const char | doc_string[] | ) |
Set a documentation sting for the entire program printed when --help is specified.
Definition at line 84 of file Teuchos_CommandLineProcessor.cpp.
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).
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. |
int
for EType
. Using any other type for EType
could be trouble!
Definition at line 548 of file Teuchos_CommandLineProcessor.hpp.
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.
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 136 of file Teuchos_CommandLineProcessor.cpp.
void Teuchos::CommandLineProcessor::setOption | ( | const char | option_name[], | |
double * | option_val, | |||
const char | documentation[] = NULL , |
|||
const bool | required = false | |||
) |
Set a floating-point option.
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 121 of file Teuchos_CommandLineProcessor.cpp.
void Teuchos::CommandLineProcessor::setOption | ( | const char | option_name[], | |
int * | option_val, | |||
const char | documentation[] = NULL , |
|||
const bool | required = false | |||
) |
Set an integer option.
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 106 of file Teuchos_CommandLineProcessor.cpp.
void Teuchos::CommandLineProcessor::setOption | ( | const char | option_true[], | |
const char | option_false[], | |||
bool * | option_val, | |||
const char | documentation[] = NULL | |||
) |
Set a boolean option.
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 89 of file Teuchos_CommandLineProcessor.cpp.
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 527 of file Teuchos_CommandLineProcessor.hpp.
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 523 of file Teuchos_CommandLineProcessor.hpp.
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..