ProgOptions.hpp

Go to the documentation of this file.

#ifndef MOAB_PROGRAM_OPTIONS_H
#define MOAB_PROGRAM_OPTIONS_H
 
#include <vector>
#include <map>
#include <string>
#include <iostream>
 
class ProgOpt;
 
/** A simple command-line option parser and help utility
 *
 * Utility class to specify a program's command-line options arguments, produce a help message
 * explaining how they work, and parse user's command line input (producing useful errors messages
 * if any problems arise). Loosely (okay, very loosely) inspired by boost program_options.
 *
 * Options are specified by a comma-separated namestring. An option named "foo,f" can be specified
 * three ways on the command line: "-f val", "--foo val", or "--foo=val". The types of options
 * and arguments are specified by function templates. Valid template values for positional argument
 * and options are int, double, and std::string. void may also be used in options, and it indicates
 * a command line option that does not take an argument.
 *
 * Example usage:
 * ProgOptions po( "Example usage of ProgOptions" );
 * po.addOpt<void>( "verbose,v", "Turn on verbose messages" );
 * po.addOpt<std::string> ("foo", "Specify the foo string" );
 * int x = 0;
 * po.addOpt<int>( ",x", "Specify the x number", &x ); // x will be automatically set when options
 * parsed po.parseCommandLine( argc, argv ); bool verbose = po.numOptSet("verbose") > 0; std::string
 * foo; if( !po.getOpt( "foo", &foo ) ) foo = "default";
 * ...
 *
 * See the file dagmc_preproc.cpp in the dagmc directory for a real-world example.
 */
class ProgOptions
{
 
 public:
 /**
 * Flags for addOpt and addRequiredArg functions; may be combined with bitwise arithmetic
 * (though not all combinations make sense!)
 **/
 
 /// Set for a flag that, when detected, prints help text and halts program.
 /// Constructor creates such a flag by default, so the user shouldn't need to use this directly.
 static const int help_flag = 1 << 0;
 
 /// Flag indicating that an option should be given a "cancel" flag.
 /// This creates, for option --foo, an additional option --no-foo that
 /// clears all previously read instances of the foo option
 static const int add_cancel_opt = 1 << 1;
 
 /// When applied to a flag argument (one with template type void), indicate that the
 /// value 'false' should be stored into the pointer that was given at option creation time.
 /// This overrides the default behavior, which is to store the value 'true'.
 static const int store_false = 1 << 2;
 
 /// Specify a numerical flag where any positive integer is an acceptable
 /// value. E.g. --dimension=3 is equivalent to -3. Only values in the
 /// range [0,9] are accepted and the flag type must be integer.
 static const int int_flag = 1 << 3;
 
 /** Substitue any occurance of the '%' symbol in a string with
 * the the MPI rank of this process in MPI_COMM_WORLD. This
 * option has no effect if not compiled with MPI. This flag
 * has no effect for non-string options.
 */
 static const int rank_subst = 1 << 4;
 
 /// Set for a flag that, when detected, will call printVersion() and halt the program.
 static const int version_flag = 1 << 5;
 
 /// unimplemented flag for required arguments that may be given multiple times
 // const static int accept_multiple;
 
 /**
 * @param helptext A brief summary of the program's function, to be printed
 * when the help flag is detected
 */
 ProgOptions( const std::string& helptext = "", const std::string& briefdesc = "" );
 ~ProgOptions();
 
 /** Specify the program version
 *
 * Set the program version to a given string. This will be printed when printVersion()
 * is called.
 * @param version_string The version string
 * @param addflag If true, a default '--version' option will be added. If false,
 * the version will be set, but no option will be added to the parser.
 */
 void setVersion( const std::string& version_string, bool addFlag = true );
 
 /** Specify a new command-line option
 *
 * Instruct the parser to accept a new command-line argument, as well as specifying
 * how the argument should be handled. The template parameter indicates the type of
 * command-line option being specified: acceptable types are void (indicating a flag
 * without an argument), int, double, and std::string.
 *
 * @param namestring The command-line options name(s). Format is longname,shortname.
 * If the comma is omitted, or appears only at the end, this option will have
 * no shortname; if the comma is the first letter of the namestring, the option
 * has no longname.
 * @param helpstring The help information displayed for the option when the program is
 * invoked with --help
 * @param value A pointer to memory in which to store the parsed value for this option.
 * If NULL, then the value of the option must be queried using the getOpt function.
 * If the template parameter is void and value is non-NULL, treat value as a bool*
 * and store 'true' into it when the flag is encountered. (See also store_false, above)
 * @param flags Option behavior flags, which should come from static vars in the ProgOptions
 * class
 */
 template < typename T >
 void addOpt( const std::string& namestring, const std::string& helpstring, T* value, int flags = 0 );
 
 /** Specify a new command-line option
 *
 * This funtion is identical to the 4-arg version, but omits the value parameter, which
 * is assumed to be NULL
 */
 template < typename T >
 void addOpt( const std::string& namestring, const std::string& helpstring, int flags = 0 )
 {
 addOpt< T >( namestring, helpstring, NULL, flags );
 }
 
 /** Add a new line of help text to the option help printout
 *
 * Add a line of text to the option-related help. Called between calls to addOpt(),
 * this function can be used to divide the option list into groups of related options
 * to make the help text more convenient.
 */
 void addOptionHelpHeading( const std::string& );
 
 /** Add required positional argument
 *
 * Add a new required positional argument. The order in which arguments are specified
 * is the order in which they will be expected on the command line.
 * The template parameter may be int, double, or std::string (but not void)
 * @param helpname The name to give the argument in the help text
 * @param helpstring The help text for the argument
 * @param value Pointer to where parsed value from command line should be stored.
 * If NULL, the value must be queried using getReqArg()
 */
 template < typename T >
 void addRequiredArg( const std::string& helpname, const std::string& helpstring, T* value = NULL, int flags = 0 );
 
 /** Add optional positional arguments
 *
 * Specify location in ordered argument list at which optional arguments
 * may occur. Optional arguments are allowed at only one location
 * it argument list (this function may not be called more than once.).
 * The template parameter may be int, double, or std::string (but not void)
 * @param count The maximum number of optional arguments. Specify zero for unlimited.
 * @param helpname The name to give the argument in the help text
 * @param helpstring The help text for the arguments
 */
 template < typename T >
 void addOptionalArgs( unsigned max_count,
 const std::string& helpname,
 const std::string& helpstring,
 int flags = 0 );
 
 /**
 * Print the full help to the given stream
 */
 void printHelp( std::ostream& str = std::cout );
 
 /**
 * Print only the usage message to the given stream
 */
 void printUsage( std::ostream& str = std::cout );
 
 /**
 * Print the version string to the given stream
 */
 void printVersion( std::ostream& str = std::cout );
 
 /**
 * Parse command-line inputs as given to main()
 */
 void parseCommandLine( int argc, char* argv[] );
 
 /**
 *
 * Get the value of the named option.
 * @param namestring The name string given when the option was created. This need not be
 * idential to the created name; only the longname, or the shortname (with comma prefix),
 * will also work.
 * @param value Pointer to location to store option argument, if any is found
 * @return True if the option was set and its argument was stored into value; false otherwise.
 */
 template < typename T >
 bool getOpt( const std::string& namestring, T* value );
 
 /**
 * Get a list of values for the named option-- one value for each time it was
 * given on the command line.
 *
 * This function cannot be called with void as the template parameter;
 * compilers will reject vector<void> as a type. This means it cannot be
 * called for flag-type options. To count the number of times a given flag
 * was specified, use numOptSet()
 * @param namestring See similar argument to getOpt()
 * @param values Reference to list to store values into. Will have as many entries
 * as there were instances of this option on the command line
 */
 template < typename T >
 void getOptAllArgs( const std::string& namestring, std::vector< T >& values );
 
 /**
 * @param namestring See similar argument to getOpt()
 * @return The number of times the named option appeared on the command line.
 */
 int numOptSet( const std::string& namestring );
 
 /**
 * Retrieve the value of a required command-line argument by name
 * @param namestring The helpname that was given to addRequiredArg when the
 * desired argument was created
 */
 template < typename T >
 T getReqArg( const std::string& namestring );
 
 /**
 * Append the values of any required or optional arguments
 * @param namestring The helpname that was given to addRequiredArg or
 * addOptionalArgs.
 */
 template < typename T >
 void getArgs( const std::string& namestring, std::vector< T >& values );
 
 /**
 * Prints an error message to std::cerr, along with a brief usage message,
 * then halts the program. Used throughout ProgramOptions implementation.
 * Users may call this directly if they detect an incorrect usage of program
 * options that the ProgramOptions wasn't able to detect itself.
 * @param message The error message to print before program halt.
 */
 void error( const std::string& message );
 
 /**
 * Write help data formatted for use as a unix man page.
 */
 void write_man_page( std::ostream& to_this_stream );
 
 protected:
 std::string get_option_usage_prefix( const ProgOpt& option );
 
 void get_namestrings( const std::string& input, std::string* l, std::string* s );
 
 ProgOpt* lookup( const std::map< std::string, ProgOpt* >&, const std::string& );
 ProgOpt* lookup_option( const std::string& );
 
 bool evaluate( const ProgOpt& opt, void* target, const std::string& option, unsigned* arg_idx = NULL );
 bool process_option( ProgOpt* opt, std::string arg, const char* value = 0 );
 
 std::map< std::string, ProgOpt* > long_names;
 std::map< std::string, ProgOpt* > short_names;
 std::map< std::string, ProgOpt* > required_args;
 
 typedef std::pair< ProgOpt*, std::string > help_line;
 std::vector< help_line > option_help_strings;
 std::vector< help_line > arg_help_strings;
 std::vector< std::string > main_help;
 std::string brief_help;
 
 bool expect_optional_args;
 unsigned optional_args_position, max_optional_args;
 
 std::string progname;
 std::string progversion;
 
 // if an option was specified with the int_flag, this
 // will contain the long name of the option
 std::string number_option_name;
};
 
#endif /* MOAB_PROGRAM_OPTIONS_H */