lib/argmatch.h

   1 /* argmatch.h -- definitions and prototypes for argmatch.c
   2
   3    Copyright (C) 1990, 1998-1999, 2001-2002, 2004-2005, 2009-2024 Free Software
   4    Foundation, Inc.
   5
   6    This program is free software: you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation, either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  18
  19 /* Written by David MacKenzie <djm@ai.mit.edu>
  20    Modified by Akim Demaille <demaille@inf.enst.fr> */
  21
  22 #ifndef ARGMATCH_H_
  23 # define ARGMATCH_H_ 1
  24
  25 /* This file uses _GL_ATTRIBUTE_PURE.  */
  26 # if !_GL_CONFIG_H_INCLUDED
  27 #  error "Please include config.h first."
  28 # endif
  29
  30 # include <limits.h>
  31 # include <stddef.h>
  32 # include <stdio.h>
  33 # include <string.h> /* memcmp */
  34
  35 # include "gettext.h"
  36 # include "quote.h"
  37
  38 # ifdef  __cplusplus
  39 extern "C" {
  40 # endif
  41
  42 # define ARRAY_CARDINALITY(Array) (sizeof (Array) / sizeof *(Array))
  43
  44 /* Assert there are as many real arguments as there are values
  45    (argument list ends with a NULL guard).  */
  46
  47 # define ARGMATCH_VERIFY(Arglist, Vallist) \
  48     static_assert (ARRAY_CARDINALITY (Arglist) \
  49                    == ARRAY_CARDINALITY (Vallist) + 1)
  50
  51 /* Return the index of the element of ARGLIST (NULL terminated) that
  52    matches with ARG.  If VALLIST is not NULL, then use it to resolve
  53    false ambiguities (i.e., different matches of ARG but corresponding
  54    to the same values in VALLIST).  */
  55
  56 ptrdiff_t argmatch (char const *arg, char const *const *arglist,
  57                     void const *vallist, size_t valsize) _GL_ATTRIBUTE_PURE;
  58
  59 ptrdiff_t argmatch_exact (char const *arg, char const *const *arglist)
  60   _GL_ATTRIBUTE_PURE;
  61
  62 # define ARGMATCH(Arg, Arglist, Vallist) \
  63   argmatch (Arg, Arglist, (void const *) (Vallist), sizeof *(Vallist))
  64
  65 # define ARGMATCH_EXACT(Arg, Arglist) \
  66   argmatch_exact (Arg, Arglist)
  67
  68 /* xargmatch calls this function when it fails.  This function should not
  69    return.  By default, this is a function that calls ARGMATCH_DIE which
  70    in turn defaults to 'exit (exit_failure)'.  */
  71 typedef void (*argmatch_exit_fn) (void);
  72 extern argmatch_exit_fn argmatch_die;
  73
  74 /* Report on stderr why argmatch failed.  Report correct values. */
  75
  76 void argmatch_invalid (char const *context, char const *value,
  77                        ptrdiff_t problem);
  78
  79 /* Left for compatibility with the old name invalid_arg */
  80
  81 # define invalid_arg(Context, Value, Problem) \
  82   argmatch_invalid (Context, Value, Problem)
  83
  84
  85
  86 /* Report on stderr the list of possible arguments.  */
  87
  88 void argmatch_valid (char const *const *arglist,
  89                      void const *vallist, size_t valsize);
  90
  91 # define ARGMATCH_VALID(Arglist, Vallist) \
  92   argmatch_valid (Arglist, (void const *) (Vallist), sizeof *(Vallist))
  93
  94
  95
  96 /* Like argmatch/argmatch_exact, but upon failure, report an explanation
  97    of the failure, and exit using the function EXIT_FN. */
  98
  99 ptrdiff_t __xargmatch_internal (char const *context,
 100                                 char const *arg, char const *const *arglist,
 101                                 void const *vallist, size_t valsize,
 102                                 argmatch_exit_fn exit_fn,
 103                                 bool allow_abbreviation);
 104
 105 /* Programmer friendly interface to __xargmatch_internal. */
 106
 107 # define XARGMATCH(Context, Arg, Arglist, Vallist)              \
 108   ((Vallist) [__xargmatch_internal (Context, Arg, Arglist,      \
 109                                     (void const *) (Vallist),   \
 110                                     sizeof *(Vallist),          \
 111                                     argmatch_die,               \
 112                                     true)])
 113
 114 # define XARGMATCH_EXACT(Context, Arg, Arglist, Vallist)        \
 115   ((Vallist) [__xargmatch_internal (Context, Arg, Arglist,      \
 116                                     (void const *) (Vallist),   \
 117                                     sizeof *(Vallist),          \
 118                                     argmatch_die,               \
 119                                     false)])
 120
 121 /* Convert a value into a corresponding argument. */
 122
 123 char const *argmatch_to_argument (void const *value,
 124                                   char const *const *arglist,
 125                                   void const *vallist, size_t valsize)
 126   _GL_ATTRIBUTE_PURE;
 127
 128 # define ARGMATCH_TO_ARGUMENT(Value, Arglist, Vallist)                  \
 129   argmatch_to_argument (Value, Arglist,                                 \
 130                         (void const *) (Vallist), sizeof *(Vallist))
 131
 132 # define ARGMATCH_DEFINE_GROUP(Name, Type)                              \
 133   /* The type of the values of this group.  */                          \
 134   typedef Type argmatch_##Name##_type;                                  \
 135                                                                         \
 136   /* The size of the type of the values of this group. */               \
 137   enum argmatch_##Name##_size_enum                                      \
 138   {                                                                     \
 139     argmatch_##Name##_size = sizeof (argmatch_##Name##_type)            \
 140   };                                                                    \
 141                                                                         \
 142   /* Argument mapping of this group.  */                                \
 143   typedef struct                                                        \
 144   {                                                                     \
 145     /* Argument (e.g., "simple").  */                                   \
 146     const char *arg;                                                    \
 147     /* Value (e.g., simple_backups).  */                                \
 148     const argmatch_##Name##_type val;                                   \
 149   } argmatch_##Name##_arg;                                              \
 150                                                                         \
 151   /* Documentation of this group.  */                                   \
 152   typedef struct                                                        \
 153   {                                                                     \
 154     /* Argument (e.g., "simple").  */                                   \
 155     const char *arg;                                                    \
 156     /* Documentation (e.g., N_("always make simple backups")).  */      \
 157     const char *doc;                                                    \
 158   } argmatch_##Name##_doc;                                              \
 159                                                                         \
 160   /* All the features of an argmatch group.  */                         \
 161   typedef struct                                                        \
 162   {                                                                     \
 163     const argmatch_##Name##_arg* args;                                  \
 164     const argmatch_##Name##_doc* docs;                                  \
 165                                                                         \
 166     /* Printed before the usage message.  */                            \
 167     const char *doc_pre;                                                \
 168     /* Printed after the usage message.  */                             \
 169     const char *doc_post;                                               \
 170   } argmatch_##Name##_group_type;                                       \
 171                                                                         \
 172   /* The structure the user must build.  */                             \
 173   extern const argmatch_##Name##_group_type argmatch_##Name##_group;    \
 174                                                                         \
 175   /* Print the documentation of this group.  */                         \
 176   void argmatch_##Name##_usage (FILE *out);                             \
 177                                                                         \
 178   /* If nonnegative, the index I of ARG in ARGS, i.e,                   \
 179      ARGS[I] == ARG.                                                    \
 180      Return -1 for invalid argument, -2 for ambiguous argument. */      \
 181   ptrdiff_t argmatch_##Name##_choice (const char *arg);                 \
 182                                                                         \
 183   /* A pointer to the corresponding value if it exists, or              \
 184      report an error and exit with failure if the argument was          \
 185      not recognized. */                                                 \
 186   const argmatch_##Name##_type*                                         \
 187   argmatch_##Name##_value (const char *context, const char *arg);       \
 188                                                                         \
 189   /* The first argument in ARGS that matches this value, or NULL.  */   \
 190   const char *                                                          \
 191   argmatch_##Name##_argument (const argmatch_##Name##_type *val);       \
 192                                                                         \
 193   ptrdiff_t                                                             \
 194   argmatch_##Name##_choice (const char *arg)                            \
 195   {                                                                     \
 196     const argmatch_##Name##_group_type *g = &argmatch_##Name##_group;   \
 197     size_t size = argmatch_##Name##_size;                               \
 198     ptrdiff_t res = -1;      /* Index of first nonexact match.  */      \
 199     bool ambiguous = false;  /* Whether multiple nonexact match(es). */ \
 200     size_t arglen = strlen (arg);                                       \
 201                                                                         \
 202     /* Test all elements for either exact match or abbreviated          \
 203        matches.  */                                                     \
 204     for (size_t i = 0; g->args[i].arg; i++)                             \
 205       if (!strncmp (g->args[i].arg, arg, arglen))                       \
 206         {                                                               \
 207           if (strlen (g->args[i].arg) == arglen)                        \
 208             /* Exact match found.  */                                   \
 209             return i;                                                   \
 210           else if (res == -1)                                           \
 211             /* First nonexact match found.  */                          \
 212             res = i;                                                    \
 213           else if (memcmp (&g->args[res].val, &g->args[i].val, size))   \
 214             /* Second nonexact match found.  */                         \
 215             /* There is a real ambiguity, or we could not               \
 216                disambiguate. */                                         \
 217             ambiguous = true;                                           \
 218         }                                                               \
 219     return ambiguous ? -2 : res;                                        \
 220   }                                                                     \
 221                                                                         \
 222   const char *                                                          \
 223   argmatch_##Name##_argument (const argmatch_##Name##_type *val)        \
 224   {                                                                     \
 225     const argmatch_##Name##_group_type *g = &argmatch_##Name##_group;   \
 226     size_t size = argmatch_##Name##_size;                               \
 227     for (size_t i = 0; g->args[i].arg; i++)                             \
 228       if (!memcmp (val, &g->args[i].val, size))                         \
 229         return g->args[i].arg;                                          \
 230     return NULL;                                                        \
 231   }                                                                     \
 232                                                                         \
 233   /* List the valid values of this group. */                            \
 234   static void                                                           \
 235   argmatch_##Name##_valid (FILE *out)                                   \
 236   {                                                                     \
 237     const argmatch_##Name##_group_type *g = &argmatch_##Name##_group;   \
 238     size_t size = argmatch_##Name##_size;                               \
 239                                                                         \
 240     /* Try to put synonyms on the same line.  Synonyms are expected     \
 241        to follow each other. */                                         \
 242     fputs (gettext ("Valid arguments are:"), out);                      \
 243     for (int i = 0; g->args[i].arg; i++)                                \
 244       if (i == 0                                                        \
 245           || memcmp (&g->args[i-1].val, &g->args[i].val, size))         \
 246         fprintf (out, "\n  - %s", quote (g->args[i].arg));              \
 247       else                                                              \
 248         fprintf (out, ", %s", quote (g->args[i].arg));                  \
 249     putc ('\n', out);                                                   \
 250   }                                                                     \
 251                                                                         \
 252   const argmatch_##Name##_type*                                         \
 253   argmatch_##Name##_value (const char *context, const char *arg)        \
 254   {                                                                     \
 255     const argmatch_##Name##_group_type *g = &argmatch_##Name##_group;   \
 256     ptrdiff_t res = argmatch_##Name##_choice (arg);                     \
 257     if (res < 0)                                                        \
 258       {                                                                 \
 259         argmatch_invalid (context, arg, res);                           \
 260         argmatch_##Name##_valid (stderr);                               \
 261         argmatch_die ();                                                \
 262       }                                                                 \
 263     return &g->args[res].val;                                           \
 264   }                                                                     \
 265                                                                         \
 266   /* The column in which the documentation is displayed.                \
 267      The leftmost possible, but no more than 20. */                     \
 268   static int                                                            \
 269   argmatch_##Name##_doc_col (void)                                      \
 270   {                                                                     \
 271     const argmatch_##Name##_group_type *g = &argmatch_##Name##_group;   \
 272     size_t size = argmatch_##Name##_size;                               \
 273     int res = 0;                                                        \
 274     for (int i = 0; g->docs[i].arg; ++i)                                \
 275       {                                                                 \
 276         int col = 4;                                                    \
 277         int ival = argmatch_##Name##_choice (g->docs[i].arg);           \
 278         if (ival < 0)                                                   \
 279           /* Pseudo argument, display it. */                            \
 280           col += strlen (g->docs[i].arg);                               \
 281         else                                                            \
 282           /* Genuine argument, display it with its synonyms. */         \
 283           for (int j = 0; g->args[j].arg; ++j)                          \
 284             if (! memcmp (&g->args[ival].val, &g->args[j].val, size))   \
 285               col += (col == 4 ? 0 : 2) + strlen (g->args[j].arg);      \
 286         if (res <= col)                                                 \
 287           res = col <= 20 ? col : 20;                                   \
 288       }                                                                 \
 289     return res ? res : 20;                                              \
 290   }                                                                     \
 291                                                                         \
 292   void                                                                  \
 293   argmatch_##Name##_usage (FILE *out)                                   \
 294   {                                                                     \
 295     const argmatch_##Name##_group_type *g = &argmatch_##Name##_group;   \
 296     size_t size = argmatch_##Name##_size;                               \
 297     /* Width of the screen.  Help2man does not seem to support          \
 298        arguments on several lines, so in that case pretend a very       \
 299        large width. */                                                  \
 300     const int screen_width = getenv ("HELP2MAN") ? INT_MAX : 80;        \
 301     if (g->doc_pre)                                                     \
 302       fprintf (out, "%s\n", gettext (g->doc_pre));                      \
 303     int doc_col = argmatch_##Name##_doc_col ();                         \
 304     for (int i = 0; g->docs[i].arg; ++i)                                \
 305       {                                                                 \
 306         int col = 0;                                                    \
 307         bool first = true;                                              \
 308         int ival = argmatch_##Name##_choice (g->docs[i].arg);           \
 309         if (ival < 0)                                                   \
 310           /* Pseudo argument, display it. */                            \
 311           col += fprintf (out,  "  %s", g->docs[i].arg);                \
 312         else                                                            \
 313           /* Genuine argument, display it with its synonyms. */         \
 314           for (int j = 0; g->args[j].arg; ++j)                          \
 315             if (! memcmp (&g->args[ival].val, &g->args[j].val, size))   \
 316               {                                                         \
 317                 if (!first                                              \
 318                     && screen_width < col + 2 + strlen (g->args[j].arg)) \
 319                   {                                                     \
 320                     fprintf (out, ",\n");                               \
 321                     col = 0;                                            \
 322                     first = true;                                       \
 323                   }                                                     \
 324                 if (first)                                              \
 325                   {                                                     \
 326                     col += fprintf (out, " ");                          \
 327                     first = false;                                      \
 328                   }                                                     \
 329                 else                                                    \
 330                   col += fprintf (out, ",");                            \
 331                 col += fprintf (out,  " %s", g->args[j].arg);           \
 332               }                                                         \
 333         /* The doc.  Separated by at least two spaces. */               \
 334         if (doc_col < col + 2)                                          \
 335           {                                                             \
 336             fprintf (out, "\n");                                        \
 337             col = 0;                                                    \
 338           }                                                             \
 339         fprintf (out, "%*s%s\n",                                        \
 340                  doc_col - col, "", gettext (g->docs[i].doc));          \
 341       }                                                                 \
 342     if (g->doc_post)                                                    \
 343       fprintf (out, "%s\n", gettext (g->doc_post));                     \
 344   }
 345
 346 # ifdef  __cplusplus
 347 }
 348 # endif
 349
 350 #endif /* ARGMATCH_H_ */