source/core/getopt.h

   1 #ifndef MSP_CORE_GETOPT_H_
   2 #define MSP_CORE_GETOPT_H_
   3
   4 #include <list>
   5 #include <stdexcept>
   6 #include <string>
   7 #include <vector>
   8 #include <msp/strings/lexicalcast.h>
   9
  10 namespace Msp {
  11
  12 class usage_error: public std::runtime_error
  13 {
  14 private:
  15         std::string help_;
  16
  17 public:
  18         usage_error(const std::string &w, const std::string &h = std::string()): std::runtime_error(w), help_(h) { }
  19         ~usage_error() throw() { }
  20
  21         const char *help() const throw() { return help_.c_str(); }
  22 };
  23
  24
  25 /**
  26 Command line option processor.  Both short and long options are supported, with
  27 optional and required arguments.  Automatic help text generation is also
  28 available.
  29
  30 Short options begin with a single dash and are identified by a single letter.
  31 Multiple short options may be grouped if they take no arguments; for example,
  32 the string "-abc" could be interpreted as having the options 'a', 'b' and 'c'.
  33 If the option takes an argument and there are unused characters in the argv
  34 element, then those characters are interpreted as the argument.  Otherwise the
  35 next element is taken as the argument.  An optional argument must be given in
  36 the same element.
  37
  38 Long options begin with a double dash and are identified by an arbitrary
  39 string.  An argument can be specified either in the same argv element,
  40 separated by an equals sign, or in the next element.  As with short options,
  41 an optional argument must be in the same element.
  42
  43 A single option may have both alternative forms, but must always have at least
  44 a long form.  This is to encourage self-documenting options; it's much easier
  45 to remember words than letters.
  46
  47 A built-in --help option is provided and will output a list of options and
  48 their associated help texts.  An application may override this by providing
  49 its own option with the same name.
  50 */
  51 class GetOpt
  52 {
  53 public:
  54         enum ArgType
  55         {
  56                 NO_ARG,
  57                 OPTIONAL_ARG,
  58                 REQUIRED_ARG
  59         };
  60
  61         class Option
  62         {
  63         protected:
  64                 Option() { }
  65         public:
  66                 virtual ~Option() { }
  67
  68                 /// Sets help text for the option.
  69                 virtual Option &set_help(const std::string &) = 0;
  70
  71                 /** Sets help text for the option, with a placeholder metavariable.  The
  72                 metavariable is used to denote the argument in the option list. */
  73                 virtual Option &set_help(const std::string &, const std::string &) = 0;
  74
  75                 virtual Option &bind_seen_count(unsigned &) = 0;
  76
  77                 /// Returns the number of times this option was seen on the command line.
  78                 virtual unsigned get_seen_count() const = 0;
  79         };
  80
  81 private:
  82         class OptBase: public Option
  83         {
  84         protected:
  85                 char shrt;
  86                 std::string lng;
  87                 ArgType arg_type;
  88                 unsigned seen_count;
  89                 unsigned *ext_seen_count;
  90                 std::string help;
  91                 std::string metavar;
  92
  93                 OptBase(char, const std::string &, ArgType);
  94         public:
  95                 virtual ~OptBase() { }
  96
  97                 virtual OptBase &set_help(const std::string &);
  98                 virtual OptBase &set_help(const std::string &, const std::string &);
  99                 virtual OptBase &bind_seen_count(unsigned &);
 100                 char get_short() const { return shrt; }
 101                 const std::string &get_long() const { return lng; }
 102                 ArgType get_arg_type() const { return arg_type; }
 103                 const std::string &get_help() const { return help; }
 104                 const std::string &get_metavar() const { return metavar; }
 105                 virtual unsigned get_seen_count() const { return seen_count; }
 106                 void process();
 107                 void process(const std::string &);
 108         protected:
 109                 virtual void store() = 0;
 110                 virtual void store(const std::string &) = 0;
 111         };
 112
 113         template<typename T>
 114         class SimpleOption: public OptBase
 115         {
 116         private:
 117                 T &data;
 118
 119         public:
 120                 SimpleOption(char s, const std::string &l, T &d, ArgType a): OptBase(s, l, a), data(d) { }
 121
 122                 virtual void store() { }
 123
 124                 virtual void store(const std::string &a)
 125                 { data = lexical_cast<T>(a); }
 126         };
 127
 128         template<typename T>
 129         class ListOption: public OptBase
 130         {
 131         private:
 132                 T &data;
 133
 134         public:
 135                 ListOption(char s, const std::string &l, T &d, ArgType a): OptBase(s, l, a), data(d)
 136                 { if(arg_type!=REQUIRED_ARG) throw std::invalid_argument("ListOption arg_type!=REQUIRED"); }
 137
 138                 virtual void store() { }
 139
 140                 virtual void store(const std::string &a)
 141                 { data.push_back(lexical_cast<typename T::value_type>(a)); }
 142         };
 143
 144         typedef std::list<OptBase *> OptionList;
 145
 146         bool help;
 147         OptionList opts;
 148         std::vector<std::string> args;
 149
 150 public:
 151         GetOpt();
 152         ~GetOpt();
 153
 154         /// Returns any non-option arguments encountered during processing.
 155         const std::vector<std::string> &get_args() const { return args; }
 156
 157         /** Adds an option with both short and long forms.  Processing depends on
 158         the type of the destination variable and whether an argument is taken or
 159         not.  With an argument, the value is lexical_cast to appropriate type and
 160         stored in the destination.  Without an argument, a bool will be set to true
 161         and an unsigned will be incremented; any other type will be ignored. */
 162         template<typename T>
 163         Option &add_option(char s, const std::string &l, T &d, ArgType a = NO_ARG)
 164         { return add_option(new SimpleOption<T>(s, l, d, a)); }
 165
 166         /** Adds an option with both short and long forms.  The option may be
 167         specified multiple times, and the argument from each occurrence is stored in
 168         the list.  The argument type must be REQUIRED_ARG. */
 169         template<typename T>
 170         Option &add_option(char s, const std::string &l, std::list<T> &d, ArgType a = REQUIRED_ARG)
 171         { return add_option(new ListOption<std::list<T> >(s, l, d, a)); }
 172
 173         /** Adds an option with only a long form. */
 174         template<typename T>
 175         Option &add_option(const std::string &l, T &d, ArgType a)
 176         { return add_option(0, l, d, a); }
 177
 178 private:
 179         OptBase &add_option(OptBase *);
 180
 181         OptBase &get_option(char);
 182         OptBase &get_option(const std::string &);
 183
 184 public:
 185         /** Processes argc/argv style command line arguments.  The contents of argv
 186         will be unchanged; use get_args to access non-option arguments. */
 187         void operator()(unsigned, const char *const *);
 188
 189 private:
 190         /** Processes a long option.  Returns the number of arguments eaten. */
 191         unsigned process_long(const char *const *);
 192
 193         /** Processes short options.  Returns the number of arguments eaten. */
 194         unsigned process_short(const char *const *);
 195
 196 public:
 197         /** Generates a single line that describes known options. */
 198         std::string generate_usage(const std::string &) const;
 199
 200         /** Generates help for known options in tabular format, one option per
 201         line.  The returned string will have a linefeed at the end. */
 202         std::string generate_help() const;
 203 };
 204
 205 template<> inline void GetOpt::SimpleOption<bool>::store()
 206 { data = true; }
 207
 208 template<> inline void GetOpt::SimpleOption<unsigned>::store()
 209 { ++data; }
 210
 211 template<> inline void GetOpt::SimpleOption<std::string>::store(const std::string &a)
 212 { data = a; }
 213
 214 template<> inline void GetOpt::ListOption<std::list<std::string> >::store(const std::string &a)
 215 { data.push_back(a); }
 216
 217 } // namespace Msp
 218
 219 #endif