Teuchos Package Browser (Single Doxygen Collection)  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 // Teuchos: Common Tools Package
4 //
5 // Copyright 2004 NTESS and the Teuchos contributors.
6 // SPDX-License-Identifier: BSD-3-Clause
7 // *****************************************************************************
8 // @HEADER
9 
10 #ifndef TEUCHOS_COMMAND_LINE_PROCESSOR_HPP
11 #define TEUCHOS_COMMAND_LINE_PROCESSOR_HPP
12 
21 #include "Teuchos_map.hpp"
22 #include "Teuchos_any.hpp"
24 #include "Teuchos_Ptr.hpp"
25 #include <vector>
26 
42 namespace Teuchos {
43 
45 public:
46 
48 
49 
51  class ParseError : public std::logic_error
52  {public: ParseError(const std::string& what_arg) : std::logic_error(what_arg) {}};
53 
55  class HelpPrinted : public ParseError
56  {public: HelpPrinted(const std::string& what_arg) : ParseError(what_arg) {}};
57 
60  {public: UnrecognizedOption(const std::string& what_arg) : ParseError(what_arg) {}};
61 
67  PARSE_SUCCESSFUL = 0
68  ,PARSE_HELP_PRINTED = 1
69  ,PARSE_UNRECOGNIZED_OPTION = 2
70  ,PARSE_ERROR = 3
71  };
72 
74 
76 
77 
94  bool throwExceptions = true
95  ,bool recogniseAllOptions = true
96  ,bool addOutputSetupOptions = false
97  );
98 
102 
104 
106 
107 
109  void throwExceptions( const bool & throwExceptions );
110 
112  bool throwExceptions() const;
113 
115  void recogniseAllOptions( const bool & recogniseAllOptions );
116 
118  bool recogniseAllOptions() const;
119 
121  void addOutputSetupOptions( const bool &addOutputSetupOptions );
122 
124  bool addOutputSetupOptions() const;
125 
127 
129 
130 
133  void setDocString( const char doc_string[] );
134 
147  void setOption(
148  const char option_true[]
149  ,const char option_false[]
150  ,bool *option_val
151  ,const char documentation[] = NULL
152  );
153 
164  void setOption(
165  const char option_name[]
166  ,int *option_val
167  ,const char documentation[] = NULL
168  ,const bool required = false
169  );
170 
181  void setOption(
182  const char option_name[]
183  ,long int *option_val
184  ,const char documentation[] = NULL
185  ,const bool required = false
186  );
187 
198  void setOption(
199  const char option_name[]
200  ,size_t *option_val
201  ,const char documentation[] = NULL
202  ,const bool required = false
203  );
204 
215  void setOption(
216  const char option_name[]
217  ,long long int *option_val
218  ,const char documentation[] = NULL
219  ,const bool required = false
220  );
221 
232  void setOption(
233  const char option_name[]
234  ,double *option_val
235  ,const char documentation[] = NULL
236  ,const bool required = false
237  );
238 
249  void setOption(
250  const char option_name[]
251  ,float *option_val
252  ,const char documentation[] = NULL
253  ,const bool required = false
254  );
255 
266  void setOption(
267  const char option_name[]
268  ,std::string *option_val
269  ,const char documentation[] = NULL
270  ,const bool required = false
271  );
272 
301  template <class EType>
302  void setOption(
303  const char enum_option_name[],
304  EType* enum_option_val,
305  const int num_enum_opt_values,
306  const EType enum_opt_values[],
307  const char * const enum_opt_names[],
308  const char documentation[] = nullptr,
309  const bool required = false );
310 
312 
314 
315 
375  EParseCommandLineReturn parse(
376  int argc
377  ,char* argv[]
378  ,std::ostream *errout = &std::cerr
379  ) const;
380 
382 
384 
385 
394  void printHelpMessage( const char program_name[], std::ostream &out ) const;
395 
401  void printFinalTimerSummary(const Ptr<std::ostream> &out = null);
402 
404 
405 public:
406  //
407  enum EOptType { OPT_NONE, OPT_BOOL_TRUE, OPT_BOOL_FALSE, OPT_INT, OPT_LONG_INT, OPT_SIZE_T,
409  OPT_DOUBLE, OPT_FLOAT, OPT_STRING, OPT_ENUM_INT };
410 
411  // RAB: 2003/10/10: Note: I had to move this out of the private section since
412  // the sun compiler (version 7) complained (rightly it now appears after looking
413  // up what the ISO/ANSI C++ standard says) about the declaration for opt_val_val_t
414  // not being able to access a private member of CommandLineProcessor.
415 
416 private:
417 
418  // /////////////////////////////////
419  // Private types
420 
421  // ToDo: RAB: 2004/05/25: Clean up these data structures and add
422  // support for a templated enum type. This will clean up usage
423  // quite a bit.
424 
425  //
426  struct opt_val_val_t {
428  opt_type(OPT_NONE),
429  required(false),
430  was_read(false)
431  {}
432  opt_val_val_t( EOptType opt_type_in, const any& opt_val_in, bool required_in )
433  :opt_type(opt_type_in),opt_val(opt_val_in),required(required_in),was_read(false)
434  {}
436  any opt_val; // Will be bool*, int*, double*, std::string* or a small int (for OPT_ENUM_INT)
437  bool required;
438  bool was_read;
439  };
440 
441  //
443 
444  //
445  struct opt_doc_t {
447  :opt_type(OPT_NONE)
448  {}
449  opt_doc_t(EOptType opt_type_in, const std::string& opt_name_in, const std::string& opt_name_false_in
450  ,const std::string &documentation_in, const any &default_val_in )
451  :opt_type(opt_type_in),opt_name(opt_name_in),opt_name_false(opt_name_false_in)
452  ,documentation(documentation_in),default_val(default_val_in)
453  {}
455  std::string opt_name;
456  std::string opt_name_false; // only for bool
457  std::string documentation;
459  };
460 
461  //
462  typedef std::vector<opt_doc_t> options_documentation_list_t;
463 
464  //
467  :enum_option_val(NULL), num_enum_opt_values(0)
468  {}
470  int* _enum_option_val
471  ,const int _num_enum_opt_values
472  ,const int _enum_opt_values[]
473  ,const char * const _enum_opt_names[]
474  )
475  :enum_option_val(_enum_option_val),
476  num_enum_opt_values(_num_enum_opt_values),
477  enum_opt_values(_enum_opt_values,_enum_opt_values+_num_enum_opt_values)
478  {
479  for( int k = 0; k < num_enum_opt_values; ++k )
480  enum_opt_names.push_back(std::string(_enum_opt_names[k]));
481  }
484  std::vector<int> enum_opt_values;
485  std::vector<std::string> enum_opt_names;
486  };
487 
488  //
489  typedef std::vector<enum_opt_data_t> enum_opt_data_list_t;
490 
491  // /////////////////////////////////
492  // Private data members
493 
497  std::string doc_string_;
498 
499  //use pragmas to disable some false positive warnings in windows sharedlib exports
500 #ifdef _MSC_VER
501 #pragma warning(push)
502 #pragma warning(disable:4251)
503 #endif
507 #ifdef _MSC_VER
508 #pragma warning(pop)
509 #endif
510 
518 
520 
523 
531 
532  // /////////////////////////////////
533  // Private member functions
534 
535  // Set the extra output setup options
536  void add_extra_output_setup_options() const;
537 
538  // Set an integer enumeration option
539  void setEnumOption(
540  const char enum_option_name[],
541  int* enum_option_val,
542  const int num_enum_opt_values,
543  const int enum_opt_values[],
544  const char * const enum_opt_names[],
545  const char documentation[],
546  const bool required
547  );
548 
549  // Set an enum int option
550  bool set_enum_value(
551  int argv_i
552  ,char* argv[]
553  ,const std::string &enum_opt_name
554  ,const int enum_id
555  ,const std::string &enum_str_val
556  ,std::ostream *errout
557  ) const;
558 
559  // Print the valid enum values
560  void print_enum_opt_names(
561  const int enum_id
562  ,std::ostream &out
563  ) const;
564 
565  // Return the name of the default value for an enum
566  std::string enum_opt_default_val_name(
567  const std::string &enum_name
568  ,const int enum_id
569  ,std::ostream *errout
570  ) const;
571 
572  // Return the index given and option value
573  int find_enum_opt_index(
574  const std::string &enum_opt_name
575  ,const int opt_value
576  ,const enum_opt_data_t &enum_data
577  ,std::ostream *errout
578  ) const;
579 
580  // Get the option and the value from an entry in argv[].
581  // Will return false if entry is not formated properly.
582  bool get_opt_val(
583  const char str[]
584  ,std::string *opt_name
585  ,std::string *opt_val_str // May be empty on return
586  ) const;
587 
588  // String for option type
589  std::string opt_type_str( EOptType ) const;
590 
591  // Print bad option
592  void print_bad_opt(
593  int argv_i
594  ,char* argv[]
595  ,std::ostream *errout
596  ) const;
597 
598 public: // Hidden implementation stuff that clients should never see
599 
635  public:
639  virtual void summarize(std::ostream &out=std::cout) = 0;
640  };
641 
642  static void setTimeMonitorSurrogate(const RCP<TimeMonitorSurrogate> &timeMonitorSurrogate);
643 
644  static RCP<TimeMonitorSurrogate> getTimeMonitorSurrogate();
645 
646 private:
647 
648  static RCP<TimeMonitorSurrogate>& getRawTimeMonitorSurrogate();
649 
650 }; // end class CommandLineProcessor
651 
652 
653 // /////////////////////////
654 // Inline members
655 
656 
657 // Behavior modes
658 
659 
660 inline
661 void CommandLineProcessor::throwExceptions( const bool & throwExceptions_in )
662 { throwExceptions_ = throwExceptions_in; }
663 
664 
665 inline
667 { return throwExceptions_; }
668 
669 
670 inline
671 void CommandLineProcessor::recogniseAllOptions( const bool & recogniseAllOptions_in )
672 { recogniseAllOptions_ = recogniseAllOptions_in; }
673 
674 
675 inline
677 { return recogniseAllOptions_; }
678 
679 
680 inline
681 void CommandLineProcessor::addOutputSetupOptions( const bool &addOutputSetupOptions_in )
682 { addOutputSetupOptions_ = addOutputSetupOptions_in; }
683 
684 
685 inline
687 { return addOutputSetupOptions_; }
688 
689 
690 template <class EType>
691 inline
693  const char enum_option_name[],
694  EType* enum_option_val,
695  const int num_enum_opt_values,
696  const EType enum_opt_values[],
697  const char * const enum_opt_names[],
698  const char documentation[],
699  const bool required
700  )
701 {
702  // RAB: 2004/05/25: Every C++ implementation that I know of just
703  // represents enumerations as int's and therefore this will compile
704  // just fine. However, the ISO/ANSI C++ standard says that
705  // compilers are allowed to use a smaller storage type for an enum
706  // but must not require storage any larger than an 'int'. If the
707  // below compile-time assertion does not compile then we need to do
708  // something different but it will be a lot of work!
709  CompileTimeAssert<sizeof(int)-sizeof(EType)>();
710  //CompileTimeAssert<sizeof(int)-sizeof(EType)-1>(); // Uncomment to see compilation error
712  enum_option_name,
713  reinterpret_cast<int*>(enum_option_val),
714  num_enum_opt_values,
715  reinterpret_cast<const int*>(enum_opt_values),
716  enum_opt_names,
717  documentation,
718  required );
719 }
720 
721 
722 inline
723 std::string CommandLineProcessor::opt_type_str( EOptType opt_type ) const
724 {
725  std::string str;
726  switch( opt_type ) {
727  case OPT_BOOL_TRUE:
728  str = "bool";
729  break;
730  case OPT_INT:
731  str = "int";
732  break;
733  case OPT_LONG_INT:
734  str = "long int";
735  break;
736  case OPT_SIZE_T:
737  str = "size_t";
738  break;
739  case OPT_LONG_LONG_INT:
740  str = "long long int";
741  break;
742  case OPT_DOUBLE:
743  str = "double";
744  break;
745  case OPT_FLOAT:
746  str = "float";
747  break;
748  case OPT_STRING:
749  str = "string";
750  break;
751  case OPT_ENUM_INT:
752  str = "enum";
753  break;
754  default:
755  assert(0); // Local programming error only
756  }
757  return str;
758 }
759 
760 
761 } // end namespace Teuchos
762 
763 
764 #endif // TEUCHOS_COMMAND_LINE_PROCESSOR_HPP
Modified boost::any class for holding a templated value.
Thrown if –help was specified and throwExceptions==true.
std::vector< enum_opt_data_t > enum_opt_data_list_t
Teuchos::map< std::string, opt_val_val_t > options_list_t
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.
std::vector< opt_doc_t > options_documentation_list_t
opt_val_val_t(EOptType opt_type_in, const any &opt_val_in, bool required_in)
Modified boost::any class, which is a container for a templated value.
void setEnumOption(const char enum_option_name[], int *enum_option_val, const int num_enum_opt_values, const int enum_opt_values[], const char *const enum_opt_names[], const char documentation[], const bool required)
Thrown if an unrecognized option was found and throwExceptions==true.
options_documentation_list_t options_documentation_list_
void setOption(const char option_true[], const char option_false[], bool *option_val, const char documentation[]=NULL)
Set a boolean option.
#define TEUCHOSCORE_LIB_DLL_EXPORT
std::string opt_type_str(EOptType) const
Interface by which CommandLineProcessor may use TimeMonitor.
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)
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.
enum_opt_data_t(int *_enum_option_val, const int _num_enum_opt_values, const int _enum_opt_values[], const char *const _enum_opt_names[])
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...