manual/examples/argp-ex3.c

   1 /* Argp example #3 -- a program with options and arguments using argp */
   2
   3 /* This program uses the same features as example 2, and uses options and
   4    arguments.
   5
   6    We now use the first four fields in ARGP, so here's a description of them:
   7      OPTIONS  -- A pointer to a vector of struct argp_option (see below)
   8      PARSER   -- A function to parse a single option, called by argp
   9      ARGS_DOC -- A string describing how the non-option arguments should look
  10      DOC      -- A descriptive string about this program; if it contains a
  11                  vertical tab character (\v), the part after it will be
  12                  printed *following* the options
  13
  14    The function PARSER takes the following arguments:
  15      KEY  -- An integer specifying which option this is (taken
  16              from the KEY field in each struct argp_option), or
  17              a special key specifying something else; the only
  18              special keys we use here are ARGP_KEY_ARG, meaning
  19              a non-option argument, and ARGP_KEY_END, meaning
  20              that all arguments have been parsed
  21      ARG  -- For an option KEY, the string value of its
  22              argument, or NULL if it has none
  23      STATE-- A pointer to a struct argp_state, containing
  24              various useful information about the parsing state; used here
  25              are the INPUT field, which reflects the INPUT argument to
  26              argp_parse, and the ARG_NUM field, which is the number of the
  27              current non-option argument being parsed
  28    It should return either 0, meaning success, ARGP_ERR_UNKNOWN, meaning the
  29    given KEY wasn't recognized, or an errno value indicating some other
  30    error.
  31
  32    Note that in this example, main uses a structure to communicate with the
  33    parse_opt function, a pointer to which it passes in the INPUT argument to
  34    argp_parse.  Of course, it's also possible to use global variables
  35    instead, but this is somewhat more flexible.
  36
  37    The OPTIONS field contains a pointer to a vector of struct argp_option's;
  38    that structure has the following fields (if you assign your option
  39    structures using array initialization like this example, unspecified
  40    fields will be defaulted to 0, and need not be specified):
  41      NAME   -- The name of this option's long option (may be zero)
  42      KEY    -- The KEY to pass to the PARSER function when parsing this option,
  43                *and* the name of this option's short option, if it is a
  44                printable ascii character
  45      ARG    -- The name of this option's argument, if any
  46      FLAGS  -- Flags describing this option; some of them are:
  47                  OPTION_ARG_OPTIONAL -- The argument to this option is optional
  48                  OPTION_ALIAS        -- This option is an alias for the
  49                                         previous option
  50                  OPTION_HIDDEN       -- Don't show this option in --help output
  51      DOC    -- A documentation string for this option, shown in --help output
  52
  53    An options vector should be terminated by an option with all fields zero. */
  54
  55 #include <argp.h>
  56
  57 const char *argp_program_version =
  58   "argp-ex3 1.0";
  59 const char *argp_program_bug_address =
  60   "<bug-gnu-utils@@gnu.org>";
  61
  62 /* Program documentation.  */
  63 static char doc[] =
  64   "Argp example #3 -- a program with options and arguments using argp";
  65
  66 /* A description of the arguments we accept.  */
  67 static char args_doc[] = "ARG1 ARG2";
  68
  69 /* The options we understand.  */
  70 static struct argp_option options[] = {
  71   {"verbose",  'v', 0,      0,  "Produce verbose output" },
  72   {"quiet",    'q', 0,      0,  "Don't produce any output" },
  73   {"silent",   's', 0,      OPTION_ALIAS },
  74   {"output",   'o', "FILE", 0,
  75    "Output to FILE instead of standard output" },
  76   { 0 }
  77 };
  78
  79 /* Used by @code{main} to communicate with @code{parse_opt}.  */
  80 struct arguments
  81 {
  82   char *args[2];                /* @var{arg1} & @var{arg2} */
  83   int silent, verbose;
  84   char *output_file;
  85 };
  86
  87 /* Parse a single option.  */
  88 static error_t
  89 parse_opt (int key, char *arg, struct argp_state *state)
  90 {
  91   /* Get the @var{input} argument from @code{argp_parse}, which we
  92      know is a pointer to our arguments structure.  */
  93   struct arguments *arguments = state->input;
  94
  95   switch (key)
  96     {
  97     case 'q': case 's':
  98       arguments->silent = 1;
  99       break;
 100     case 'v':
 101       arguments->verbose = 1;
 102       break;
 103     case 'o':
 104       arguments->output_file = arg;
 105       break;
 106
 107     case ARGP_KEY_ARG:
 108       if (state->arg_num >= 2)
 109         /* Too many arguments.  */
 110         argp_usage (state);
 111
 112       arguments->args[state->arg_num] = arg;
 113
 114       break;
 115
 116     case ARGP_KEY_END:
 117       if (state->arg_num < 2)
 118         /* Not enough arguments.  */
 119         argp_usage (state);
 120       break;
 121
 122     default:
 123       return ARGP_ERR_UNKNOWN;
 124     }
 125   return 0;
 126 }
 127
 128 /* Our argp parser.  */
 129 static struct argp argp = { options, parse_opt, args_doc, doc };
 130
 131 int main (int argc, char **argv)
 132 {
 133   struct arguments arguments;
 134
 135   /* Default values.  */
 136   arguments.silent = 0;
 137   arguments.verbose = 0;
 138   arguments.output_file = "-";
 139
 140   /* Parse our arguments; every option seen by @code{parse_opt} will
 141      be reflected in @code{arguments}.  */
 142   argp_parse (&argp, argc, argv, 0, 0, &arguments);
 143
 144   printf ("ARG1 = %s\nARG2 = %s\nOUTPUT_FILE = %s\n"
 145           "VERBOSE = %s\nSILENT = %s\n",
 146           arguments.args[0], arguments.args[1],
 147           arguments.output_file,
 148           arguments.verbose ? "yes" : "no",
 149           arguments.silent ? "yes" : "no");
 150
 151   exit (0);
 152 }