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 = -1 }

Return value for CommandLineProcessor::parse(). 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 exception is thrown, there is a parse error, or help is printed.

bool throwExceptions () const

Returns true if an 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 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.

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, FancyOutputting_test.cpp, and test/RefCountPtr/cxx_main.cpp.

Definition at line 63 of file Teuchos_CommandLineProcessor.hpp.

Member Enumeration Documentation

enum Teuchos::CommandLineProcessor::EParseCommandLineReturn

Return value for CommandLineProcessor::parse().

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.

Definition at line 84 of file Teuchos_CommandLineProcessor.hpp.

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

Definition at line 65 of file Teuchos_CommandLineProcessor.cpp.

Member Function Documentation

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

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

Examples:
CommandLineProcessor/cxx_main.cpp.

Definition at line 522 of file Teuchos_CommandLineProcessor.hpp.

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

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

Definition at line 526 of file Teuchos_CommandLineProcessor.hpp.

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

Set if all options must be recognized or not.

Examples:
CommandLineProcessor/cxx_main.cpp.

Definition at line 530 of file Teuchos_CommandLineProcessor.hpp.

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

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

Definition at line 534 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 538 of file Teuchos_CommandLineProcessor.hpp.

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

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

Definition at line 542 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.

Examples:
CommandLineProcessor/cxx_main.cpp.

Definition at line 84 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.

Parameters:

option_true [in] (null terminated string) If this option is found then *option_val = true will be set.

option_false [in] (null terminated 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 string gives the documentation for the option.

Examples:
CommandLineProcessor/cxx_main.cpp.

Definition at line 89 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.

Parameters:

option_name [in] (null terminated 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 string gives the documentation for the option.

Definition at line 106 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.

Parameters:

option_name [in] (null terminated 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 string gives the documentation for the option.

Definition at line 121 of file Teuchos_CommandLineProcessor.cpp.

void Teuchos::CommandLineProcessor::setOption ( const char option_name[],

std::string * option_val,

const char documentation[] = NULL,

const bool required = false

)

Set a string option.

Parameters:

option_name [in] (null terminated 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 string gives the documentation for the option.

Definition at line 136 of file Teuchos_CommandLineProcessor.cpp.

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 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 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 string gives the documentation for the option.

Warning! Only use enumeration or int for EType. Using any other type for EType could be trouble!
Definition at line 547 of file Teuchos_CommandLineProcessor.hpp.

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

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.

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.

Definition at line 275 of file Teuchos_CommandLineProcessor.cpp.

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

Generated on Thu Sep 18 12:30: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 = -1 }
	Return value for `CommandLineProcessor::parse()`. 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 exception is thrown, there is a parse error, or help is printed.
bool	throwExceptions () const
	Returns true if an 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 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.