X-Git-Url: http://git.tdb.fi/?p=libs%2Fcore.git;a=blobdiff_plain;f=source%2Fcore%2Fgetopt.h;h=2aaceef836730aa24a966c3cfaa20bb9864e23a7;hp=d3369c6b46fdf57b392b5a8dc56507fc6b79a773;hb=9f8d6a18f68fb54b62e9f4a5cf1a1650282b3667;hpb=bc08f0a03c75627427b19e3f821642931ba60b33

diff --git a/source/core/getopt.h b/source/core/getopt.h
index d3369c6..2aaceef 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,16 @@ 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;
+
+		virtual Option &bind_seen_count(unsigned &) = 0;
+
+		/// Returns the number of times this option was seen on the command line.
 		virtual unsigned get_seen_count() const = 0;
 	};
 
@@ -52,6 +86,7 @@ private:
 		std::string lng;
 		ArgType arg_type;
 		unsigned seen_count;
+		unsigned *ext_seen_count;
 		std::string help;
 		std::string metavar;
 
@@ -61,6 +96,7 @@ private:
 
 		virtual OptBase &set_help(const std::string &);
 		virtual OptBase &set_help(const std::string &, const std::string &);
+		virtual OptBase &bind_seen_count(unsigned &);
 		char get_short() const { return shrt; }
 		const std::string &get_long() const { return lng; }
 		ArgType get_arg_type() const { return arg_type; }
@@ -131,16 +167,26 @@ public:
 	GetOpt();
 	~GetOpt();
 
+	/// Returns any non-option arguments encountered during processing.
 	const std::vector<std::string> &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<typename T>
 	Option &add_option(char s, const std::string &l, T &d, ArgType a = NO_ARG)
 	{ return add_option(new SimpleOption<T>(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<typename T>
 	Option &add_option(char s, const std::string &l, std::list<T> &d, ArgType a = REQUIRED_ARG)
 	{ return add_option(new ListOption<std::list<T> >(s, l, d, a)); }
-	
+
+	/** Adds an option with only a long form. */
 	template<typename T>
 	Option &add_option(const std::string &l, T &d, ArgType a)
 	{ return add_option(0, l, d, a); }