Teuchos::CommandLineProcessor Class Reference

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

#include <Teuchos_CommandLineProcessor.hpp>

Collaboration diagram for Teuchos::CommandLineProcessor:

[legend]
List of all members.

Public Types

enum  EParseCommandLineReturn { PARSE_SUCCESSFUL = 0, PARSE_HELP_PRINTED = 1, PARSE_UNRECOGNIZED_OPTION = -1 }
 Return value for CommandLineProcessor::parse(). More...
enum  EOptType {
  OPT_NONE, OPT_BOOL_TRUE, OPT_BOOL_FALSE, OPT_INT,
  OPT_DOUBLE, OPT_STRING, OPT_ENUM_INT
}

Public Member Functions

Constructors
 CommandLineProcessor (bool throwExceptions=true, bool recogniseAllOptions=true)
 Default Constructor.
Set up options
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)
 Set an integer option.
void setOption (const char option_name[], double *option_val, const char documentation[]=NULL)
 Set a floating-point option.
void setOption (const char option_name[], std::string *option_val, const char documentation[]=NULL)
 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)
 Set an enumeration option (templated by enumeration type).
Parse methods
EParseCommandLineReturn parse (int argc, char *argv[], std::ostream *errout=&std::cerr) const
 Parse a command line.
Miscellaneous method
void printHelpMessage (const char program_name[], std::ostream &out) const
 Print the help message.
Behavior modes
void throwExceptions (const bool &throwExceptions)
 Set if an exception is thrown, there is a parse error, or help is printed.
const bool & throwExceptions () const
 Return 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.
const bool & recogniseAllOptions () const
 Return true if all options are being recognized by the parser.

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_tenum_opt_data_list_t

Private Member Functions

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[])
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_
options_list_t options_list_
options_documentation_list_t options_documentation_list_
enum_opt_data_list_t enum_opt_data_list_

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.

Examples:

CommandLineProcessor/cxx_main.cpp.

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

typedef std::vector<opt_doc_t> Teuchos::CommandLineProcessor::options_documentation_list_t [private]
 

Definition at line 368 of file Teuchos_CommandLineProcessor.hpp.

typedef std::vector<enum_opt_data_t> Teuchos::CommandLineProcessor::enum_opt_data_list_t [private]
 

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

enum Teuchos::CommandLineProcessor::EOptType
 

Enumeration values:
OPT_NONE 
OPT_BOOL_TRUE 
OPT_BOOL_FALSE 
OPT_INT 
OPT_DOUBLE 
OPT_STRING 
OPT_ENUM_INT 

Definition at line 320 of file Teuchos_CommandLineProcessor.hpp.


Constructor & Destructor Documentation

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

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.

Definition at line 61 of file Teuchos_CommandLineProcessor.cpp.


Member Function Documentation

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

void Teuchos::CommandLineProcessor::setOption const char  option_name[],
int *  option_val,
const char  documentation[] = NULL
 

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

void Teuchos::CommandLineProcessor::setOption const char  option_name[],
double *  option_val,
const char  documentation[] = NULL
 

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

void Teuchos::CommandLineProcessor::setOption const char  option_name[],
std::string *  option_val,
const char  documentation[] = NULL
 

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 113 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
[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 475 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
  • 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.

Examples:
CommandLineProcessor/cxx_main.cpp.

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

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 289 of file Teuchos_CommandLineProcessor.hpp.

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

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

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

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

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

Definition at line 298 of file Teuchos_CommandLineProcessor.hpp.

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[]
[private]
 

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

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

Definition at line 411 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 427 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 442 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 467 of file Teuchos_CommandLineProcessor.cpp.

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

Definition at line 504 of file Teuchos_CommandLineProcessor.hpp.

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

Definition at line 493 of file Teuchos_CommandLineProcessor.cpp.


Member Data Documentation

bool Teuchos::CommandLineProcessor::throwExceptions_ [private]
 

Definition at line 400 of file Teuchos_CommandLineProcessor.hpp.

bool Teuchos::CommandLineProcessor::recogniseAllOptions_ [private]
 

Definition at line 401 of file Teuchos_CommandLineProcessor.hpp.

options_list_t Teuchos::CommandLineProcessor::options_list_ [private]
 

Definition at line 402 of file Teuchos_CommandLineProcessor.hpp.

options_documentation_list_t Teuchos::CommandLineProcessor::options_documentation_list_ [private]
 

Definition at line 403 of file Teuchos_CommandLineProcessor.hpp.

enum_opt_data_list_t Teuchos::CommandLineProcessor::enum_opt_data_list_ [private]
 

Definition at line 404 of file Teuchos_CommandLineProcessor.hpp.


The documentation for this class was generated from the following files:
Generated on Thu Sep 18 12:41:20 2008 for Teuchos - Trilinos Tools Package by doxygen 1.3.9.1