The Option Parsing Library  0.2.0
Data Fields
opt_t Struct Reference

represents an element of an option description table. More...

#include <opt.h>

Data Fields

char * lopt
int sopt
int * flag
int arg

Detailed Description

represents an element of an option description table.

opt_t represents an element of an option description table that is used for a user program to specify options and their properties. A option description table is an array of opt_t, each element of which is consisted of four members, two of which have overloaded meanings:

To mark an end of the table, the lopt member of the last element has to be set to a null pointer. If the flag member points to a flag variable, the pointed integer object is initalized to be 0 by opt_init().

For OPT_TYPE_INT and OPT_TYPE_UINT, the conversion of a given option-argument recognizes the C-style prefixes; numbers starting with 0 are treated as octal, and those with 0x or 0X are treated as hexadecimal.

Some examples follow:

      opt_t options[] = {
          { "verbose", 'v', &option_verbose, 1 },
          { "brief",   'b', &option_verbose, 0 },
          { NULL, }
      };

This example says that two options ("--verbose" or "-v" and "--brief" or "-b") are recognized and option_verbose is set to 1 when "--verbose" or "-v" given, and set to 0 when "--brief" or "-b" given.

      opt_t options[] = {
          "version",  'v',         OPT_ARG_NO, OPT_TYPE_NO,
          "help",     UCHAR_MAX+1, OPT_ARG_NO, OPT_TYPE_NO,
          "morehelp", UCHAR_MAX+2, OPT_ARG_NO, OPT_TYPE_NO,
          NULL,
      };

This example shows options that do not take any additional arguments. Setting the flag member to a null pointer also says the option takes no argument in which case the value of the arg member ignored. Thus, the above example can be written as follows without any change on the behavior:

      opt_t options[] = {
          "version",  'v',         NULL, 0,
          "help",     UCHAR_MAX+1, NULL, 0,
          "morehelp", UCHAR_MAX+2, NULL, 0,
          NULL,
      };

where you can put any integer in the place of 0. The former is preferred, however, since it shows more explicitly the fact that no additional arguments consumed after each of the options.

When only long-named options need to be provided without introducing flag variables, values from UCHAR_MAX+1 to INT_MAX (inclusive) can be used for the sopt member; both are defined in <limits.h>. (Even if the C standard does not require UCHAR_MAX less than INT_MAX, many parts of C, especially, of the standard library cannot work correctly without such a relationship on a hosted implementation.)

      opt_t options[] = {
          "",   'x', OPT_ARG_NO, OPT_TYPE_NO,
          NULL,
      };

On the other hand, providing an empty string for the lopt member as in this example can specify that an option is only short-named. Note that, however, this is discouraged; long-named options are much more user-friendly especially for novices.

      opt_t options[] = {
          "input", 'i', OPT_ARG_REQ, OPT_TYPE_STR,
          "port",  'p', OPT_ARG_REQ, OPT_TYPE_UINT,
          "start", 's', OPT_ARG_REQ, OPT_TYPE_REAL,
          "end",   'e', OPT_ARG_REQ, OPT_TYPE_REAL,
          NULL,
      };

This example shows options that take additional arguments. OPT_ARG_REQ for the flag member specifies that the option requires an option-argument and that the type of the argument is given in the arg member. For OPT_TYPE_INT, OPT_TYPE_UINT and OPT_TYPE_REAL, strtol(), strtoul() and strtod() are respectively used to convert option-arguments.

      opt_t options[] = {
          "negative", 'n', OPT_ARG_OPT, OPT_TYPE_REAL,
          NULL,
      };

This table specifies the option "--negative" or "-n" takes an optionally given argument. If an option-argument with the expected form (which is determined by strtod() in this case) follows the option, it is taken. If there is no argument, or is an argument but has no expected form, the option works as if OPT_ARG_OPT and OPT_TYPE_REAL are replaced by OPT_ARG_NO and OPT_TYPE_NO.

The following examples show how to control the ordering mode.

      opt_t options[] = {
          "+", 0, OPT_ARG_NO, OPT_TYPE_NO,
          ...
          NULL,
      };

Setting the first long-named option to "+" or setting the environment variable named POSIXLY_CORRECT says option processing performed by opt_parse() immediately stops whenever an operand encountered (which POSIX requires).

      opt_t options[] = {
          "-", 0, OPT_ARG_NO, OPT_TYPE_NO,
          ...
          NULL,
      };

In addition, setting the first long-named option to "-" makes opt_parse() returns the character valued 1 when encounters an operand as if the operand is an option-argument for the option whose short name has the value 1.


Field Documentation

value for flag variable or type of additional argument

pointer to flag varible or information about additional argument

char* opt_t::lopt

long-named option (optional for some cases)

short-named option (optional for some cases)


The documentation for this struct was generated from the following file:
 All Data Structures Files Functions Variables Enumerator Defines