Descriptor Struct Reference

Detailed Description

Describes an option, its help text (usage) and how it should be parsed.

The main input when constructing an option::Parser is an array of Descriptors.

Example:

enum OptionIndex {CREATE, ...};
enum OptionType {DISABLE, ENABLE, OTHER};

const option::Descriptor usage[] = {
  { CREATE,                                            // index
    OTHER,                                             // type
    "c",                                               // shortopt
    "create",                                          // longopt
    Arg::None,                                         // check_arg
    "--create  Tells the program to create something." // help
  }
  , ...
};

Definition at line 315 of file optionparser.h.

Public Attributes
const unsigned	index
	Index of this option's linked list in the array filled in by the parser. More...
const int	type
	Used to distinguish between options with the same index. See index for details. More...
const char *const	shortopt
	Each char in this string will be accepted as a short option character. More...
const char *const	longopt
	The long option name (without the leading – ). More...
const CheckArg	check_arg
	For each option that matches shortopt or longopt this function will be called to check a potential argument to the option. More...
const char *	help
	The usage text associated with the options in this Descriptor. More...

Member Data Documentation

const CheckArg check_arg

For each option that matches shortopt or longopt this function will be called to check a potential argument to the option.

This function will be called even if there is no potential argument. In that case it will be passed NULL as arg parameter. Do not confuse this with the empty string.

See CheckArg for more information.

Definition at line 405 of file optionparser.h.

const char* help

The usage text associated with the options in this Descriptor.

You can use option::printUsage() to format your usage message based on the help texts. You can use dummy Descriptors where shortopt and longopt are both the empty string to add text to the usage that is not related to a specific option.

See option::printUsage() for special formatting characters you can use in help to get a column layout.

Attention

Must be UTF-8-encoded. If your compiler supports C++11 you can use the "u8" prefix to make sure string literals are properly encoded.

Definition at line 422 of file optionparser.h.

const unsigned index

Index of this option's linked list in the array filled in by the parser.

Command line options whose Descriptors have the same index will end up in the same linked list in the order in which they appear on the command line. If you have multiple long option aliases that refer to the same option, give their descriptors the same index.

If you have options that mean exactly opposite things (e.g. –enable-foo and –disable-foo ), you should also give them the same index, but distinguish them through different values for type. That way they end up in the same list and you can just take the last element of the list and use its type. This way you get the usual behaviour where switches later on the command line override earlier ones without having to code it manually.

Tip:

Use an enum rather than plain ints for better readability, as shown in the example at Descriptor.

Definition at line 336 of file optionparser.h.

const char* const longopt

The long option name (without the leading – ).

If this Descriptor should not have a long option name, use the empty string "". NULL is not permitted here!

While shortopt allows multiple short option characters, each Descriptor can have only a single long option name. If you have multiple long option names referring to the same option use separate Descriptors that have the same index and type. You may repeat short option characters in such an alias Descriptor but there's no need to.

Dummy Descriptors:

You can use dummy Descriptors with an empty string for both shortopt and longopt to add text to the usage that is not related to a specific option. See help. The first dummy Descriptor will be used for unknown options (see below).

Unknown Option Descriptor:

The first dummy Descriptor in the list of Descriptors, whose shortopt and longopt are both the empty string, will be used as the Descriptor for unknown options. An unknown option is a string in the argument vector that is not a lone minus '-' but starts with a minus character and does not match any Descriptor's shortopt or longopt.
Note that the dummy descriptor's check_arg function will be called and its return value will be evaluated as usual. I.e. if it returns ARG_ILLEGAL the parsing will be aborted with Parser::error()==true.
if check_arg does not return ARG_ILLEGAL the descriptor's index will be used to pick the linked list into which to put the unknown option.
If there is no dummy descriptor, unknown options will be dropped silently.

Definition at line 393 of file optionparser.h.

const char* const shortopt

Each char in this string will be accepted as a short option character.

The string must not include the minus character '-' or you'll get undefined behaviour.

If this Descriptor should not have short option characters, use the empty string "". NULL is not permitted here!

See longopt for more information.

Definition at line 358 of file optionparser.h.

const int type

Used to distinguish between options with the same index. See index for details.

It is recommended that you use an enum rather than a plain int to make your code more readable.

Definition at line 345 of file optionparser.h.

---

The documentation for this struct was generated from the following file:

• src/optionparser.h