Teuchos_CommandLineProcessor.hpp

Go to the documentation of this file.

// @HEADER
// ***********************************************************************
// 
//                    Teuchos: Common Tools Package
//                 Copyright (2004) Sandia Corporation
// 
// Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
// license for use of this work by or on behalf of the U.S. Government.
// 
// This library is free software; you can redistribute it and/or modify
// it under the terms of the GNU Lesser General Public License as
// published by the Free Software Foundation; either version 2.1 of the
// License, or (at your option) any later version.
//  
// This library is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// Lesser General Public License for more details.
//  
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
// USA
// Questions? Contact Michael A. Heroux (maherou@sandia.gov) 
// 
// ***********************************************************************
// @HEADER

// //////////////////////////////////////////////////
// Teuchos_CommandLineProcessor.hpp

#ifndef TEUCHOS_COMMAND_LINE_PROCESSOR_HPP
#define TEUCHOS_COMMAND_LINE_PROCESSOR_HPP

#include "Teuchos_map.hpp"
#include "Teuchos_any.hpp"
#include "Teuchos_CompileTimeAssert.hpp"

namespace Teuchos {


/* ToDo: RAB: 2003/10/02: Add support for required options as per KRL's suggestion
 *
 * ToDo:  Finish documentation.
 */

class CommandLineProcessor {
public:

  enum EParseCommandLineReturn {
    PARSE_SUCCESSFUL              =  0 
    ,PARSE_HELP_PRINTED            =  1 
    ,PARSE_UNRECOGNIZED_OPTION     = -1 
  };



  CommandLineProcessor(
    bool    throwExceptions      = true
    ,bool   recogniseAllOptions  = true
    );




  void setOption(
    const char     option_true[]
    ,const char    option_false[]
    ,bool          *option_val
    ,const char    documentation[] = NULL
    );


  void setOption(
    const char     option_name[]
    ,int           *option_val
    ,const char    documentation[] = NULL
    );


  void setOption(
    const char     option_name[]
    ,double        *option_val
    ,const char    documentation[] = NULL
    );


  void setOption(
    const char     option_name[]
    ,std::string   *option_val
    ,const char    documentation[] = NULL
    );
  

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



  EParseCommandLineReturn  parse(
    int             argc
    ,char*          argv[]
    ,std::ostream   *errout    = &std::cerr
    ) const;




  void printHelpMessage( const char program_name[], std::ostream &out ) const;



  void throwExceptions ( const bool & throwExceptions ) { throwExceptions_ = throwExceptions; };
  
  const bool& throwExceptions() const { return throwExceptions_; };

  void recogniseAllOptions ( const bool & recogniseAllOptions ) { recogniseAllOptions_ = recogniseAllOptions; };

  const bool& recogniseAllOptions() const { return recogniseAllOptions_; };



  class ParseError : public std::logic_error
  {public: ParseError(const std::string& what_arg) : std::logic_error(what_arg) {}};

  class HelpPrinted : public ParseError
  {public: HelpPrinted(const std::string& what_arg) : ParseError(what_arg) {}};

  class UnrecognizedOption : public ParseError
  {public: UnrecognizedOption(const std::string& what_arg) : ParseError(what_arg) {}};


public:
  //
  enum EOptType { OPT_NONE, OPT_BOOL_TRUE, OPT_BOOL_FALSE, OPT_INT, OPT_DOUBLE, OPT_STRING, OPT_ENUM_INT };
  // RAB: 2003/10/10: Note: I had to move this out of the private section since
  // the sun compiler (version 7) complained (rightly it now appears after looking
  // up what the ISO/ANSI C++ standard says) about the declaration for opt_val_val_t
  // not being able to access a private member of CommandLineProcessor.

private:

  // /////////////////////////////////
  // Private types

  // ToDo: RAB: 2004/05/25: Clean up these data structures and add
  // support for a templated enum type.  This will clean up usage
  // quite a bit.

  //
  struct opt_val_val_t {
    opt_val_val_t()
      :opt_type(OPT_NONE)
      {}
    opt_val_val_t( EOptType opt_type_in, const any& opt_val_in )
      :opt_type(opt_type_in),opt_val(opt_val_in)
      {}
    EOptType     opt_type;
    any          opt_val; // Will be bool*, int*, double*, string* or a small int (for OPT_ENUM_INT)
  };

  //
  typedef Teuchos::map<std::string,opt_val_val_t>   options_list_t;

  //
  struct opt_doc_t {
    opt_doc_t()
      :opt_type(OPT_NONE)
      {}
    opt_doc_t(EOptType opt_type_in, const std::string& opt_name_in, const std::string& opt_name_false_in
            ,const std::string &documentation_in, const any &default_val_in )
      :opt_type(opt_type_in),opt_name(opt_name_in),opt_name_false(opt_name_false_in)
      ,documentation(documentation_in),default_val(default_val_in)
      {}
    EOptType     opt_type;
    std::string  opt_name;
    std::string  opt_name_false; // only for bool
    std::string  documentation;
    any          default_val;
  };
  
  //
  typedef std::vector<opt_doc_t>   options_documentation_list_t;

  //
  struct enum_opt_data_t {
    enum_opt_data_t()
      :enum_option_val(NULL), num_enum_opt_values(0)
      {}
    enum_opt_data_t(
      int          *_enum_option_val
      ,const int    _num_enum_opt_values
      ,const int    _enum_opt_values[]
      ,const char*  _enum_opt_names[]
      )
      :enum_option_val(_enum_option_val)
      ,num_enum_opt_values(_num_enum_opt_values)
      ,enum_opt_values(_enum_opt_values,_enum_opt_values+_num_enum_opt_values)
      {
        for( int k = 0; k < num_enum_opt_values; ++k )
          enum_opt_names.push_back(std::string(_enum_opt_names[k]));
      }
    int                  *enum_option_val;
    int                  num_enum_opt_values;
    std::vector<int>     enum_opt_values;
    std::vector<string>  enum_opt_names;
  };

  //
  typedef std::vector<enum_opt_data_t> enum_opt_data_list_t;

  // /////////////////////////////////
  // Private data members

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

  // /////////////////////////////////
  // Private member functions

  // Set an integer enumeration option
  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[]
    );

  // Set an enum int option
  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;

  // Print the valid enum values
  void print_enum_opt_names(
    const int            enum_id
    ,std::ostream        &out
    ) const;

  // Return the name of the default value for an enum
  std::string enum_opt_default_val_name(
    const std::string    &enum_name
    ,const int           enum_id
    ,std::ostream        *errout
    ) const;
  
  // Return the index given and option value
  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; 

  // Get the option and the value from an entry in argv[].
  // Will return false if entry is not formated properly.
  bool get_opt_val(
    const char     str[]
    ,std::string   *opt_name
    ,std::string   *opt_val_str // May be empty on return
    ) const;

  // String for option type
  std::string opt_type_str( EOptType ) const;

  // Print bad option
  void print_bad_opt(
    int             argv_i
    ,char*          argv[]
    ,std::ostream   *errout
    ) const;

}; // end class CommandLineProcessor

// /////////////////////////
// Inline members

template <class EType>
inline
void 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[]
  )
{
  // RAB: 2004/05/25: Every C++ implementation that I know of just
  // represents enumerations as int's and therefore this will compile
  // just fine.  However, the ISO/ANSI C++ standard says that
  // compilers are allowed to use a smaller storage type for an enum
  // but must not require storage any larger than an 'int'.  If the
  // below compile-time assertion does not compile then we need to do
  // something different but it will be a lot of work!
  CompileTimeAssert<sizeof(int)-sizeof(EType)>();
  //CompileTimeAssert<sizeof(int)-sizeof(EType)-1>(); // Uncomment to see compilation error
  setEnumOption(
    enum_option_name
    ,reinterpret_cast<int*>(enum_option_val)
    ,num_enum_opt_values
    ,reinterpret_cast<const int*>(enum_opt_values)
    ,enum_opt_names
    ,documentation
    );
}

inline
std::string CommandLineProcessor::opt_type_str( EOptType opt_type ) const
{
  std::string str;
  switch( opt_type ) {
    case OPT_BOOL_TRUE:
      str = "bool";
      break;
    case OPT_INT:
      str = "int";
      break;
    case OPT_DOUBLE:
      str = "double";
      break;
    case OPT_STRING:
      str = "string";
      break;
    case OPT_ENUM_INT:
      str = "enum";
      break;
    default:
      assert(0); // Local programming error only
  } 
  return str;
}

} // end namespace Teuchos

#endif // TEUCHOS_COMMAND_LINE_PROCESSOR_HPP

---