doc/argmatch.texi

   1 @node Recognizing Option Arguments
   2 @section Recognizing Option Arguments
   3
   4 The module @samp{argmatch} provides a simple textual user interface to a
   5 finite choice.  It is for example well suited to recognize arguments of
   6 options or values of environment variables that accept a fixed set of valid
   7 choices.
   8
   9 These choices may be denoted by synonyms, such as `none' and `off' below.
  10
  11 @smallexample
  12 $ @kbd{my_cp --backup=none foo bar}
  13 $ @kbd{my_cp --backup=non foo bar}
  14 $ @kbd{my_cp --backup=no foo bar}
  15 $ @kbd{my_cp --backup=n foo bar}
  16 my_cp: ambiguous argument 'n' for 'backup type'
  17 Valid arguments are:
  18   - 'no', 'none', 'off'
  19   - 'numbered', 't', 'newstyle'
  20   - 'existing', 'nil', 'numbered-existing'
  21   - 'simple', 'never', 'single'
  22 Try 'my_cp --help' for more information.
  23 $ @kbd{my_cp --backup=num foo bar}
  24 $ @kbd{my_cp --backup=true foo bar}
  25 my_cp: invalid argument 'true' for 'backup type'
  26 Valid arguments are:
  27   - 'no', 'none', 'off'
  28   - 'numbered', 't', 'newstyle'
  29   - 'existing', 'nil', 'numbered-existing'
  30   - 'simple', 'never', 'single'
  31 Try 'my_cp --help' for more information.
  32 @end smallexample
  33
  34 To set up @code{argmatch}, first call @samp{ARGMATCH_DEFINE_GROUP
  35 (@var{name}, @var{type})} with the name of the argmatch group name, and the
  36 value type.  For instance:
  37
  38 @smallexample
  39 enum backup_type
  40 @{
  41   no_backups,
  42   simple_backups,
  43   numbered_existing_backups,
  44   numbered_backups
  45 @};
  46
  47 ARGMATCH_DEFINE_GROUP (backup, enum backup_type);
  48 @end smallexample
  49
  50 @noindent
  51 This defines a few types and functions named @code{argmatch_@var{name}_*}.
  52 Introduce the array that defines the mapping from user-input to actual
  53 value, with a terminator:
  54
  55 @example
  56 static const argmatch_backup_arg argmatch_backup_args[] =
  57 @{
  58   @{ "no",                no_backups @},
  59   @{ "none",              no_backups @},
  60   @{ "off",               no_backups @},
  61   @{ "simple",            simple_backups @},
  62   @{ "never",             simple_backups @},
  63   @{ "single",            simple_backups @},
  64   @{ "existing",          numbered_existing_backups @},
  65   @{ "nil",               numbered_existing_backups @},
  66   @{ "numbered-existing", numbered_existing_backups @},
  67   @{ "numbered",          numbered_backups @},
  68   @{ "t",                 numbered_backups @},
  69   @{ "newstyle",          numbered_backups @},
  70   @{ NULL, no_backups @}
  71 @};
  72 @end example
  73
  74 @noindent
  75 Then introduce the array that defines the values, also with a terminator.
  76 Document only once per group of synonyms:
  77
  78 @example
  79 static const argmatch_backup_doc argmatch_backup_docs[] =
  80 @{
  81   @{ "no",       N_("never make backups (even if --backup is given)") @},
  82   @{ "numbered", N_("make numbered backups") @},
  83   @{ "existing", N_("numbered if numbered backups exist, simple otherwise") @},
  84   @{ "simple",   N_("always make simple backups") @},
  85   @{ NULL, NULL @}
  86 @};
  87 @end example
  88
  89 @noindent
  90 Finally, define the argmatch group:
  91
  92 @example
  93 const argmatch_backup_group_type argmatch_backup_group =
  94 @{
  95   argmatch_backup_args,
  96   argmatch_backup_docs,
  97   N_("\
  98 The backup suffix is '~', unless set with --suffix or SIMPLE_BACKUP_SUFFIX.\n\
  99 The version control method may be selected via the --backup option or through\n\
 100 the VERSION_CONTROL environment variable.  Here are the values:\n"),
 101   NULL
 102 @};
 103 @end example
 104
 105 @sp 1
 106
 107 To use the argmatch group:
 108
 109 @smallexample
 110 ptrdiff_t i = argmatch_backup_choice ("--backup", "none");
 111 // argmatch_backup_group.args[i].arg is "none", so its value
 112 // is argmatch_backup_group.args[i].val.
 113 // Return -1 on invalid argument, and -2 on ambiguity.
 114
 115 enum backup_type val = *argmatch_backup_value ("--backup", "none");
 116 // Returns a pointer to the value, and exit on errors.
 117 // So argmatch_backup_group.args[i].val == val.
 118
 119 const char *arg = argmatch_backup_argument (&no_backups);
 120 // arg is "no".
 121
 122 // Print the documentation on stdout.
 123 argmatch_backup_usage (stdout);
 124 // Gives:
 125 //
 126 // The backup suffix is '~', unless set with --suffix or SIMPLE_BACKUP_SUFFIX.
 127 // The version control method may be selected via the --backup option or through
 128 // the VERSION_CONTROL environment variable.  Here are the values:
 129 //
 130 //   no, none, off  never make backups (even if --backup is given)
 131 //   numbered, t, newstyle
 132 //                  make numbered backups
 133 //   existing, nil, numbered-existing
 134 //                  numbered if numbered backups exist, simple otherwise
 135 //   simple, never, single
 136 //                  always make simple backups
 137 @end smallexample