From: Mikko Rasa Date: Sat, 14 Jul 2012 15:21:00 +0000 (+0300) Subject: Add documentation to GetOpt X-Git-Url: http://git.tdb.fi/?a=commitdiff_plain;h=03d324e20b1062fbc9a6b60106b370c7194a6141;p=libs%2Fcore.git Add documentation to GetOpt --- diff --git a/source/core/getopt.h b/source/core/getopt.h index d3369c6..dbc0f9c 100644 --- a/source/core/getopt.h +++ b/source/core/getopt.h @@ -22,6 +22,32 @@ public: }; +/** +Command line option processor. Both short and long options are supported, with +optional and required arguments. Automatic help text generation is also +available. + +Short options begin with a single dash and are identified by a single letter. +Multiple short options may be grouped if they take no arguments; for example, +the string "-abc" could be interpreted as having the options 'a', 'b' and 'c'. +If the option takes an argument and there are unused characters in the argv +element, then those characters are interpreted as the argument. Otherwise the +next element is taken as the argument. An optional argument must be given in +the same element. + +Long options begin with a double dash and are identified by an arbitrary +string. An argument can be specified either in the same argv element, +separated by an equals sign, or in the next element. As with short options, +an optional argument must be in the same element. + +A single option may have both alternative forms, but must always have at least +a long form. This is to encourage self-documenting options; it's much easier +to remember words than letters. + +A built-in --help option is provided and will output a list of options and +their associated help texts. An application may override this by providing +its own option with the same name. +*/ class GetOpt { public: @@ -31,7 +57,7 @@ public: OPTIONAL_ARG, REQUIRED_ARG }; - + class Option { protected: @@ -39,8 +65,14 @@ public: public: virtual ~Option() { } + /// Sets help text for the option. virtual Option &set_help(const std::string &) = 0; + + /** Sets help text for the option, with a placeholder metavariable. The + metavariable is used to denote the argument in the option list. */ virtual Option &set_help(const std::string &, const std::string &) = 0; + + /// Returns the number of times this option was seen on the command line. virtual unsigned get_seen_count() const = 0; }; @@ -131,16 +163,26 @@ public: GetOpt(); ~GetOpt(); + /// Returns any non-option arguments encountered during processing. const std::vector &get_args() const { return args; } + /** Adds an option with both short and long forms. Processing depends on + the type of the destination variable and whether an argument is taken or + not. With an argument, the value is lexical_cast to appropriate type and + stored in the destination. Without an argument, a bool will be set to true + and an unsigned will be incremented; any other type will be ignored. */ template Option &add_option(char s, const std::string &l, T &d, ArgType a = NO_ARG) { return add_option(new SimpleOption(s, l, d, a)); } - + + /** Adds an option with both short and long forms. The option may be + specified multiple times, and the argument from each occurrence is stored in + the list. The argument type must be REQUIRED_ARG. */ template Option &add_option(char s, const std::string &l, std::list &d, ArgType a = REQUIRED_ARG) { return add_option(new ListOption >(s, l, d, a)); } - + + /** Adds an option with only a long form. */ template Option &add_option(const std::string &l, T &d, ArgType a) { return add_option(0, l, d, a); }