Teuchos Package Browser (Single Doxygen Collection) Version of the Day
Classes | Public Types | Private Types | Private Member Functions | Private Attributes | Static Private Attributes | Related Functions
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.

Classes

struct  enum_opt_data_t
class  HelpPrinted
 Thrown if --help was specified and throwExceptions==true. More...
struct  opt_doc_t
struct  opt_val_val_t
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
}

Private Types

typedef Teuchos::map
< std::string, opt_val_val_t
options_list_t
typedef std::vector< opt_doc_toptions_documentation_list_t
typedef std::vector
< enum_opt_data_t
enum_opt_data_list_t

Private Member Functions

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

Private Attributes

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 added_extra_output_setup_options_
bool in_add_extra_output_setup_options_

Static Private Attributes

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_

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

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

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

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

Definition at line 72 of file Teuchos_CommandLineProcessor.hpp.


Member Typedef Documentation

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

Definition at line 383 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 403 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 430 of file Teuchos_CommandLineProcessor.hpp.


Member Enumeration Documentation

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.

Definition at line 94 of file Teuchos_CommandLineProcessor.hpp.

Enumerator:
OPT_NONE 
OPT_BOOL_TRUE 
OPT_BOOL_FALSE 
OPT_INT 
OPT_DOUBLE 
OPT_STRING 
OPT_ENUM_INT 

Definition at line 353 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 79 of file Teuchos_CommandLineProcessor.cpp.


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.

Definition at line 543 of file Teuchos_CommandLineProcessor.hpp.

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 547 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 551 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 555 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 559 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 563 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 99 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 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 104 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 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 123 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 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 140 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 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 157 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 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!

Definition at line 568 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
      • 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
    • 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 177 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.

Definition at line 302 of file Teuchos_CommandLineProcessor.cpp.

void Teuchos::CommandLineProcessor::add_extra_output_setup_options ( ) const [private]

Definition at line 456 of file Teuchos_CommandLineProcessor.cpp.

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 *  enum_opt_names[],
const char  documentation[],
const bool  required 
) [private]

Definition at line 507 of file Teuchos_CommandLineProcessor.cpp.

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 536 of file Teuchos_CommandLineProcessor.cpp.

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

Definition at line 572 of file Teuchos_CommandLineProcessor.cpp.

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 593 of file Teuchos_CommandLineProcessor.cpp.

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 608 of file Teuchos_CommandLineProcessor.cpp.

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

Definition at line 633 of file Teuchos_CommandLineProcessor.cpp.

std::string Teuchos::CommandLineProcessor::opt_type_str ( EOptType  opt_type) const [inline, private]

Definition at line 599 of file Teuchos_CommandLineProcessor.hpp.

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

Definition at line 659 of file Teuchos_CommandLineProcessor.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..


Member Data Documentation

Definition at line 435 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 436 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 437 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 438 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 445 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 446 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 447 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 452 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 453 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 454 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 455 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 456 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 457 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 459 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 460 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 462 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 463 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 464 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 465 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 466 of file Teuchos_CommandLineProcessor.hpp.

Definition at line 467 of file Teuchos_CommandLineProcessor.hpp.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines