DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
A Flexible UNIX Command Line Processing Facility - Args(3C++)

Keyword options

Options consisting of more than a single character are called ``keyword options''. For example, on my machine, in

       cc -dryrun -c foo.c

``dryrun'' is a keyword option. Keyword options, like single-character options, can take values:

       cc -align symbol -c foo.c

However, unlike single-character options, keyword options must be separated from their value by a space:

       cc -alignsymbol -c foo.c  // error!

Args makes it easy to specify the allowed set of keyword options:

       const char* keywords[] = {
           "dryrun",
           "align:",
           0
       };
       Args args(argc, argv, "co:OI:D;p",
           Args::intermix | Args::plusoptions, keywords);

The user simply places all the keyword options in a null-terminated list, and passes that list as an optional argument to the Args constructor. Notice that keywords options that take a value have an extra `:' at the end.

Specifying a string as a keyword option to Args causes any command line argument which matches that string (prefixed by a flag) to be treated as that keyword option, even if it consists of a sequence of legal single-character options. Thus,

       cc -dryrun foo.c

is treated as a keyword option, even if we were to specify `d', `r', `y', `u', and `n' as single-character options.

All Args functions that take an option character as an argument are overloaded to also take a (pointer to a) keyword:

       if (args.isset("dryrun")) // ...
       if (args.flag("align") == '-') // ...
       const char* symbol = args.value("align");

Args allows keyword options to take suboptions. They are specified using the same syntax as for non-keyword options:

       const char* keywords[] = {
           "foo;",
           // ...
       };
       main() {
           // ...
           const char* subval = args.subvalue("foo", "bar");
       }

When iterating over the options, the user can get a pointer to the keyword from the Opt object returned by the Optsiter:

       int dryrun = 0;
       extern void align(const char*);
       Optsiter oi(args);
       const Opt* opt;
       while (oi.next(opt)) {
           const char* key = opt->keyword();
           if (key != 0) {
               if (strcmp(key, "align") == 0)
                   align(opt->value());
               else
                   dryrun = 1;
           }
           else {
               // it's a single-character option
               // ...
           }
       }

Notice that keyword() returns the null pointer if the option is actually a single-character option. Similarly, if the option is a keyword option, then opt->chr() returns '\0'.


Next topic: Invocation errors
Previous topic: `+' options

© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 27 April 2004