parse command-line options More...

#include <options.hpp>

Public Types
enum	OptCtrl { OptCtrl::DEFAULT, OptCtrl::ANYCASE, OptCtrl::QUIET, OptCtrl::PLUS, OptCtrl::SHORT_ONLY, OptCtrl::LONG_ONLY, OptCtrl::NOGUESSING, OptCtrl::PARSE_POS }

enum	OptRC { ENDOPTS, BADCHAR, BADKWD, AMBIGUOUS, POSITIONAL }

Public Member Functions
	Options (const char name, const char const optv[])

const char *	name (void) const
	name() returns the command name

unsigned	ctrls (void) const
	ctrls() (with no arguments) returns the existing control settings

void	ctrls (unsigned newctrls)
	ctrls() (with 1 argument) sets new control settings

void	reset (void)
	reset for another pass to parse for options

void	usage (std::ostream &os, const char *positionals) const

int	operator() (OptIter &iter, const char *&optarg)

int	explicit_endopts () const

Detailed Description

parse command-line options

Synopsis

#include <options.h>
Options opts(cmdname, optv);
char cmdname[], *optv[];

Description

The Options constructor expects a command-name (usually argv[0]) and a pointer to an array of strings. The last element in this array MUST be NULL. Each non-NULL string in the array must have the following format:

The 1st character must be the option-name ('c' for a -c option).

The 2nd character must be one of '|', '?', ':', '*', or '+'. '|' – indicates that the option takes NO argument; '?' – indicates that the option takes an OPTIONAL argument; ':' – indicates that the option takes a REQUIRED argument; '*' – indicates that the option takes 0 or more arguments; '+' – indicates that the option takes 1 or more arguments;

The remainder of the string must be the long-option name.

If desired, the long-option name may be followed by one or more spaces and then by the name of the option value. This name will be used when printing usage messages. If the option-value-name is not given then the string "<value>" will be used in usage messages.

One may use a space to indicate that a particular option does not have a corresponding long-option. For example, "c: " (or "c:") means the -c option takes a value & has NO corresponding long-option.

To specify a long-option that has no corresponding single-character option is a bit trickier: Options::operator() still needs an "option- character" to return when that option is matched. One may use a whitespace character or a non-printable character as the single-character option in such a case. (hence " |hello" would only match "--hello").

Exceptions to the above

If the 1st character of the string is '-', then the rest of the string must correspond to the above format, and the option is considered to be a hidden-option. This means it will be parsed when actually matching options from the command-line, but will NOT show-up if a usage message is printed using the usage() member function. Such an example might be "-h|hidden". If you want to use any "dummy" options (options that are not parsed, but that to show up in the usage message), you can specify them along with any positional parameters to the usage() member function.

If the 2nd character of the string is '\0' then it is assumed that there is no corresponding long-option and that the option takes no argument (hence "f", and "f| " are equivalent).

const char * optv[] = {
    "c:count   <number>",
    "s?str     <string>",
    "x",
    " |hello",
    "g+groups  <newsgroup>",
    NULL
} ;

optv[] now corresponds to the following:

  usage: cmdname [-c|--count <number>] [-s|--str [<string>]]
                 [-x] [--hello] [-g|--groups <newsgroup> ...]

Long-option names are matched case-insensitive and only a unique prefix of the name needs to be specified.

Option-name characters are case-sensitive!

Caveat

Because of the way in which multi-valued options and options with optional values are handled, it is NOT possible to supply a value to an option in a separate argument (different argv[] element) if the value is OPTIONAL and begins with a '-'. What this means is that if an option "-s" takes an optional value value and you wish to supply a value of "-foo" then you must specify this on the command-line as "-s-foo" instead of "-s -foo" because "-s -foo" will be considered to be two separate sets of options.

A multi-valued option is terminated by another option or by the end-of options. The following are all equivalent (if "-l" is a multi-valued option and "-x" is an option that takes no value):

cmdname -x -l item1 item2 item3 – arg1 arg2 arg3 cmdname -x -litem1 -litem2 -litem3 – arg1 arg2 arg3 cmdname -l item1 item2 item3 -x arg1 arg2 arg3

#include <options.h>
static const char * optv[] = {
   "H|help",
   "c:count   <number>",
   "s?str     <string>",
   "x",
   " |hello",
   "g+groups  <newsgroup>",
   NULL
} ;
main(int argc, char * argv[]) {
   int  optchar;
   const char * optarg;
   const char * str = "default_string";
   int  count = 0, xflag = 0, hello = 0;
   int  errors = 0, ngroups = 0;
   Options  opts(*argv, optv);
   OptArgvIter  iter(--argc, ++argv);
   while( optchar = opts(iter, optarg) ) {
      switch (optchar) {
      case 'H' :
         opts.usage(cout, "files ...");
         exit(0);
         break;
      case 'g' :
         ++ngroups; break;  
      case 's' :
         str = optarg; break;
      case 'x' :
         ++xflag; break;
      case ' ' :
         ++hello; break;
      case 'c' :
         if (optarg == NULL)  ++errors;
         else  count = (int) atol(optarg);
         break;
      default :  ++errors; break;
      } 
   }
   if (errors || (iter.index() == argc)) {
      if (! errors) {
         cerr << opts.name() << ": no filenames given." << endl ;
      }
      opts.usage(cerr, "files ...");
      exit(1);
   }
   cout << "xflag=" << ((xflag) ? "ON"  : "OFF") << endl
        << "hello=" << ((hello) ? "YES" : "NO") << endl
        << "count=" << count << endl
        << "str=\"" << ((str) ? str : "No value given!") << "\"" << endl
        << "ngroups=" << ngroups << endl ;
   if (iter.index() < argc) {
      cout << "files=" ;
      for (int i = iter.index() ; i < argc ; i++) {
         cout << "\"" << argv[i] << "\" " ;
      }
      cout << endl ;
   }
}

Member Enumeration Documentation

enum Options::OptCtrl

strong

Enumerator
DEFAULT	Default setting.
ANYCASE	Ignore case when matching short-options.
QUIET	Don't print error messages.
PLUS	Allow "+" as a long-option prefix.
SHORT_ONLY	Don't accept long-options.
LONG_ONLY	Don't accept short-options (also allows "-" as a long-option prefix).
NOGUESSING	Normally, when we see a short (long) option on the command line that doesn't match any known short (long) options, then we try to "guess" by seeing if it will match any known long (short) option. Setting this mask prevents this "guessing" from occurring.
PARSE_POS	By default, Options will not present positional command-line arguments to the user and will instead stop parsing when the first positional argument has been encountered. If this flag is given, Options will present positional arguments to the user with a return code of POSITIONAL; ENDOPTS will be returned only when the end of the argument list is reached.

enum Options::OptRC

strong

Error return values for operator()

Member Function Documentation

int Options::explicit_endopts ( ) const

inline

Call this member function after operator() has returned 0 if you want to know whether or not options were explicitly terminated because "--" appeared on the command-line.

int Options::operator()	(	OptIter &	iter,
		const char *&	optarg
	)

operator() iterates through the arguments as necessary (using the given iterator) and returns the character value of the option (or long-option) that it matched. If the option has a value then the value given may be found in optarg (otherwise optarg will be NULL).

0 is returned upon end-of-options. At this point, "iter" may be used to process any remaining positional parameters. If the PARSE_POS control-flag is set then 0 is returned only when all arguments in "iter" have been exhausted.

If an invalid option is found then BADCHAR is returned and *optarg is the unrecognized option character.

If an invalid long-option is found then BADKWD is returned and optarg points to the bad long-option.

If an ambiguous long-option is found then AMBIGUOUS is returned and optarg points to the ambiguous long-option.

If the PARSE_POS control-flag is set then POSITIONAL is returned when a positional argument is encountered and optarg points to the positonal argument (and "iter" is advanced to the next argument in the iterator).

Unless Options::OptCtrl::QUIET is used, missing option-arguments and invalid options (and the like) will automatically cause error messages to be issued to cerr.

void Options::usage	(	std::ostream &	os,
		const char *	positionals
	)		const

usage() prints options usage (followed by any positional arguments listed in the parameter "positionals") on the given outstream

The documentation for this class was generated from the following files:

options.hpp
options.cpp

Public Types