mlpack  2.0.1
cli.hpp
Go to the documentation of this file.
1 
16 #ifndef __MLPACK_CORE_UTIL_CLI_HPP
17 #define __MLPACK_CORE_UTIL_CLI_HPP
18 
19 #include <list>
20 #include <iostream>
21 #include <map>
22 #include <string>
23 
24 #include <boost/any.hpp>
25 #include <boost/program_options.hpp>
26 
27 #include "timers.hpp"
28 #include "cli_deleter.hpp" // To make sure we can delete the singleton.
29 #include "version.hpp"
30 
46 #define PROGRAM_INFO(NAME, DESC) static mlpack::util::ProgramDoc \
47  io_programdoc_dummy_object = mlpack::util::ProgramDoc(NAME, DESC);
48 
66 #define PARAM_FLAG(ID, DESC, ALIAS) \
67  PARAM_FLAG_INTERNAL(ID, DESC, ALIAS);
68 
90 #define PARAM_INT(ID, DESC, ALIAS, DEF) \
91  PARAM(int, ID, DESC, ALIAS, DEF, false)
92 
114 #define PARAM_FLOAT(ID, DESC, ALIAS, DEF) \
115  PARAM(float, ID, DESC, ALIAS, DEF, false)
116 
138 #define PARAM_DOUBLE(ID, DESC, ALIAS, DEF) \
139  PARAM(double, ID, DESC, ALIAS, DEF, false)
140 
163 #define PARAM_STRING(ID, DESC, ALIAS, DEF) \
164  PARAM(std::string, ID, DESC, ALIAS, DEF, false)
165 
187 #define PARAM_VECTOR(T, ID, DESC, ALIAS) \
188  PARAM(std::vector<T>, ID, DESC, ALIAS, std::vector<T>(), false)
189 
190 // A required flag doesn't make sense and isn't given here.
191 
212 #define PARAM_INT_REQ(ID, DESC, ALIAS) PARAM(int, ID, DESC, ALIAS, 0, true)
213 
236 #define PARAM_FLOAT_REQ(ID, DESC, ALIAS) PARAM(float, ID, DESC, ALIAS, 0.0f, \
237  true)
238 
259 #define PARAM_DOUBLE_REQ(ID, DESC, ALIAS) PARAM(double, ID, DESC, ALIAS, \
260  0.0f, true)
261 
282 #define PARAM_STRING_REQ(ID, DESC, ALIAS) PARAM(std::string, ID, DESC, \
283  ALIAS, "", true);
284 
305 #define PARAM_VECTOR_REQ(T, ID, DESC, ALIAS) PARAM(std::vector<T>, ID, DESC, \
306  ALIAS, std::vector<T>(), true);
307 
313 // These are ugly, but necessary utility functions we must use to generate a
314 // unique identifier inside of the PARAM() module.
315 #define JOIN(x, y) JOIN_AGAIN(x, y)
316 #define JOIN_AGAIN(x, y) x ## y
317 
333 #ifdef __COUNTER__
334  #define PARAM(T, ID, DESC, ALIAS, DEF, REQ) static mlpack::util::Option<T> \
335  JOIN(io_option_dummy_object_, __COUNTER__) \
336  (false, DEF, ID, DESC, ALIAS, REQ);
337 
339  #define PARAM_FLAG_INTERNAL(ID, DESC, ALIAS) static \
340  mlpack::util::Option<bool> JOIN(__io_option_flag_object_, __COUNTER__) \
341  (ID, DESC, ALIAS);
342 
344 #else
345  // We have to do some really bizarre stuff since __COUNTER__ isn't defined. I
346  // don't think we can absolutely guarantee success, but it should be "good
347  // enough". We use the __LINE__ macro and the type of the parameter to try
348  // and get a good guess at something unique.
349  #define PARAM(T, ID, DESC, ALIAS, DEF, REQ) static mlpack::util::Option<T> \
350  JOIN(JOIN(io_option_dummy_object_, __LINE__), opt) (false, DEF, ID, \
351  DESC, ALIAS, REQ);
352 
354  #define PARAM_FLAG_INTERNAL(ID, DESC, ALIAS) static \
355  mlpack::util::Option<bool> JOIN(__io_option_flag_object_, __LINE__) \
356  (ID, DESC, ALIAS);
357 
359 #endif
360 
364 #define TYPENAME(x) (std::string(typeid(x).name()))
365 
366 namespace po = boost::program_options;
367 
368 namespace mlpack {
369 
370 namespace util {
371 
372 // Externally defined in option.hpp, this class holds information about the
373 // program being run.
374 class ProgramDoc;
375 
376 } // namespace util
377 
382 struct ParamData
383 {
385  std::string name;
387  std::string desc;
389  std::string tname;
391  boost::any value;
393  bool wasPassed;
395  bool isFlag;
396 };
397 
523 class CLI
524 {
525  public:
537  static void Add(const std::string& path,
538  const std::string& description,
539  const std::string& alias = "",
540  bool required = false);
541 
553  template<class T>
554  static void Add(const std::string& identifier,
555  const std::string& description,
556  const std::string& alias = "",
557  bool required = false);
558 
566  static void AddFlag(const std::string& identifier,
567  const std::string& description,
568  const std::string& alias = "");
569 
574  static void DefaultMessages();
575 
581  static void Destroy();
582 
589  template<typename T>
590  static T& GetParam(const std::string& identifier);
591 
598  static std::string GetDescription(const std::string& identifier);
599 
612  static CLI& GetSingleton();
613 
619  static bool HasParam(const std::string& identifier);
620 
628  static std::string HyphenateString(const std::string& str, int padding);
629 
636  static void ParseCommandLine(int argc, char** argv);
637 
643  static void RemoveDuplicateFlags(po::basic_parsed_options<char>& bpo);
644 
650  static void ParseStream(std::istream& stream);
651 
655  static void Print();
656 
660  static void PrintHelp(const std::string& param = "");
661 
669  static void RegisterProgramDoc(util::ProgramDoc* doc);
670 
674  ~CLI();
675 
676  private:
678  po::options_description desc;
679 
681  po::variables_map vmap;
682 
684  std::list<std::string> requiredOptions;
685 
687  typedef std::map<std::string, ParamData> gmap_t;
688  gmap_t globalValues;
689 
691  typedef std::map<std::string, std::string> amap_t;
692  amap_t aliasValues;
693 
695  static CLI* singleton;
696 
698  bool didParse;
699 
701  std::string programName;
702 
705 
707  friend class Timer;
708 
709  public:
712 
713  private:
720  static void AddAlias(const std::string& alias, const std::string& original);
721 
729  static std::string AliasReverseLookup(const std::string& value);
730 
731 #ifdef _WIN32
732 
737  void FileTimeToTimeVal(timeval* tv);
738 #endif
739 
745  static void RequiredOptions();
746 
754  static std::string SanitizeString(const std::string& str);
755 
759  static void UpdateGmap();
760 
764  CLI();
765 
771  CLI(const std::string& optionsName);
772 
774  CLI(const CLI& other);
775 };
776 
777 } // namespace mlpack
778 
779 // Include the actual definitions of templated methods
780 #include "cli_impl.hpp"
781 
782 #endif
std::map< std::string, ParamData > gmap_t
Map of global values.
Definition: cli.hpp:687
Linear algebra utility functions, generally performed on matrices or vectors.
boost::any value
The actual value of this parameter.
Definition: cli.hpp:391
std::list< std::string > requiredOptions
Pathnames of required options.
Definition: cli.hpp:684
amap_t aliasValues
Definition: cli.hpp:692
po::variables_map vmap
Values of the options given by user.
Definition: cli.hpp:681
std::string desc
Description of this parameter, if any.
Definition: cli.hpp:387
Timers timer
Holds the timer objects.
Definition: cli.hpp:704
bool isFlag
True if the wasPassed value should not be ignored.
Definition: cli.hpp:395
util::ProgramDoc * doc
Pointer to the ProgramDoc object.
Definition: cli.hpp:711
po::options_description desc
The documentation and names of options.
Definition: cli.hpp:678
std::string name
Name of this parameter.
Definition: cli.hpp:385
The timer class provides a way for mlpack methods to be timed.
Definition: timers.hpp:69
std::string programName
Hold the name of the program for –version.
Definition: cli.hpp:701
gmap_t globalValues
Definition: cli.hpp:688
Aids in the extensibility of CLI by focusing potential changes into one structure.
Definition: cli.hpp:382
static CLI * singleton
The singleton itself.
Definition: cli.hpp:695
bool didParse
True, if CLI was used to parse command line options.
Definition: cli.hpp:698
std::map< std::string, std::string > amap_t
Map for aliases, from alias to actual name.
Definition: cli.hpp:691
bool wasPassed
True if this parameter was passed in via command line or file.
Definition: cli.hpp:393
std::string tname
Type information of this parameter.
Definition: cli.hpp:389
A static object whose constructor registers program documentation with the CLI class.
Definition: option.hpp:82
Parses the command line for parameters and holds user-specified parameters.
Definition: cli.hpp:523