Teuchos - Trilinos Tools Package  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Teuchos_CommandLineProcessor.hpp
Go to the documentation of this file.
1 // @HEADER
2 // ***********************************************************************
3 //
4 // Teuchos: Common Tools Package
5 // Copyright (2004) Sandia Corporation
6 //
7 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
8 // license for use of this work by or on behalf of the U.S. Government.
9 //
10 // Redistribution and use in source and binary forms, with or without
11 // modification, are permitted provided that the following conditions are
12 // met:
13 //
14 // 1. Redistributions of source code must retain the above copyright
15 // notice, this list of conditions and the following disclaimer.
16 //
17 // 2. Redistributions in binary form must reproduce the above copyright
18 // notice, this list of conditions and the following disclaimer in the
19 // documentation and/or other materials provided with the distribution.
20 //
21 // 3. Neither the name of the Corporation nor the names of the
22 // contributors may be used to endorse or promote products derived from
23 // this software without specific prior written permission.
24 //
25 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
26 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
29 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
30 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
31 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
32 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
33 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
34 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
35 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 //
37 // Questions? Contact Michael A. Heroux (maherou@sandia.gov)
38 //
39 // ***********************************************************************
40 // @HEADER
41 
42 #ifndef TEUCHOS_COMMAND_LINE_PROCESSOR_HPP
43 #define TEUCHOS_COMMAND_LINE_PROCESSOR_HPP
44 
53 #include "Teuchos_map.hpp"
54 #include "Teuchos_any.hpp"
56 #include "Teuchos_Ptr.hpp"
57 #include <vector>
58 
74 namespace Teuchos {
75 
76 class TEUCHOSCORE_LIB_DLL_EXPORT CommandLineProcessor {
77 public:
78 
80 
81 
83  class ParseError : public std::logic_error
84  {public: ParseError(const std::string& what_arg) : std::logic_error(what_arg) {}};
85 
87  class HelpPrinted : public ParseError
88  {public: HelpPrinted(const std::string& what_arg) : ParseError(what_arg) {}};
89 
92  {public: UnrecognizedOption(const std::string& what_arg) : ParseError(what_arg) {}};
93 
99  PARSE_SUCCESSFUL = 0
100  ,PARSE_HELP_PRINTED = 1
101  ,PARSE_UNRECOGNIZED_OPTION = 2
102  ,PARSE_ERROR = 3
103  };
104 
106 
108 
109 
126  bool throwExceptions = true
127  ,bool recogniseAllOptions = true
128  ,bool addOutputSetupOptions = false
129  );
130 
134 
136 
138 
139 
141  void throwExceptions( const bool & throwExceptions );
142 
144  bool throwExceptions() const;
145 
147  void recogniseAllOptions( const bool & recogniseAllOptions );
148 
150  bool recogniseAllOptions() const;
151 
153  void addOutputSetupOptions( const bool &addOutputSetupOptions );
154 
156  bool addOutputSetupOptions() const;
157 
159 
161 
162 
165  void setDocString( const char doc_string[] );
166 
179  void setOption(
180  const char option_true[]
181  ,const char option_false[]
182  ,bool *option_val
183  ,const char documentation[] = NULL
184  );
185 
196  void setOption(
197  const char option_name[]
198  ,int *option_val
199  ,const char documentation[] = NULL
200  ,const bool required = false
201  );
202 
213  void setOption(
214  const char option_name[]
215  ,long int *option_val
216  ,const char documentation[] = NULL
217  ,const bool required = false
218  );
219 
230  void setOption(
231  const char option_name[]
232  ,size_t *option_val
233  ,const char documentation[] = NULL
234  ,const bool required = false
235  );
236 
247  void setOption(
248  const char option_name[]
249  ,long long int *option_val
250  ,const char documentation[] = NULL
251  ,const bool required = false
252  );
253 
264  void setOption(
265  const char option_name[]
266  ,double *option_val
267  ,const char documentation[] = NULL
268  ,const bool required = false
269  );
270 
281  void setOption(
282  const char option_name[]
283  ,float *option_val
284  ,const char documentation[] = NULL
285  ,const bool required = false
286  );
287 
298  void setOption(
299  const char option_name[]
300  ,std::string *option_val
301  ,const char documentation[] = NULL
302  ,const bool required = false
303  );
304 
333  template <class EType>
334  void setOption(
335  const char enum_option_name[],
336  EType* enum_option_val,
337  const int num_enum_opt_values,
338  const EType enum_opt_values[],
339  const char * const enum_opt_names[],
340  const char documentation[] = nullptr,
341  const bool required = false );
342 
344 
346 
347 
407  EParseCommandLineReturn parse(
408  int argc
409  ,char* argv[]
410  ,std::ostream *errout = &std::cerr
411  ) const;
412 
414 
416 
417 
426  void printHelpMessage( const char program_name[], std::ostream &out ) const;
427 
433  void printFinalTimerSummary(const Ptr<std::ostream> &out = null);
434 
436 
437 public:
438  //
439  enum EOptType { OPT_NONE, OPT_BOOL_TRUE, OPT_BOOL_FALSE, OPT_INT, OPT_LONG_INT, OPT_SIZE_T,
440  OPT_LONG_LONG_INT,
441  OPT_DOUBLE, OPT_FLOAT, OPT_STRING, OPT_ENUM_INT };
442 
443  // RAB: 2003/10/10: Note: I had to move this out of the private section since
444  // the sun compiler (version 7) complained (rightly it now appears after looking
445  // up what the ISO/ANSI C++ standard says) about the declaration for opt_val_val_t
446  // not being able to access a private member of CommandLineProcessor.
447 
448 private:
449 
450  // /////////////////////////////////
451  // Private types
452 
453  // ToDo: RAB: 2004/05/25: Clean up these data structures and add
454  // support for a templated enum type. This will clean up usage
455  // quite a bit.
456 
457  //
458  struct opt_val_val_t {
459  opt_val_val_t():
460  opt_type(OPT_NONE),
461  required(false),
462  was_read(false)
463  {}
464  opt_val_val_t( EOptType opt_type_in, const any& opt_val_in, bool required_in )
465  :opt_type(opt_type_in),opt_val(opt_val_in),required(required_in),was_read(false)
466  {}
467  EOptType opt_type;
468  any opt_val; // Will be bool*, int*, double*, std::string* or a small int (for OPT_ENUM_INT)
469  bool required;
470  bool was_read;
471  };
472 
473  //
474  typedef Teuchos::map<std::string,opt_val_val_t> options_list_t;
475 
476  //
477  struct opt_doc_t {
478  opt_doc_t()
479  :opt_type(OPT_NONE)
480  {}
481  opt_doc_t(EOptType opt_type_in, const std::string& opt_name_in, const std::string& opt_name_false_in
482  ,const std::string &documentation_in, const any &default_val_in )
483  :opt_type(opt_type_in),opt_name(opt_name_in),opt_name_false(opt_name_false_in)
484  ,documentation(documentation_in),default_val(default_val_in)
485  {}
486  EOptType opt_type;
487  std::string opt_name;
488  std::string opt_name_false; // only for bool
489  std::string documentation;
490  any default_val;
491  };
492 
493  //
494  typedef std::vector<opt_doc_t> options_documentation_list_t;
495 
496  //
497  struct enum_opt_data_t {
498  enum_opt_data_t()
499  :enum_option_val(NULL), num_enum_opt_values(0)
500  {}
501  enum_opt_data_t(
502  int* _enum_option_val
503  ,const int _num_enum_opt_values
504  ,const int _enum_opt_values[]
505  ,const char * const _enum_opt_names[]
506  )
507  :enum_option_val(_enum_option_val),
508  num_enum_opt_values(_num_enum_opt_values),
509  enum_opt_values(_enum_opt_values,_enum_opt_values+_num_enum_opt_values)
510  {
511  for( int k = 0; k < num_enum_opt_values; ++k )
512  enum_opt_names.push_back(std::string(_enum_opt_names[k]));
513  }
514  int *enum_option_val;
515  int num_enum_opt_values;
516  std::vector<int> enum_opt_values;
517  std::vector<std::string> enum_opt_names;
518  };
519 
520  //
521  typedef std::vector<enum_opt_data_t> enum_opt_data_list_t;
522 
523  // /////////////////////////////////
524  // Private data members
525 
526  bool throwExceptions_;
527  bool recogniseAllOptions_;
528  bool addOutputSetupOptions_;
529  std::string doc_string_;
530 
531  //use pragmas to disable some false positive warnings in windows sharedlib exports
532 #ifdef _MSC_VER
533 #pragma warning(push)
534 #pragma warning(disable:4251)
535 #endif
536  mutable options_list_t options_list_;
537  options_documentation_list_t options_documentation_list_;
538  enum_opt_data_list_t enum_opt_data_list_;
539 #ifdef _MSC_VER
540 #pragma warning(pop)
541 #endif
542 
543  bool output_all_front_matter_;
544  bool output_show_line_prefix_;
545  bool output_show_tab_count_;
546  bool output_show_proc_rank_;
547  int output_to_root_rank_only_;
548  bool print_rcpnode_statistics_on_exit_;
549  bool show_timer_summary_on_exit_;
550 
551  bool printed_timer_summary_;
552 
553  bool added_extra_output_setup_options_;
554  bool in_add_extra_output_setup_options_;
555 
556  static const bool output_all_front_matter_default_;
557  static const bool output_show_line_prefix_default_;
558  static const bool output_show_tab_count_default_;
559  static const bool output_show_proc_rank_default_;
560  static const int output_to_root_rank_only_default_;
561  static const bool print_rcpnode_statistics_on_exit_default_;
562  static const bool show_timer_summary_on_exit_default_;
563 
564  // /////////////////////////////////
565  // Private member functions
566 
567  // Set the extra output setup options
568  void add_extra_output_setup_options() const;
569 
570  // Set an integer enumeration option
571  void setEnumOption(
572  const char enum_option_name[],
573  int* enum_option_val,
574  const int num_enum_opt_values,
575  const int enum_opt_values[],
576  const char * const enum_opt_names[],
577  const char documentation[],
578  const bool required
579  );
580 
581  // Set an enum int option
582  bool set_enum_value(
583  int argv_i
584  ,char* argv[]
585  ,const std::string &enum_opt_name
586  ,const int enum_id
587  ,const std::string &enum_str_val
588  ,std::ostream *errout
589  ) const;
590 
591  // Print the valid enum values
592  void print_enum_opt_names(
593  const int enum_id
594  ,std::ostream &out
595  ) const;
596 
597  // Return the name of the default value for an enum
598  std::string enum_opt_default_val_name(
599  const std::string &enum_name
600  ,const int enum_id
601  ,std::ostream *errout
602  ) const;
603 
604  // Return the index given and option value
605  int find_enum_opt_index(
606  const std::string &enum_opt_name
607  ,const int opt_value
608  ,const enum_opt_data_t &enum_data
609  ,std::ostream *errout
610  ) const;
611 
612  // Get the option and the value from an entry in argv[].
613  // Will return false if entry is not formated properly.
614  bool get_opt_val(
615  const char str[]
616  ,std::string *opt_name
617  ,std::string *opt_val_str // May be empty on return
618  ) const;
619 
620  // String for option type
621  std::string opt_type_str( EOptType ) const;
622 
623  // Print bad option
624  void print_bad_opt(
625  int argv_i
626  ,char* argv[]
627  ,std::ostream *errout
628  ) const;
629 
630 public: // Hidden implementation stuff that clients should never see
631 
667  public:
671  virtual void summarize(std::ostream &out=std::cout) = 0;
672  };
673 
674  static void setTimeMonitorSurrogate(const RCP<TimeMonitorSurrogate> &timeMonitorSurrogate);
675 
676  static RCP<TimeMonitorSurrogate> getTimeMonitorSurrogate();
677 
678 private:
679 
680  static RCP<TimeMonitorSurrogate>& getRawTimeMonitorSurrogate();
681 
682 }; // end class CommandLineProcessor
683 
684 
685 // /////////////////////////
686 // Inline members
687 
688 
689 // Behavior modes
690 
691 
692 inline
693 void CommandLineProcessor::throwExceptions( const bool & throwExceptions_in )
694 { throwExceptions_ = throwExceptions_in; }
695 
696 
697 inline
699 { return throwExceptions_; }
700 
701 
702 inline
703 void CommandLineProcessor::recogniseAllOptions( const bool & recogniseAllOptions_in )
704 { recogniseAllOptions_ = recogniseAllOptions_in; }
705 
706 
707 inline
709 { return recogniseAllOptions_; }
710 
711 
712 inline
713 void CommandLineProcessor::addOutputSetupOptions( const bool &addOutputSetupOptions_in )
714 { addOutputSetupOptions_ = addOutputSetupOptions_in; }
715 
716 
717 inline
719 { return addOutputSetupOptions_; }
720 
721 
722 template <class EType>
723 inline
725  const char enum_option_name[],
726  EType* enum_option_val,
727  const int num_enum_opt_values,
728  const EType enum_opt_values[],
729  const char * const enum_opt_names[],
730  const char documentation[],
731  const bool required
732  )
733 {
734  // RAB: 2004/05/25: Every C++ implementation that I know of just
735  // represents enumerations as int's and therefore this will compile
736  // just fine. However, the ISO/ANSI C++ standard says that
737  // compilers are allowed to use a smaller storage type for an enum
738  // but must not require storage any larger than an 'int'. If the
739  // below compile-time assertion does not compile then we need to do
740  // something different but it will be a lot of work!
741  CompileTimeAssert<sizeof(int)-sizeof(EType)>();
742  //CompileTimeAssert<sizeof(int)-sizeof(EType)-1>(); // Uncomment to see compilation error
743  setEnumOption(
744  enum_option_name,
745  reinterpret_cast<int*>(enum_option_val),
746  num_enum_opt_values,
747  reinterpret_cast<const int*>(enum_opt_values),
748  enum_opt_names,
749  documentation,
750  required );
751 }
752 
753 
754 inline
755 std::string CommandLineProcessor::opt_type_str( EOptType opt_type ) const
756 {
757  std::string str;
758  switch( opt_type ) {
759  case OPT_BOOL_TRUE:
760  str = "bool";
761  break;
762  case OPT_INT:
763  str = "int";
764  break;
765  case OPT_LONG_INT:
766  str = "long int";
767  break;
768  case OPT_SIZE_T:
769  str = "size_t";
770  break;
771  case OPT_LONG_LONG_INT:
772  str = "long long int";
773  break;
774  case OPT_DOUBLE:
775  str = "double";
776  break;
777  case OPT_FLOAT:
778  str = "float";
779  break;
780  case OPT_STRING:
781  str = "string";
782  break;
783  case OPT_ENUM_INT:
784  str = "enum";
785  break;
786  default:
787  assert(0); // Local programming error only
788  }
789  return str;
790 }
791 
792 
793 } // end namespace Teuchos
794 
795 
796 #endif // TEUCHOS_COMMAND_LINE_PROCESSOR_HPP
Modified boost::any class for holding a templated value.
Thrown if –help was specified and throwExceptions==true.
Template classes for testing assertions at compile time.
bool throwExceptions() const
Returns true if an std::exception is thrown, there is a parse error, or help is printed.
Thrown if an unrecognized option was found and throwExceptions==true.
void setOption(const char option_true[], const char option_false[], bool *option_val, const char documentation[]=NULL)
Set a boolean option.
Interface by which CommandLineProcessor may use TimeMonitor.
bool addOutputSetupOptions() const
Returns true options will be automatically added to setup Teuchos::VerboseObjectBase::getDefaultOStre...
Provides std::map class for deficient platforms.
EParseCommandLineReturn
Return value for CommandLineProcessor::parse(). Note: These enums are all given non-negative values s...
bool recogniseAllOptions() const
Returns true if all options must be recognized by the parser.
Smart reference counting pointer class for automatic garbage collection.
If instantiated (for Test!=0) then this should not compile!
Thrown if a parse std::exception occurs and throwExceptions==true.
Class that helps parse command line input arguments from (argc,argv[]) and set options.
Simple wrapper class for raw pointers to single objects where no persisting relationship exists...