ProgOptions.hpp

#ifndef MOAB_PROGRAM_OPTIONS_H
#define MOAB_PROGRAM_OPTIONS_H

/* THIS FILE WAS COPIED FROM THE MOAB LIBRARY */

#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;

  /// When applied to a flag argument (one with template type void), indicate that the 
  /// value 'true' should be stored into the pointer that was given at option creation time.
  static const int store_true = 1<<6 ;
  
  ///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 */