Teuchos Package Browser (Single Doxygen Collection) Version of the Day
Teuchos_CommandLineProcessor.hpp
Go to the documentation of this file.
00001 // @HEADER
00002 // ***********************************************************************
00003 //
00004 //                    Teuchos: Common Tools Package
00005 //                 Copyright (2004) Sandia Corporation
00006 //
00007 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
00008 // license for use of this work by or on behalf of the U.S. Government.
00009 //
00010 // Redistribution and use in source and binary forms, with or without
00011 // modification, are permitted provided that the following conditions are
00012 // met:
00013 //
00014 // 1. Redistributions of source code must retain the above copyright
00015 // notice, this list of conditions and the following disclaimer.
00016 //
00017 // 2. Redistributions in binary form must reproduce the above copyright
00018 // notice, this list of conditions and the following disclaimer in the
00019 // documentation and/or other materials provided with the distribution.
00020 //
00021 // 3. Neither the name of the Corporation nor the names of the
00022 // contributors may be used to endorse or promote products derived from
00023 // this software without specific prior written permission.
00024 //
00025 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
00026 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00027 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
00028 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
00029 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00030 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00031 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00032 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00033 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00034 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00035 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00036 //
00037 // Questions? Contact Michael A. Heroux (maherou@sandia.gov)
00038 //
00039 // ***********************************************************************
00040 // @HEADER
00041 
00042 #ifndef TEUCHOS_COMMAND_LINE_PROCESSOR_HPP
00043 #define TEUCHOS_COMMAND_LINE_PROCESSOR_HPP
00044 
00053 #include "Teuchos_map.hpp"
00054 #include "Teuchos_any.hpp"
00055 #include "Teuchos_CompileTimeAssert.hpp"
00056 #include "Teuchos_Ptr.hpp"
00057 
00073 namespace Teuchos {
00074 
00075 class TEUCHOSCORE_LIB_DLL_EXPORT CommandLineProcessor {
00076 public:
00077 
00079 
00080 
00082   class ParseError : public std::logic_error
00083   {public: ParseError(const std::string& what_arg) : std::logic_error(what_arg) {}};
00084 
00086   class HelpPrinted : public ParseError
00087   {public: HelpPrinted(const std::string& what_arg) : ParseError(what_arg) {}};
00088 
00090   class UnrecognizedOption : public ParseError
00091   {public: UnrecognizedOption(const std::string& what_arg) : ParseError(what_arg) {}};
00092 
00097   enum EParseCommandLineReturn {
00098     PARSE_SUCCESSFUL              =  0 
00099     ,PARSE_HELP_PRINTED            =  1 
00100     ,PARSE_UNRECOGNIZED_OPTION     =  2 
00101     ,PARSE_ERROR                   =  3 
00102   };
00103   
00105 
00107 
00108 
00124   CommandLineProcessor(
00125     bool    throwExceptions       = true
00126     ,bool   recogniseAllOptions   = true
00127     ,bool   addOutputSetupOptions = false
00128     );
00129 
00132   ~CommandLineProcessor();
00133 
00135 
00137 
00138 
00140   void throwExceptions( const bool & throwExceptions );
00141   
00143   bool throwExceptions() const;
00144 
00146   void recogniseAllOptions( const bool & recogniseAllOptions );
00147 
00149   bool recogniseAllOptions() const;
00150 
00152   void addOutputSetupOptions( const bool &addOutputSetupOptions );
00153 
00155   bool addOutputSetupOptions() const;
00156 
00158 
00160 
00161   
00164   void setDocString( const char doc_string[] );
00165 
00178   void setOption(
00179     const char     option_true[]
00180     ,const char    option_false[]
00181     ,bool          *option_val
00182     ,const char    documentation[] = NULL
00183     );
00184 
00195   void setOption(
00196     const char     option_name[]
00197     ,int           *option_val
00198     ,const char    documentation[] = NULL
00199     ,const bool    required        = false
00200     );
00201 
00212   void setOption(
00213     const char     option_name[]
00214     ,long int      *option_val
00215     ,const char    documentation[] = NULL
00216     ,const bool    required        = false
00217     );
00218 
00219 #ifdef HAVE_TEUCHOS_LONG_LONG_INT
00220 
00230   void setOption(
00231     const char     option_name[]
00232     ,long long int *option_val
00233     ,const char    documentation[] = NULL
00234     ,const bool    required        = false
00235     );
00236 #endif
00237 
00248   void setOption(
00249     const char     option_name[]
00250     ,double        *option_val
00251     ,const char    documentation[] = NULL
00252     ,const bool    required        = false
00253     );
00254 
00265   void setOption(
00266     const char     option_name[]
00267     ,std::string   *option_val
00268     ,const char    documentation[] = NULL
00269     ,const bool    required        = false
00270     );
00271   
00300   template <class EType>
00301   void setOption(
00302     const char    enum_option_name[]
00303     ,EType        *enum_option_val
00304     ,const int    num_enum_opt_values
00305     ,const EType  enum_opt_values[]
00306     ,const char*  enum_opt_names[]
00307     ,const char   documentation[] = NULL
00308     ,const bool   required        = false
00309     );
00310   
00312 
00314 
00315 
00375   EParseCommandLineReturn  parse(
00376     int             argc
00377     ,char*          argv[]
00378     ,std::ostream   *errout = &std::cerr
00379     ) const;
00380 
00382 
00384 
00385 
00394    void printHelpMessage( const char program_name[], std::ostream &out ) const;
00395 
00401   void printFinalTimerSummary(const Ptr<std::ostream> &out = null);
00402 
00404 
00405 public:
00406   //
00407   enum EOptType { OPT_NONE, OPT_BOOL_TRUE, OPT_BOOL_FALSE, OPT_INT, OPT_LONG_INT, 
00408 #ifdef HAVE_TEUCHOS_LONG_LONG_INT
00409   OPT_LONG_LONG_INT,
00410 #endif
00411   OPT_DOUBLE, OPT_STRING, OPT_ENUM_INT };
00412 
00413   // RAB: 2003/10/10: Note: I had to move this out of the private section since
00414   // the sun compiler (version 7) complained (rightly it now appears after looking
00415   // up what the ISO/ANSI C++ standard says) about the declaration for opt_val_val_t
00416   // not being able to access a private member of CommandLineProcessor.
00417 
00418 private:
00419 
00420   // /////////////////////////////////
00421   // Private types
00422 
00423   // ToDo: RAB: 2004/05/25: Clean up these data structures and add
00424   // support for a templated enum type.  This will clean up usage
00425   // quite a bit.
00426 
00427   //
00428   struct opt_val_val_t {
00429     opt_val_val_t()
00430       :opt_type(OPT_NONE)
00431       {}
00432     opt_val_val_t( EOptType opt_type_in, const any& opt_val_in, bool required_in )
00433       :opt_type(opt_type_in),opt_val(opt_val_in),required(required_in),was_read(false)
00434       {}
00435     EOptType     opt_type;
00436     any          opt_val; // Will be bool*, int*, double*, std::string* or a small int (for OPT_ENUM_INT)
00437     bool         required;
00438     bool         was_read;
00439   };
00440 
00441   //
00442   typedef Teuchos::map<std::string,opt_val_val_t>   options_list_t;
00443 
00444   //
00445   struct opt_doc_t {
00446     opt_doc_t()
00447       :opt_type(OPT_NONE)
00448       {}
00449     opt_doc_t(EOptType opt_type_in, const std::string& opt_name_in, const std::string& opt_name_false_in
00450             ,const std::string &documentation_in, const any &default_val_in )
00451       :opt_type(opt_type_in),opt_name(opt_name_in),opt_name_false(opt_name_false_in)
00452       ,documentation(documentation_in),default_val(default_val_in)
00453       {}
00454     EOptType     opt_type;
00455     std::string  opt_name;
00456     std::string  opt_name_false; // only for bool
00457     std::string  documentation;
00458     any          default_val;
00459   };
00460   
00461   //
00462   typedef std::vector<opt_doc_t>   options_documentation_list_t;
00463 
00464   //
00465   struct enum_opt_data_t {
00466     enum_opt_data_t()
00467       :enum_option_val(NULL), num_enum_opt_values(0)
00468       {}
00469     enum_opt_data_t(
00470       int          *_enum_option_val
00471       ,const int    _num_enum_opt_values
00472       ,const int    _enum_opt_values[]
00473       ,const char*  _enum_opt_names[]
00474       )
00475       :enum_option_val(_enum_option_val)
00476       ,num_enum_opt_values(_num_enum_opt_values)
00477       ,enum_opt_values(_enum_opt_values,_enum_opt_values+_num_enum_opt_values)
00478       {
00479         for( int k = 0; k < num_enum_opt_values; ++k )
00480           enum_opt_names.push_back(std::string(_enum_opt_names[k]));
00481       }
00482     int                  *enum_option_val;
00483     int                  num_enum_opt_values;
00484     std::vector<int>     enum_opt_values;
00485     std::vector<std::string>  enum_opt_names;
00486   };
00487 
00488   //
00489   typedef std::vector<enum_opt_data_t> enum_opt_data_list_t;
00490 
00491   // /////////////////////////////////
00492   // Private data members
00493 
00494   bool                             throwExceptions_;
00495   bool                             recogniseAllOptions_;
00496   bool                             addOutputSetupOptions_;
00497   std::string                      doc_string_;
00498 
00499   //use pragmas to disable some false positive warnings in windows sharedlib exports
00500 #ifdef _MSC_VER
00501 #pragma warning(push)
00502 #pragma warning(disable:4251)
00503 #endif
00504   mutable options_list_t           options_list_;
00505   options_documentation_list_t     options_documentation_list_;
00506   enum_opt_data_list_t             enum_opt_data_list_;
00507 #ifdef _MSC_VER
00508 #pragma warning(pop)
00509 #endif
00510 
00511   bool  output_all_front_matter_;
00512   bool  output_show_line_prefix_;
00513   bool  output_show_tab_count_;
00514   bool  output_show_proc_rank_;
00515   int   output_to_root_rank_only_;
00516   bool  print_rcpnode_statistics_on_exit_;
00517   bool  show_timer_summary_on_exit_;
00518 
00519   bool printed_timer_summary_;
00520 
00521   bool  added_extra_output_setup_options_;
00522   bool  in_add_extra_output_setup_options_;
00523 
00524   static const bool  output_all_front_matter_default_;
00525   static const bool  output_show_line_prefix_default_;
00526   static const bool  output_show_tab_count_default_;
00527   static const bool  output_show_proc_rank_default_;
00528   static const int   output_to_root_rank_only_default_;
00529   static const bool  print_rcpnode_statistics_on_exit_default_;
00530   static const bool  show_timer_summary_on_exit_default_;
00531 
00532   // /////////////////////////////////
00533   // Private member functions
00534 
00535   // Set the extra output setup options
00536   void add_extra_output_setup_options() const;
00537 
00538   // Set an integer enumeration option
00539   void setEnumOption(
00540     const char    enum_option_name[]
00541     ,int          *enum_option_val
00542     ,const int    num_enum_opt_values
00543     ,const int    enum_opt_values[]
00544     ,const char*  enum_opt_names[]
00545     ,const char   documentation[]
00546     ,const bool   required
00547     );
00548 
00549   // Set an enum int option
00550   bool set_enum_value(
00551     int                  argv_i
00552     ,char*               argv[]
00553     ,const std::string   &enum_opt_name
00554     ,const int           enum_id
00555     ,const std::string   &enum_str_val
00556     ,std::ostream        *errout
00557     ) const;
00558 
00559   // Print the valid enum values
00560   void print_enum_opt_names(
00561     const int            enum_id
00562     ,std::ostream        &out
00563     ) const;
00564 
00565   // Return the name of the default value for an enum
00566   std::string enum_opt_default_val_name(
00567     const std::string    &enum_name
00568     ,const int           enum_id
00569     ,std::ostream        *errout
00570     ) const;
00571   
00572   // Return the index given and option value
00573   int find_enum_opt_index(
00574     const std::string           &enum_opt_name
00575     ,const int                  opt_value
00576     ,const enum_opt_data_t      &enum_data
00577     ,std::ostream               *errout
00578     ) const; 
00579 
00580   // Get the option and the value from an entry in argv[].
00581   // Will return false if entry is not formated properly.
00582   bool get_opt_val(
00583     const char     str[]
00584     ,std::string   *opt_name
00585     ,std::string   *opt_val_str // May be empty on return
00586     ) const;
00587 
00588   // String for option type
00589   std::string opt_type_str( EOptType ) const;
00590 
00591   // Print bad option
00592   void print_bad_opt(
00593     int             argv_i
00594     ,char*          argv[]
00595     ,std::ostream   *errout
00596     ) const;
00597 
00598 public: // Hidden implementation stuff that clients should never see
00599 
00634   class TimeMonitorSurrogate {
00635   public:
00637     virtual ~TimeMonitorSurrogate() {}
00639     virtual void summarize(std::ostream &out=std::cout) = 0;
00640   };
00641 
00642   static void setTimeMonitorSurrogate(const RCP<TimeMonitorSurrogate> &timeMonitorSurrogate);
00643 
00644   static RCP<TimeMonitorSurrogate> getTimeMonitorSurrogate();
00645 
00646 private:
00647 
00648   static RCP<TimeMonitorSurrogate>& getRawTimeMonitorSurrogate();
00649 
00650 }; // end class CommandLineProcessor
00651 
00652 
00653 // /////////////////////////
00654 // Inline members
00655 
00656 
00657 // Behavior modes
00658 
00659 
00660 inline
00661 void CommandLineProcessor::throwExceptions( const bool & throwExceptions_in )
00662 { throwExceptions_ = throwExceptions_in; }
00663 
00664 
00665 inline
00666 bool CommandLineProcessor::throwExceptions() const
00667 { return throwExceptions_; }
00668 
00669 
00670 inline
00671 void CommandLineProcessor::recogniseAllOptions( const bool & recogniseAllOptions_in )
00672 { recogniseAllOptions_ = recogniseAllOptions_in; }
00673 
00674 
00675 inline
00676 bool CommandLineProcessor::recogniseAllOptions() const
00677 { return recogniseAllOptions_; }
00678 
00679 
00680 inline
00681 void CommandLineProcessor::addOutputSetupOptions( const bool &addOutputSetupOptions_in )
00682 { addOutputSetupOptions_ = addOutputSetupOptions_in; }
00683 
00684 
00685 inline
00686 bool CommandLineProcessor::addOutputSetupOptions() const
00687 { return addOutputSetupOptions_; }
00688 
00689 
00690 template <class EType>
00691 inline
00692 void CommandLineProcessor::setOption(
00693   const char    enum_option_name[]
00694   ,EType       *enum_option_val
00695   ,const int    num_enum_opt_values
00696   ,const EType  enum_opt_values[]
00697   ,const char*  enum_opt_names[]
00698   ,const char   documentation[]
00699   ,const bool   required
00700   )
00701 {
00702   // RAB: 2004/05/25: Every C++ implementation that I know of just
00703   // represents enumerations as int's and therefore this will compile
00704   // just fine.  However, the ISO/ANSI C++ standard says that
00705   // compilers are allowed to use a smaller storage type for an enum
00706   // but must not require storage any larger than an 'int'.  If the
00707   // below compile-time assertion does not compile then we need to do
00708   // something different but it will be a lot of work!
00709   CompileTimeAssert<sizeof(int)-sizeof(EType)>();
00710   //CompileTimeAssert<sizeof(int)-sizeof(EType)-1>(); // Uncomment to see compilation error
00711   setEnumOption(
00712     enum_option_name
00713     ,reinterpret_cast<int*>(enum_option_val)
00714     ,num_enum_opt_values
00715     ,reinterpret_cast<const int*>(enum_opt_values)
00716     ,enum_opt_names
00717     ,documentation
00718     ,required
00719     );
00720 }
00721 
00722 
00723 inline
00724 std::string CommandLineProcessor::opt_type_str( EOptType opt_type ) const
00725 {
00726   std::string str;
00727   switch( opt_type ) {
00728     case OPT_BOOL_TRUE:
00729       str = "bool";
00730       break;
00731     case OPT_INT:
00732       str = "int";
00733       break;
00734     case OPT_LONG_INT:
00735       str = "long int";
00736       break;
00737 #ifdef HAVE_TEUCHOS_LONG_LONG_INT
00738     case OPT_LONG_LONG_INT:
00739       str = "long long int";
00740       break;
00741 #endif
00742     case OPT_DOUBLE:
00743       str = "double";
00744       break;
00745     case OPT_STRING:
00746       str = "string";
00747       break;
00748     case OPT_ENUM_INT:
00749       str = "enum";
00750       break;
00751     default:
00752       assert(0); // Local programming error only
00753   } 
00754   return str;
00755 }
00756 
00757 
00758 } // end namespace Teuchos
00759 
00760 
00761 #endif // TEUCHOS_COMMAND_LINE_PROCESSOR_HPP
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines