lib/argp-help.c

   1 /* Hierarchial argument parsing help output
   2    Copyright (C) 1995-2005, 2007 Free Software Foundation, Inc.
   3    This file is part of the GNU C Library.
   4    Written by Miles Bader <miles@gnu.ai.mit.edu>.
   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 2, or (at your option)
   9    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 along
  17    with this program; if not, write to the Free Software Foundation,
  18    Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
  19
  20 #ifndef _GNU_SOURCE
  21 # define _GNU_SOURCE    1
  22 #endif
  23
  24 #ifdef HAVE_CONFIG_H
  25 # include <config.h>
  26 #endif
  27
  28 #include <alloca.h>
  29 #include <errno.h>
  30 #include <stddef.h>
  31 #include <stdlib.h>
  32 #include <string.h>
  33 #include <assert.h>
  34 #include <stdarg.h>
  35 #include <ctype.h>
  36 #include <limits.h>
  37 #ifdef USE_IN_LIBIO
  38 # include <wchar.h>
  39 #endif
  40
  41 #ifdef _LIBC
  42 # include <libintl.h>
  43 # undef dgettext
  44 # define dgettext(domain, msgid) \
  45    INTUSE(__dcgettext) (domain, msgid, LC_MESSAGES)
  46 #else
  47 # include "gettext.h"
  48 #endif
  49
  50 #include "argp.h"
  51 #include "argp-fmtstream.h"
  52 #include "argp-namefrob.h"
  53
  54 #ifndef SIZE_MAX
  55 # define SIZE_MAX ((size_t) -1)
  56 #endif
  57 \f
  58 /* User-selectable (using an environment variable) formatting parameters.
  59
  60    These may be specified in an environment variable called `ARGP_HELP_FMT',
  61    with a contents like:  VAR1=VAL1,VAR2=VAL2,BOOLVAR2,no-BOOLVAR2
  62    Where VALn must be a positive integer.  The list of variables is in the
  63    UPARAM_NAMES vector, below.  */
  64
  65 /* Default parameters.  */
  66 #define DUP_ARGS      0         /* True if option argument can be duplicated. */
  67 #define DUP_ARGS_NOTE 1         /* True to print a note about duplicate args. */
  68 #define SHORT_OPT_COL 2         /* column in which short options start */
  69 #define LONG_OPT_COL  6         /* column in which long options start */
  70 #define DOC_OPT_COL   2         /* column in which doc options start */
  71 #define OPT_DOC_COL  29         /* column in which option text starts */
  72 #define HEADER_COL    1         /* column in which group headers are printed */
  73 #define USAGE_INDENT 12         /* indentation of wrapped usage lines */
  74 #define RMARGIN      79         /* right margin used for wrapping */
  75
  76 /* User-selectable (using an environment variable) formatting parameters.
  77    They must all be of type `int' for the parsing code to work.  */
  78 struct uparams
  79 {
  80   /* If true, arguments for an option are shown with both short and long
  81      options, even when a given option has both, e.g. `-x ARG, --longx=ARG'.
  82      If false, then if an option has both, the argument is only shown with
  83      the long one, e.g., `-x, --longx=ARG', and a message indicating that
  84      this really means both is printed below the options.  */
  85   int dup_args;
  86
  87   /* This is true if when DUP_ARGS is false, and some duplicate arguments have
  88      been suppressed, an explanatory message should be printed.  */
  89   int dup_args_note;
  90
  91   /* Various output columns.  */
  92   int short_opt_col;      /* column in which short options start */
  93   int long_opt_col;       /* column in which long options start */
  94   int doc_opt_col;        /* column in which doc options start */
  95   int opt_doc_col;        /* column in which option text starts */
  96   int header_col;         /* column in which group headers are printed */
  97   int usage_indent;       /* indentation of wrapped usage lines */
  98   int rmargin;            /* right margin used for wrapping */
  99
 100   int valid;              /* True when the values in here are valid.  */
 101 };
 102
 103 /* This is a global variable, as user options are only ever read once.  */
 104 static struct uparams uparams = {
 105   DUP_ARGS, DUP_ARGS_NOTE,
 106   SHORT_OPT_COL, LONG_OPT_COL, DOC_OPT_COL, OPT_DOC_COL, HEADER_COL,
 107   USAGE_INDENT, RMARGIN,
 108   0
 109 };
 110
 111 /* A particular uparam, and what the user name is.  */
 112 struct uparam_name
 113 {
 114   const char *name;             /* User name.  */
 115   int is_bool;                  /* Whether it's `boolean'.  */
 116   size_t uparams_offs;          /* Location of the (int) field in UPARAMS.  */
 117 };
 118
 119 /* The name-field mappings we know about.  */
 120 static const struct uparam_name uparam_names[] =
 121 {
 122   { "dup-args",       1, offsetof (struct uparams, dup_args) },
 123   { "dup-args-note",  1, offsetof (struct uparams, dup_args_note) },
 124   { "short-opt-col",  0, offsetof (struct uparams, short_opt_col) },
 125   { "long-opt-col",   0, offsetof (struct uparams, long_opt_col) },
 126   { "doc-opt-col",    0, offsetof (struct uparams, doc_opt_col) },
 127   { "opt-doc-col",    0, offsetof (struct uparams, opt_doc_col) },
 128   { "header-col",     0, offsetof (struct uparams, header_col) },
 129   { "usage-indent",   0, offsetof (struct uparams, usage_indent) },
 130   { "rmargin",        0, offsetof (struct uparams, rmargin) },
 131   { 0 }
 132 };
 133
 134 static void
 135 validate_uparams (const struct argp_state *state, struct uparams *upptr)
 136 {
 137   const struct uparam_name *up;
 138
 139   for (up = uparam_names; up->name; up++)
 140     {
 141       if (up->is_bool
 142           || up->uparams_offs == offsetof (struct uparams, rmargin))
 143         continue;
 144       if (*(int *)((char *)upptr + up->uparams_offs) >= upptr->rmargin)
 145         {
 146           __argp_failure (state, 0, 0,
 147                           dgettext (state->root_argp->argp_domain,
 148                                     "\
 149 ARGP_HELP_FMT: %s value is less than or equal to %s"),
 150                           "rmargin", up->name);
 151           return;
 152         }
 153     }
 154   uparams = *upptr;
 155   uparams.valid = 1;
 156 }
 157
 158 /* Read user options from the environment, and fill in UPARAMS appropiately. */
 159 static void
 160 fill_in_uparams (const struct argp_state *state)
 161 {
 162   const char *var = getenv ("ARGP_HELP_FMT");
 163   struct uparams new_params = uparams;
 164
 165 #define SKIPWS(p) do { while (isspace ((unsigned char) *p)) p++; } while (0);
 166
 167   if (var)
 168     {
 169       /* Parse var. */
 170       while (*var)
 171         {
 172           SKIPWS (var);
 173
 174           if (isalpha ((unsigned char) *var))
 175             {
 176               size_t var_len;
 177               const struct uparam_name *un;
 178               int unspec = 0, val = 0;
 179               const char *arg = var;
 180
 181               while (isalnum ((unsigned char) *arg) || *arg == '-' || *arg == '_')
 182                 arg++;
 183               var_len = arg - var;
 184
 185               SKIPWS (arg);
 186
 187               if (*arg == '\0' || *arg == ',')
 188                 unspec = 1;
 189               else if (*arg == '=')
 190                 {
 191                   arg++;
 192                   SKIPWS (arg);
 193                 }
 194
 195               if (unspec)
 196                 {
 197                   if (var[0] == 'n' && var[1] == 'o' && var[2] == '-')
 198                     {
 199                       val = 0;
 200                       var += 3;
 201                       var_len -= 3;
 202                     }
 203                   else
 204                     val = 1;
 205                 }
 206               else if (isdigit ((unsigned char) *arg))
 207                 {
 208                   val = atoi (arg);
 209                   while (isdigit ((unsigned char) *arg))
 210                     arg++;
 211                   SKIPWS (arg);
 212                 }
 213
 214               for (un = uparam_names; un->name; un++)
 215                 if (strlen (un->name) == var_len
 216                     && strncmp (var, un->name, var_len) == 0)
 217                   {
 218                     if (unspec && !un->is_bool)
 219                       __argp_failure (state, 0, 0,
 220                                       dgettext (state->root_argp->argp_domain,
 221                                                 "\
 222 %.*s: ARGP_HELP_FMT parameter requires a value"),
 223                                       (int) var_len, var);
 224                     else if (val < 0)
 225                       __argp_failure (state, 0, 0,
 226                                       dgettext (state->root_argp->argp_domain,
 227                                                 "\
 228 %.*s: ARGP_HELP_FMT parameter must be positive"),
 229                                       (int) var_len, var);
 230                     else
 231                       *(int *)((char *)&new_params + un->uparams_offs) = val;
 232                     break;
 233                   }
 234               if (! un->name)
 235                 __argp_failure (state, 0, 0,
 236                                 dgettext (state->root_argp->argp_domain, "\
 237 %.*s: Unknown ARGP_HELP_FMT parameter"),
 238                                 (int) var_len, var);
 239
 240               var = arg;
 241               if (*var == ',')
 242                 var++;
 243             }
 244           else if (*var)
 245             {
 246               __argp_failure (state, 0, 0,
 247                               dgettext (state->root_argp->argp_domain,
 248                                         "Garbage in ARGP_HELP_FMT: %s"), var);
 249               break;
 250             }
 251         }
 252       validate_uparams (state, &new_params);
 253     }
 254 }
 255 \f
 256 /* Returns true if OPT hasn't been marked invisible.  Visibility only affects
 257    whether OPT is displayed or used in sorting, not option shadowing.  */
 258 #define ovisible(opt) (! ((opt)->flags & OPTION_HIDDEN))
 259
 260 /* Returns true if OPT is an alias for an earlier option.  */
 261 #define oalias(opt) ((opt)->flags & OPTION_ALIAS)
 262
 263 /* Returns true if OPT is an documentation-only entry.  */
 264 #define odoc(opt) ((opt)->flags & OPTION_DOC)
 265
 266 /* Returns true if OPT should not be translated */
 267 #define onotrans(opt) ((opt)->flags & OPTION_NO_TRANS)
 268
 269 /* Returns true if OPT is the end-of-list marker for a list of options.  */
 270 #define oend(opt) __option_is_end (opt)
 271
 272 /* Returns true if OPT has a short option.  */
 273 #define oshort(opt) __option_is_short (opt)
 274 \f
 275 /*
 276    The help format for a particular option is like:
 277
 278      -xARG, -yARG, --long1=ARG, --long2=ARG        Documentation...
 279
 280    Where ARG will be omitted if there's no argument, for this option, or
 281    will be surrounded by "[" and "]" appropiately if the argument is
 282    optional.  The documentation string is word-wrapped appropiately, and if
 283    the list of options is long enough, it will be started on a separate line.
 284    If there are no short options for a given option, the first long option is
 285    indented slighly in a way that's supposed to make most long options appear
 286    to be in a separate column.
 287
 288    For example, the following output (from ps):
 289
 290      -p PID, --pid=PID          List the process PID
 291          --pgrp=PGRP            List processes in the process group PGRP
 292      -P, -x, --no-parent        Include processes without parents
 293      -Q, --all-fields           Don't elide unusable fields (normally if there's
 294                                 some reason ps can't print a field for any
 295                                 process, it's removed from the output entirely)
 296      -r, --reverse, --gratuitously-long-reverse-option
 297                                 Reverse the order of any sort
 298          --session[=SID]        Add the processes from the session SID (which
 299                                 defaults to the sid of the current process)
 300
 301     Here are some more options:
 302      -f ZOT, --foonly=ZOT       Glork a foonly
 303      -z, --zaza                 Snit a zar
 304
 305      -?, --help                 Give this help list
 306          --usage                Give a short usage message
 307      -V, --version              Print program version
 308
 309    The struct argp_option array for the above could look like:
 310
 311    {
 312      {"pid",       'p',      "PID",  0, "List the process PID"},
 313      {"pgrp",      OPT_PGRP, "PGRP", 0, "List processes in the process group PGRP"},
 314      {"no-parent", 'P',       0,     0, "Include processes without parents"},
 315      {0,           'x',       0,     OPTION_ALIAS},
 316      {"all-fields",'Q',       0,     0, "Don't elide unusable fields (normally"
 317                                         " if there's some reason ps can't"
 318                                         " print a field for any process, it's"
 319                                         " removed from the output entirely)" },
 320      {"reverse",   'r',       0,     0, "Reverse the order of any sort"},
 321      {"gratuitously-long-reverse-option", 0, 0, OPTION_ALIAS},
 322      {"session",   OPT_SESS,  "SID", OPTION_ARG_OPTIONAL,
 323                                         "Add the processes from the session"
 324                                         " SID (which defaults to the sid of"
 325                                         " the current process)" },
 326
 327      {0,0,0,0, "Here are some more options:"},
 328      {"foonly", 'f', "ZOT", 0, "Glork a foonly"},
 329      {"zaza", 'z', 0, 0, "Snit a zar"},
 330
 331      {0}
 332    }
 333
 334    Note that the last three options are automatically supplied by argp_parse,
 335    unless you tell it not to with ARGP_NO_HELP.
 336
 337 */
 338 \f
 339 /* Returns true if CH occurs between BEG and END.  */
 340 static int
 341 find_char (char ch, char *beg, char *end)
 342 {
 343   while (beg < end)
 344     if (*beg == ch)
 345       return 1;
 346     else
 347       beg++;
 348   return 0;
 349 }
 350 \f
 351 struct hol_cluster;             /* fwd decl */
 352
 353 struct hol_entry
 354 {
 355   /* First option.  */
 356   const struct argp_option *opt;
 357   /* Number of options (including aliases).  */
 358   unsigned num;
 359
 360   /* A pointers into the HOL's short_options field, to the first short option
 361      letter for this entry.  The order of the characters following this point
 362      corresponds to the order of options pointed to by OPT, and there are at
 363      most NUM.  A short option recorded in a option following OPT is only
 364      valid if it occurs in the right place in SHORT_OPTIONS (otherwise it's
 365      probably been shadowed by some other entry).  */
 366   char *short_options;
 367
 368   /* Entries are sorted by their group first, in the order:
 369        1, 2, ..., n, 0, -m, ..., -2, -1
 370      and then alphabetically within each group.  The default is 0.  */
 371   int group;
 372
 373   /* The cluster of options this entry belongs to, or 0 if none.  */
 374   struct hol_cluster *cluster;
 375
 376   /* The argp from which this option came.  */
 377   const struct argp *argp;
 378 };
 379
 380 /* A cluster of entries to reflect the argp tree structure.  */
 381 struct hol_cluster
 382 {
 383   /* A descriptive header printed before options in this cluster.  */
 384   const char *header;
 385
 386   /* Used to order clusters within the same group with the same parent,
 387      according to the order in which they occurred in the parent argp's child
 388      list.  */
 389   int index;
 390
 391   /* How to sort this cluster with respect to options and other clusters at the
 392      same depth (clusters always follow options in the same group).  */
 393   int group;
 394
 395   /* The cluster to which this cluster belongs, or 0 if it's at the base
 396      level.  */
 397   struct hol_cluster *parent;
 398
 399   /* The argp from which this cluster is (eventually) derived.  */
 400   const struct argp *argp;
 401
 402   /* The distance this cluster is from the root.  */
 403   int depth;
 404
 405   /* Clusters in a given hol are kept in a linked list, to make freeing them
 406      possible.  */
 407   struct hol_cluster *next;
 408 };
 409
 410 /* A list of options for help.  */
 411 struct hol
 412 {
 413   /* An array of hol_entry's.  */
 414   struct hol_entry *entries;
 415   /* The number of entries in this hol.  If this field is zero, the others
 416      are undefined.  */
 417   unsigned num_entries;
 418
 419   /* A string containing all short options in this HOL.  Each entry contains
 420      pointers into this string, so the order can't be messed with blindly.  */
 421   char *short_options;
 422
 423   /* Clusters of entries in this hol.  */
 424   struct hol_cluster *clusters;
 425 };
 426 \f
 427 /* Create a struct hol from the options in ARGP.  CLUSTER is the
 428    hol_cluster in which these entries occur, or 0, if at the root.  */
 429 static struct hol *
 430 make_hol (const struct argp *argp, struct hol_cluster *cluster)
 431 {
 432   char *so;
 433   const struct argp_option *o;
 434   const struct argp_option *opts = argp->options;
 435   struct hol_entry *entry;
 436   unsigned num_short_options = 0;
 437   struct hol *hol = malloc (sizeof (struct hol));
 438
 439   assert (hol);
 440
 441   hol->num_entries = 0;
 442   hol->clusters = 0;
 443
 444   if (opts)
 445     {
 446       int cur_group = 0;
 447
 448       /* The first option must not be an alias.  */
 449       assert (! oalias (opts));
 450
 451       /* Calculate the space needed.  */
 452       for (o = opts; ! oend (o); o++)
 453         {
 454           if (! oalias (o))
 455             hol->num_entries++;
 456           if (oshort (o))
 457             num_short_options++;        /* This is an upper bound.  */
 458         }
 459
 460       hol->entries = malloc (sizeof (struct hol_entry) * hol->num_entries);
 461       hol->short_options = malloc (num_short_options + 1);
 462
 463       assert (hol->entries && hol->short_options);
 464       if (SIZE_MAX <= UINT_MAX)
 465         assert (hol->num_entries <= SIZE_MAX / sizeof (struct hol_entry));
 466
 467       /* Fill in the entries.  */
 468       so = hol->short_options;
 469       for (o = opts, entry = hol->entries; ! oend (o); entry++)
 470         {
 471           entry->opt = o;
 472           entry->num = 0;
 473           entry->short_options = so;
 474           entry->group = cur_group =
 475             o->group
 476             ? o->group
 477             : ((!o->name && !o->key)
 478                ? cur_group + 1
 479                : cur_group);
 480           entry->cluster = cluster;
 481           entry->argp = argp;
 482
 483           do
 484             {
 485               entry->num++;
 486               if (oshort (o) && ! find_char (o->key, hol->short_options, so))
 487                 /* O has a valid short option which hasn't already been used.*/
 488                 *so++ = o->key;
 489               o++;
 490             }
 491           while (! oend (o) && oalias (o));
 492         }
 493       *so = '\0';               /* null terminated so we can find the length */
 494     }
 495
 496   return hol;
 497 }
 498 \f
 499 /* Add a new cluster to HOL, with the given GROUP and HEADER (taken from the
 500    associated argp child list entry), INDEX, and PARENT, and return a pointer
 501    to it.  ARGP is the argp that this cluster results from.  */
 502 static struct hol_cluster *
 503 hol_add_cluster (struct hol *hol, int group, const char *header, int index,
 504                  struct hol_cluster *parent, const struct argp *argp)
 505 {
 506   struct hol_cluster *cl = malloc (sizeof (struct hol_cluster));
 507   if (cl)
 508     {
 509       cl->group = group;
 510       cl->header = header;
 511
 512       cl->index = index;
 513       cl->parent = parent;
 514       cl->argp = argp;
 515       cl->depth = parent ? parent->depth + 1 : 0;
 516
 517       cl->next = hol->clusters;
 518       hol->clusters = cl;
 519     }
 520   return cl;
 521 }
 522 \f
 523 /* Free HOL and any resources it uses.  */
 524 static void
 525 hol_free (struct hol *hol)
 526 {
 527   struct hol_cluster *cl = hol->clusters;
 528
 529   while (cl)
 530     {
 531       struct hol_cluster *next = cl->next;
 532       free (cl);
 533       cl = next;
 534     }
 535
 536   if (hol->num_entries > 0)
 537     {
 538       free (hol->entries);
 539       free (hol->short_options);
 540     }
 541
 542   free (hol);
 543 }
 544 \f
 545 static int
 546 hol_entry_short_iterate (const struct hol_entry *entry,
 547                          int (*func)(const struct argp_option *opt,
 548                                      const struct argp_option *real,
 549                                      const char *domain, void *cookie),
 550                          const char *domain, void *cookie)
 551 {
 552   unsigned nopts;
 553   int val = 0;
 554   const struct argp_option *opt, *real = entry->opt;
 555   char *so = entry->short_options;
 556
 557   for (opt = real, nopts = entry->num; nopts > 0 && !val; opt++, nopts--)
 558     if (oshort (opt) && *so == opt->key)
 559       {
 560         if (!oalias (opt))
 561           real = opt;
 562         if (ovisible (opt))
 563           val = (*func)(opt, real, domain, cookie);
 564         so++;
 565       }
 566
 567   return val;
 568 }
 569
 570 static inline int
 571 __attribute__ ((always_inline))
 572 hol_entry_long_iterate (const struct hol_entry *entry,
 573                         int (*func)(const struct argp_option *opt,
 574                                     const struct argp_option *real,
 575                                     const char *domain, void *cookie),
 576                         const char *domain, void *cookie)
 577 {
 578   unsigned nopts;
 579   int val = 0;
 580   const struct argp_option *opt, *real = entry->opt;
 581
 582   for (opt = real, nopts = entry->num; nopts > 0 && !val; opt++, nopts--)
 583     if (opt->name)
 584       {
 585         if (!oalias (opt))
 586           real = opt;
 587         if (ovisible (opt))
 588           val = (*func)(opt, real, domain, cookie);
 589       }
 590
 591   return val;
 592 }
 593 \f
 594 /* Iterator that returns true for the first short option.  */
 595 static inline int
 596 until_short (const struct argp_option *opt, const struct argp_option *real,
 597              const char *domain, void *cookie)
 598 {
 599   return oshort (opt) ? opt->key : 0;
 600 }
 601
 602 /* Returns the first valid short option in ENTRY, or 0 if there is none.  */
 603 static char
 604 hol_entry_first_short (const struct hol_entry *entry)
 605 {
 606   return hol_entry_short_iterate (entry, until_short,
 607                                   entry->argp->argp_domain, 0);
 608 }
 609
 610 /* Returns the first valid long option in ENTRY, or 0 if there is none.  */
 611 static const char *
 612 hol_entry_first_long (const struct hol_entry *entry)
 613 {
 614   const struct argp_option *opt;
 615   unsigned num;
 616   for (opt = entry->opt, num = entry->num; num > 0; opt++, num--)
 617     if (opt->name && ovisible (opt))
 618       return opt->name;
 619   return 0;
 620 }
 621
 622 /* Returns the entry in HOL with the long option name NAME, or 0 if there is
 623    none.  */
 624 static struct hol_entry *
 625 hol_find_entry (struct hol *hol, const char *name)
 626 {
 627   struct hol_entry *entry = hol->entries;
 628   unsigned num_entries = hol->num_entries;
 629
 630   while (num_entries-- > 0)
 631     {
 632       const struct argp_option *opt = entry->opt;
 633       unsigned num_opts = entry->num;
 634
 635       while (num_opts-- > 0)
 636         if (opt->name && ovisible (opt) && strcmp (opt->name, name) == 0)
 637           return entry;
 638         else
 639           opt++;
 640
 641       entry++;
 642     }
 643
 644   return 0;
 645 }
 646 \f
 647 /* If an entry with the long option NAME occurs in HOL, set it's special
 648    sort position to GROUP.  */
 649 static void
 650 hol_set_group (struct hol *hol, const char *name, int group)
 651 {
 652   struct hol_entry *entry = hol_find_entry (hol, name);
 653   if (entry)
 654     entry->group = group;
 655 }
 656 \f
 657 /* Order by group:  0, 1, 2, ..., n, -m, ..., -2, -1.
 658    EQ is what to return if GROUP1 and GROUP2 are the same.  */
 659 static int
 660 group_cmp (int group1, int group2, int eq)
 661 {
 662   if (group1 == group2)
 663     return eq;
 664   else if ((group1 < 0 && group2 < 0) || (group1 >= 0 && group2 >= 0))
 665     return group1 - group2;
 666   else
 667     return group2 - group1;
 668 }
 669
 670 /* Compare clusters CL1 & CL2 by the order that they should appear in
 671    output.  */
 672 static int
 673 hol_cluster_cmp (const struct hol_cluster *cl1, const struct hol_cluster *cl2)
 674 {
 675   /* If one cluster is deeper than the other, use its ancestor at the same
 676      level, so that finding the common ancestor is straightforward.
 677
 678      clN->depth > 0 means that clN->parent != NULL (see hol_add_cluster) */
 679   while (cl1->depth > cl2->depth)
 680     cl1 = cl1->parent;
 681   while (cl2->depth > cl1->depth)
 682     cl2 = cl2->parent;
 683
 684   /* Now reduce both clusters to their ancestors at the point where both have
 685      a common parent; these can be directly compared.  */
 686   while (cl1->parent != cl2->parent)
 687     cl1 = cl1->parent, cl2 = cl2->parent;
 688
 689   return group_cmp (cl1->group, cl2->group, cl2->index - cl1->index);
 690 }
 691
 692 /* Return the ancestor of CL that's just below the root (i.e., has a parent
 693    of 0).  */
 694 static struct hol_cluster *
 695 hol_cluster_base (struct hol_cluster *cl)
 696 {
 697   while (cl->parent)
 698     cl = cl->parent;
 699   return cl;
 700 }
 701
 702 /* Return true if CL1 is a child of CL2.  */
 703 static int
 704 hol_cluster_is_child (const struct hol_cluster *cl1,
 705                       const struct hol_cluster *cl2)
 706 {
 707   while (cl1 && cl1 != cl2)
 708     cl1 = cl1->parent;
 709   return cl1 == cl2;
 710 }
 711 \f
 712 /* Given the name of a OPTION_DOC option, modifies NAME to start at the tail
 713    that should be used for comparisons, and returns true iff it should be
 714    treated as a non-option.  */
 715 static int
 716 canon_doc_option (const char **name)
 717 {
 718   int non_opt;
 719
 720   if (!*name)
 721     non_opt = 1;
 722   else
 723     {
 724       /* Skip initial whitespace.  */
 725       while (isspace ((unsigned char) **name))
 726         (*name)++;
 727       /* Decide whether this looks like an option (leading `-') or not.  */
 728       non_opt = (**name != '-');
 729       /* Skip until part of name used for sorting.  */
 730       while (**name && !isalnum ((unsigned char) **name))
 731         (*name)++;
 732     }
 733   return non_opt;
 734 }
 735
 736 /* Order ENTRY1 & ENTRY2 by the order which they should appear in a help
 737    listing.  */
 738 static int
 739 hol_entry_cmp (const struct hol_entry *entry1,
 740                const struct hol_entry *entry2)
 741 {
 742   /* The group numbers by which the entries should be ordered; if either is
 743      in a cluster, then this is just the group within the cluster.  */
 744   int group1 = entry1->group, group2 = entry2->group;
 745
 746   if (entry1->cluster != entry2->cluster)
 747     {
 748       /* The entries are not within the same cluster, so we can't compare them
 749          directly, we have to use the appropiate clustering level too.  */
 750       if (! entry1->cluster)
 751         /* ENTRY1 is at the `base level', not in a cluster, so we have to
 752            compare it's group number with that of the base cluster in which
 753            ENTRY2 resides.  Note that if they're in the same group, the
 754            clustered option always comes laster.  */
 755         return group_cmp (group1, hol_cluster_base (entry2->cluster)->group, -1);
 756       else if (! entry2->cluster)
 757         /* Likewise, but ENTRY2's not in a cluster.  */
 758         return group_cmp (hol_cluster_base (entry1->cluster)->group, group2, 1);
 759       else
 760         /* Both entries are in clusters, we can just compare the clusters.  */
 761         return hol_cluster_cmp (entry1->cluster, entry2->cluster);
 762     }
 763   else if (group1 == group2)
 764     /* The entries are both in the same cluster and group, so compare them
 765        alphabetically.  */
 766     {
 767       int short1 = hol_entry_first_short (entry1);
 768       int short2 = hol_entry_first_short (entry2);
 769       int doc1 = odoc (entry1->opt);
 770       int doc2 = odoc (entry2->opt);
 771       const char *long1 = hol_entry_first_long (entry1);
 772       const char *long2 = hol_entry_first_long (entry2);
 773
 774       if (doc1)
 775         doc1 = canon_doc_option (&long1);
 776       if (doc2)
 777         doc2 = canon_doc_option (&long2);
 778
 779       if (doc1 != doc2)
 780         /* `documentation' options always follow normal options (or
 781            documentation options that *look* like normal options).  */
 782         return doc1 - doc2;
 783       else if (!short1 && !short2 && long1 && long2)
 784         /* Only long options.  */
 785         return __strcasecmp (long1, long2);
 786       else
 787         /* Compare short/short, long/short, short/long, using the first
 788            character of long options.  Entries without *any* valid
 789            options (such as options with OPTION_HIDDEN set) will be put
 790            first, but as they're not displayed, it doesn't matter where
 791            they are.  */
 792         {
 793           char first1 = short1 ? short1 : long1 ? *long1 : 0;
 794           char first2 = short2 ? short2 : long2 ? *long2 : 0;
 795 #ifdef _tolower
 796           int lower_cmp = _tolower (first1) - _tolower (first2);
 797 #else
 798           int lower_cmp = tolower (first1) - tolower (first2);
 799 #endif
 800           /* Compare ignoring case, except when the options are both the
 801              same letter, in which case lower-case always comes first.  */
 802           return lower_cmp ? lower_cmp : first2 - first1;
 803         }
 804     }
 805   else
 806     /* Within the same cluster, but not the same group, so just compare
 807        groups.  */
 808     return group_cmp (group1, group2, 0);
 809 }
 810
 811 /* Version of hol_entry_cmp with correct signature for qsort.  */
 812 static int
 813 hol_entry_qcmp (const void *entry1_v, const void *entry2_v)
 814 {
 815   return hol_entry_cmp (entry1_v, entry2_v);
 816 }
 817
 818 /* Sort HOL by group and alphabetically by option name (with short options
 819    taking precedence over long).  Since the sorting is for display purposes
 820    only, the shadowing of options isn't effected.  */
 821 static void
 822 hol_sort (struct hol *hol)
 823 {
 824   if (hol->num_entries > 0)
 825     qsort (hol->entries, hol->num_entries, sizeof (struct hol_entry),
 826            hol_entry_qcmp);
 827 }
 828 \f
 829 /* Append MORE to HOL, destroying MORE in the process.  Options in HOL shadow
 830    any in MORE with the same name.  */
 831 static void
 832 hol_append (struct hol *hol, struct hol *more)
 833 {
 834   struct hol_cluster **cl_end = &hol->clusters;
 835
 836   /* Steal MORE's cluster list, and add it to the end of HOL's.  */
 837   while (*cl_end)
 838     cl_end = &(*cl_end)->next;
 839   *cl_end = more->clusters;
 840   more->clusters = 0;
 841
 842   /* Merge entries.  */
 843   if (more->num_entries > 0)
 844     {
 845       if (hol->num_entries == 0)
 846         {
 847           hol->num_entries = more->num_entries;
 848           hol->entries = more->entries;
 849           hol->short_options = more->short_options;
 850           more->num_entries = 0;        /* Mark MORE's fields as invalid.  */
 851         }
 852       else
 853         /* Append the entries in MORE to those in HOL, taking care to only add
 854            non-shadowed SHORT_OPTIONS values.  */
 855         {
 856           unsigned left;
 857           char *so, *more_so;
 858           struct hol_entry *e;
 859           unsigned num_entries = hol->num_entries + more->num_entries;
 860           struct hol_entry *entries =
 861             malloc (num_entries * sizeof (struct hol_entry));
 862           unsigned hol_so_len = strlen (hol->short_options);
 863           char *short_options =
 864             malloc (hol_so_len + strlen (more->short_options) + 1);
 865
 866           assert (entries && short_options);
 867           if (SIZE_MAX <= UINT_MAX)
 868             assert (num_entries <= SIZE_MAX / sizeof (struct hol_entry));
 869
 870           __mempcpy (__mempcpy (entries, hol->entries,
 871                                 hol->num_entries * sizeof (struct hol_entry)),
 872                      more->entries,
 873                      more->num_entries * sizeof (struct hol_entry));
 874
 875           __mempcpy (short_options, hol->short_options, hol_so_len);
 876
 877           /* Fix up the short options pointers from HOL.  */
 878           for (e = entries, left = hol->num_entries; left > 0; e++, left--)
 879             e->short_options += (short_options - hol->short_options);
 880
 881           /* Now add the short options from MORE, fixing up its entries
 882              too.  */
 883           so = short_options + hol_so_len;
 884           more_so = more->short_options;
 885           for (left = more->num_entries; left > 0; e++, left--)
 886             {
 887               int opts_left;
 888               const struct argp_option *opt;
 889
 890               e->short_options = so;
 891
 892               for (opts_left = e->num, opt = e->opt; opts_left; opt++, opts_left--)
 893                 {
 894                   int ch = *more_so;
 895                   if (oshort (opt) && ch == opt->key)
 896                     /* The next short option in MORE_SO, CH, is from OPT.  */
 897                     {
 898                       if (! find_char (ch, short_options,
 899                                        short_options + hol_so_len))
 900                         /* The short option CH isn't shadowed by HOL's options,
 901                            so add it to the sum.  */
 902                         *so++ = ch;
 903                       more_so++;
 904                     }
 905                 }
 906             }
 907
 908           *so = '\0';
 909
 910           free (hol->entries);
 911           free (hol->short_options);
 912
 913           hol->entries = entries;
 914           hol->num_entries = num_entries;
 915           hol->short_options = short_options;
 916         }
 917     }
 918
 919   hol_free (more);
 920 }
 921 \f
 922 /* Inserts enough spaces to make sure STREAM is at column COL.  */
 923 static void
 924 indent_to (argp_fmtstream_t stream, unsigned col)
 925 {
 926   int needed = col - __argp_fmtstream_point (stream);
 927   while (needed-- > 0)
 928     __argp_fmtstream_putc (stream, ' ');
 929 }
 930
 931 /* Output to STREAM either a space, or a newline if there isn't room for at
 932    least ENSURE characters before the right margin.  */
 933 static void
 934 space (argp_fmtstream_t stream, size_t ensure)
 935 {
 936   if (__argp_fmtstream_point (stream) + ensure
 937       >= __argp_fmtstream_rmargin (stream))
 938     __argp_fmtstream_putc (stream, '\n');
 939   else
 940     __argp_fmtstream_putc (stream, ' ');
 941 }
 942
 943 /* If the option REAL has an argument, we print it in using the printf
 944    format REQ_FMT or OPT_FMT depending on whether it's a required or
 945    optional argument.  */
 946 static void
 947 arg (const struct argp_option *real, const char *req_fmt, const char *opt_fmt,
 948      const char *domain, argp_fmtstream_t stream)
 949 {
 950   if (real->arg)
 951     {
 952       if (real->flags & OPTION_ARG_OPTIONAL)
 953         __argp_fmtstream_printf (stream, opt_fmt,
 954                                  dgettext (domain, real->arg));
 955       else
 956         __argp_fmtstream_printf (stream, req_fmt,
 957                                  dgettext (domain, real->arg));
 958     }
 959 }
 960 \f
 961 /* Helper functions for hol_entry_help.  */
 962
 963 /* State used during the execution of hol_help.  */
 964 struct hol_help_state
 965 {
 966   /* PREV_ENTRY should contain the previous entry printed, or 0.  */
 967   struct hol_entry *prev_entry;
 968
 969   /* If an entry is in a different group from the previous one, and SEP_GROUPS
 970      is true, then a blank line will be printed before any output. */
 971   int sep_groups;
 972
 973   /* True if a duplicate option argument was suppressed (only ever set if
 974      UPARAMS.dup_args is false).  */
 975   int suppressed_dup_arg;
 976 };
 977
 978 /* Some state used while printing a help entry (used to communicate with
 979    helper functions).  See the doc for hol_entry_help for more info, as most
 980    of the fields are copied from its arguments.  */
 981 struct pentry_state
 982 {
 983   const struct hol_entry *entry;
 984   argp_fmtstream_t stream;
 985   struct hol_help_state *hhstate;
 986
 987   /* True if nothing's been printed so far.  */
 988   int first;
 989
 990   /* If non-zero, the state that was used to print this help.  */
 991   const struct argp_state *state;
 992 };
 993
 994 /* If a user doc filter should be applied to DOC, do so.  */
 995 static const char *
 996 filter_doc (const char *doc, int key, const struct argp *argp,
 997             const struct argp_state *state)
 998 {
 999   if (argp->help_filter)
1000     /* We must apply a user filter to this output.  */
1001     {
1002       void *input = __argp_input (argp, state);
1003       return (*argp->help_filter) (key, doc, input);
1004     }
1005   else
1006     /* No filter.  */
1007     return doc;
1008 }
1009
1010 /* Prints STR as a header line, with the margin lines set appropiately, and
1011    notes the fact that groups should be separated with a blank line.  ARGP is
1012    the argp that should dictate any user doc filtering to take place.  Note
1013    that the previous wrap margin isn't restored, but the left margin is reset
1014    to 0.  */
1015 static void
1016 print_header (const char *str, const struct argp *argp,
1017               struct pentry_state *pest)
1018 {
1019   const char *tstr = dgettext (argp->argp_domain, str);
1020   const char *fstr = filter_doc (tstr, ARGP_KEY_HELP_HEADER, argp, pest->state);
1021
1022   if (fstr)
1023     {
1024       if (*fstr)
1025         {
1026           if (pest->hhstate->prev_entry)
1027             /* Precede with a blank line.  */
1028             __argp_fmtstream_putc (pest->stream, '\n');
1029           indent_to (pest->stream, uparams.header_col);
1030           __argp_fmtstream_set_lmargin (pest->stream, uparams.header_col);
1031           __argp_fmtstream_set_wmargin (pest->stream, uparams.header_col);
1032           __argp_fmtstream_puts (pest->stream, fstr);
1033           __argp_fmtstream_set_lmargin (pest->stream, 0);
1034           __argp_fmtstream_putc (pest->stream, '\n');
1035         }
1036
1037       pest->hhstate->sep_groups = 1; /* Separate subsequent groups. */
1038     }
1039
1040   if (fstr != tstr)
1041     free ((char *) fstr);
1042 }
1043
1044 /* Inserts a comma if this isn't the first item on the line, and then makes
1045    sure we're at least to column COL.  If this *is* the first item on a line,
1046    prints any pending whitespace/headers that should precede this line. Also
1047    clears FIRST.  */
1048 static void
1049 comma (unsigned col, struct pentry_state *pest)
1050 {
1051   if (pest->first)
1052     {
1053       const struct hol_entry *pe = pest->hhstate->prev_entry;
1054       const struct hol_cluster *cl = pest->entry->cluster;
1055
1056       if (pest->hhstate->sep_groups && pe && pest->entry->group != pe->group)
1057         __argp_fmtstream_putc (pest->stream, '\n');
1058
1059       if (cl && cl->header && *cl->header
1060           && (!pe
1061               || (pe->cluster != cl
1062                   && !hol_cluster_is_child (pe->cluster, cl))))
1063         /* If we're changing clusters, then this must be the start of the
1064            ENTRY's cluster unless that is an ancestor of the previous one
1065            (in which case we had just popped into a sub-cluster for a bit).
1066            If so, then print the cluster's header line.  */
1067         {
1068           int old_wm = __argp_fmtstream_wmargin (pest->stream);
1069           print_header (cl->header, cl->argp, pest);
1070           __argp_fmtstream_set_wmargin (pest->stream, old_wm);
1071         }
1072
1073       pest->first = 0;
1074     }
1075   else
1076     __argp_fmtstream_puts (pest->stream, ", ");
1077
1078   indent_to (pest->stream, col);
1079 }
1080 \f
1081 /* Print help for ENTRY to STREAM.  */
1082 static void
1083 hol_entry_help (struct hol_entry *entry, const struct argp_state *state,
1084                 argp_fmtstream_t stream, struct hol_help_state *hhstate)
1085 {
1086   unsigned num;
1087   const struct argp_option *real = entry->opt, *opt;
1088   char *so = entry->short_options;
1089   int have_long_opt = 0;        /* We have any long options.  */
1090   /* Saved margins.  */
1091   int old_lm = __argp_fmtstream_set_lmargin (stream, 0);
1092   int old_wm = __argp_fmtstream_wmargin (stream);
1093   /* PEST is a state block holding some of our variables that we'd like to
1094      share with helper functions.  */
1095   struct pentry_state pest;
1096
1097   pest.entry = entry;
1098   pest.stream = stream;
1099   pest.hhstate = hhstate;
1100   pest.first = 1;
1101   pest.state = state;
1102
1103   if (! odoc (real))
1104     for (opt = real, num = entry->num; num > 0; opt++, num--)
1105       if (opt->name && ovisible (opt))
1106         {
1107           have_long_opt = 1;
1108           break;
1109         }
1110
1111   /* First emit short options.  */
1112   __argp_fmtstream_set_wmargin (stream, uparams.short_opt_col); /* For truly bizarre cases. */
1113   for (opt = real, num = entry->num; num > 0; opt++, num--)
1114     if (oshort (opt) && opt->key == *so)
1115       /* OPT has a valid (non shadowed) short option.  */
1116       {
1117         if (ovisible (opt))
1118           {
1119             comma (uparams.short_opt_col, &pest);
1120             __argp_fmtstream_putc (stream, '-');
1121             __argp_fmtstream_putc (stream, *so);
1122             if (!have_long_opt || uparams.dup_args)
1123               arg (real, " %s", "[%s]", state->root_argp->argp_domain, stream);
1124             else if (real->arg)
1125               hhstate->suppressed_dup_arg = 1;
1126           }
1127         so++;
1128       }
1129
1130   /* Now, long options.  */
1131   if (odoc (real))
1132     /* A `documentation' option.  */
1133     {
1134       __argp_fmtstream_set_wmargin (stream, uparams.doc_opt_col);
1135       for (opt = real, num = entry->num; num > 0; opt++, num--)
1136         if (opt->name && *opt->name && ovisible (opt))
1137           {
1138             comma (uparams.doc_opt_col, &pest);
1139             /* Calling dgettext here isn't quite right, since sorting will
1140                have been done on the original; but documentation options
1141                should be pretty rare anyway...  */
1142             __argp_fmtstream_puts (stream,
1143                                    onotrans (opt) ?
1144                                              opt->name :
1145                                    dgettext (state->root_argp->argp_domain,
1146                                              opt->name));
1147           }
1148     }
1149   else
1150     /* A real long option.  */
1151     {
1152       int first_long_opt = 1;
1153
1154       __argp_fmtstream_set_wmargin (stream, uparams.long_opt_col);
1155       for (opt = real, num = entry->num; num > 0; opt++, num--)
1156         if (opt->name && ovisible (opt))
1157           {
1158             comma (uparams.long_opt_col, &pest);
1159             __argp_fmtstream_printf (stream, "--%s", opt->name);
1160             if (first_long_opt || uparams.dup_args)
1161               arg (real, "=%s", "[=%s]", state->root_argp->argp_domain,
1162                    stream);
1163             else if (real->arg)
1164               hhstate->suppressed_dup_arg = 1;
1165           }
1166     }
1167
1168   /* Next, documentation strings.  */
1169   __argp_fmtstream_set_lmargin (stream, 0);
1170
1171   if (pest.first)
1172     {
1173       /* Didn't print any switches, what's up?  */
1174       if (!oshort (real) && !real->name)
1175         /* This is a group header, print it nicely.  */
1176         print_header (real->doc, entry->argp, &pest);
1177       else
1178         /* Just a totally shadowed option or null header; print nothing.  */
1179         goto cleanup;           /* Just return, after cleaning up.  */
1180     }
1181   else
1182     {
1183       const char *tstr = real->doc ? dgettext (state->root_argp->argp_domain,
1184                                                real->doc) : 0;
1185       const char *fstr = filter_doc (tstr, real->key, entry->argp, state);
1186       if (fstr && *fstr)
1187         {
1188           unsigned int col = __argp_fmtstream_point (stream);
1189
1190           __argp_fmtstream_set_lmargin (stream, uparams.opt_doc_col);
1191           __argp_fmtstream_set_wmargin (stream, uparams.opt_doc_col);
1192
1193           if (col > (unsigned int) (uparams.opt_doc_col + 3))
1194             __argp_fmtstream_putc (stream, '\n');
1195           else if (col >= (unsigned int) uparams.opt_doc_col)
1196             __argp_fmtstream_puts (stream, "   ");
1197           else
1198             indent_to (stream, uparams.opt_doc_col);
1199
1200           __argp_fmtstream_puts (stream, fstr);
1201         }
1202       if (fstr && fstr != tstr)
1203         free ((char *) fstr);
1204
1205       /* Reset the left margin.  */
1206       __argp_fmtstream_set_lmargin (stream, 0);
1207       __argp_fmtstream_putc (stream, '\n');
1208     }
1209
1210   hhstate->prev_entry = entry;
1211
1212 cleanup:
1213   __argp_fmtstream_set_lmargin (stream, old_lm);
1214   __argp_fmtstream_set_wmargin (stream, old_wm);
1215 }
1216 \f
1217 /* Output a long help message about the options in HOL to STREAM.  */
1218 static void
1219 hol_help (struct hol *hol, const struct argp_state *state,
1220           argp_fmtstream_t stream)
1221 {
1222   unsigned num;
1223   struct hol_entry *entry;
1224   struct hol_help_state hhstate = { 0, 0, 0 };
1225
1226   for (entry = hol->entries, num = hol->num_entries; num > 0; entry++, num--)
1227     hol_entry_help (entry, state, stream, &hhstate);
1228
1229   if (hhstate.suppressed_dup_arg && uparams.dup_args_note)
1230     {
1231       const char *tstr = dgettext (state->root_argp->argp_domain, "\
1232 Mandatory or optional arguments to long options are also mandatory or \
1233 optional for any corresponding short options.");
1234       const char *fstr = filter_doc (tstr, ARGP_KEY_HELP_DUP_ARGS_NOTE,
1235                                      state ? state->root_argp : 0, state);
1236       if (fstr && *fstr)
1237         {
1238           __argp_fmtstream_putc (stream, '\n');
1239           __argp_fmtstream_puts (stream, fstr);
1240           __argp_fmtstream_putc (stream, '\n');
1241         }
1242       if (fstr && fstr != tstr)
1243         free ((char *) fstr);
1244     }
1245 }
1246 \f
1247 /* Helper functions for hol_usage.  */
1248
1249 /* If OPT is a short option without an arg, append its key to the string
1250    pointer pointer to by COOKIE, and advance the pointer.  */
1251 static int
1252 add_argless_short_opt (const struct argp_option *opt,
1253                        const struct argp_option *real,
1254                        const char *domain, void *cookie)
1255 {
1256   char **snao_end = cookie;
1257   if (!(opt->arg || real->arg)
1258       && !((opt->flags | real->flags) & OPTION_NO_USAGE))
1259     *(*snao_end)++ = opt->key;
1260   return 0;
1261 }
1262
1263 /* If OPT is a short option with an arg, output a usage entry for it to the
1264    stream pointed at by COOKIE.  */
1265 static int
1266 usage_argful_short_opt (const struct argp_option *opt,
1267                         const struct argp_option *real,
1268                         const char *domain, void *cookie)
1269 {
1270   argp_fmtstream_t stream = cookie;
1271   const char *arg = opt->arg;
1272   int flags = opt->flags | real->flags;
1273
1274   if (! arg)
1275     arg = real->arg;
1276
1277   if (arg && !(flags & OPTION_NO_USAGE))
1278     {
1279       arg = dgettext (domain, arg);
1280
1281       if (flags & OPTION_ARG_OPTIONAL)
1282         __argp_fmtstream_printf (stream, " [-%c[%s]]", opt->key, arg);
1283       else
1284         {
1285           /* Manually do line wrapping so that it (probably) won't
1286              get wrapped at the embedded space.  */
1287           space (stream, 6 + strlen (arg));
1288           __argp_fmtstream_printf (stream, "[-%c %s]", opt->key, arg);
1289         }
1290     }
1291
1292   return 0;
1293 }
1294
1295 /* Output a usage entry for the long option opt to the stream pointed at by
1296    COOKIE.  */
1297 static int
1298 usage_long_opt (const struct argp_option *opt,
1299                 const struct argp_option *real,
1300                 const char *domain, void *cookie)
1301 {
1302   argp_fmtstream_t stream = cookie;
1303   const char *arg = opt->arg;
1304   int flags = opt->flags | real->flags;
1305
1306   if (! arg)
1307     arg = real->arg;
1308
1309   if (! (flags & OPTION_NO_USAGE) && !odoc (opt))
1310     {
1311       if (arg)
1312         {
1313           arg = dgettext (domain, arg);
1314           if (flags & OPTION_ARG_OPTIONAL)
1315             __argp_fmtstream_printf (stream, " [--%s[=%s]]", opt->name, arg);
1316           else
1317             __argp_fmtstream_printf (stream, " [--%s=%s]", opt->name, arg);
1318         }
1319       else
1320         __argp_fmtstream_printf (stream, " [--%s]", opt->name);
1321     }
1322
1323   return 0;
1324 }
1325 \f
1326 /* Print a short usage description for the arguments in HOL to STREAM.  */
1327 static void
1328 hol_usage (struct hol *hol, argp_fmtstream_t stream)
1329 {
1330   if (hol->num_entries > 0)
1331     {
1332       unsigned nentries;
1333       struct hol_entry *entry;
1334       char *short_no_arg_opts = alloca (strlen (hol->short_options) + 1);
1335       char *snao_end = short_no_arg_opts;
1336
1337       /* First we put a list of short options without arguments.  */
1338       for (entry = hol->entries, nentries = hol->num_entries
1339            ; nentries > 0
1340            ; entry++, nentries--)
1341         hol_entry_short_iterate (entry, add_argless_short_opt,
1342                                  entry->argp->argp_domain, &snao_end);
1343       if (snao_end > short_no_arg_opts)
1344         {
1345           *snao_end++ = 0;
1346           __argp_fmtstream_printf (stream, " [-%s]", short_no_arg_opts);
1347         }
1348
1349       /* Now a list of short options *with* arguments.  */
1350       for (entry = hol->entries, nentries = hol->num_entries
1351            ; nentries > 0
1352            ; entry++, nentries--)
1353         hol_entry_short_iterate (entry, usage_argful_short_opt,
1354                                  entry->argp->argp_domain, stream);
1355
1356       /* Finally, a list of long options (whew!).  */
1357       for (entry = hol->entries, nentries = hol->num_entries
1358            ; nentries > 0
1359            ; entry++, nentries--)
1360         hol_entry_long_iterate (entry, usage_long_opt,
1361                                 entry->argp->argp_domain, stream);
1362     }
1363 }
1364 \f
1365 /* Make a HOL containing all levels of options in ARGP.  CLUSTER is the
1366    cluster in which ARGP's entries should be clustered, or 0.  */
1367 static struct hol *
1368 argp_hol (const struct argp *argp, struct hol_cluster *cluster)
1369 {
1370   const struct argp_child *child = argp->children;
1371   struct hol *hol = make_hol (argp, cluster);
1372   if (child)
1373     while (child->argp)
1374       {
1375         struct hol_cluster *child_cluster =
1376           ((child->group || child->header)
1377            /* Put CHILD->argp within its own cluster.  */
1378            ? hol_add_cluster (hol, child->group, child->header,
1379                               child - argp->children, cluster, argp)
1380            /* Just merge it into the parent's cluster.  */
1381            : cluster);
1382         hol_append (hol, argp_hol (child->argp, child_cluster)) ;
1383         child++;
1384       }
1385   return hol;
1386 }
1387 \f
1388 /* Calculate how many different levels with alternative args strings exist in
1389    ARGP.  */
1390 static size_t
1391 argp_args_levels (const struct argp *argp)
1392 {
1393   size_t levels = 0;
1394   const struct argp_child *child = argp->children;
1395
1396   if (argp->args_doc && strchr (argp->args_doc, '\n'))
1397     levels++;
1398
1399   if (child)
1400     while (child->argp)
1401       levels += argp_args_levels ((child++)->argp);
1402
1403   return levels;
1404 }
1405
1406 /* Print all the non-option args documented in ARGP to STREAM.  Any output is
1407    preceded by a space.  LEVELS is a pointer to a byte vector the length
1408    returned by argp_args_levels; it should be initialized to zero, and
1409    updated by this routine for the next call if ADVANCE is true.  True is
1410    returned as long as there are more patterns to output.  */
1411 static int
1412 argp_args_usage (const struct argp *argp, const struct argp_state *state,
1413                  char **levels, int advance, argp_fmtstream_t stream)
1414 {
1415   char *our_level = *levels;
1416   int multiple = 0;
1417   const struct argp_child *child = argp->children;
1418   const char *tdoc = dgettext (argp->argp_domain, argp->args_doc), *nl = 0;
1419   const char *fdoc = filter_doc (tdoc, ARGP_KEY_HELP_ARGS_DOC, argp, state);
1420
1421   if (fdoc)
1422     {
1423       const char *cp = fdoc;
1424       nl = __strchrnul (cp, '\n');
1425       if (*nl != '\0')
1426         /* This is a `multi-level' args doc; advance to the correct position
1427            as determined by our state in LEVELS, and update LEVELS.  */
1428         {
1429           int i;
1430           multiple = 1;
1431           for (i = 0; i < *our_level; i++)
1432             cp = nl + 1, nl = __strchrnul (cp, '\n');
1433           (*levels)++;
1434         }
1435
1436       /* Manually do line wrapping so that it (probably) won't get wrapped at
1437          any embedded spaces.  */
1438       space (stream, 1 + nl - cp);
1439
1440       __argp_fmtstream_write (stream, cp, nl - cp);
1441     }
1442   if (fdoc && fdoc != tdoc)
1443     free ((char *)fdoc);        /* Free user's modified doc string.  */
1444
1445   if (child)
1446     while (child->argp)
1447       advance = !argp_args_usage ((child++)->argp, state, levels, advance, stream);
1448
1449   if (advance && multiple)
1450     {
1451       /* Need to increment our level.  */
1452       if (*nl)
1453         /* There's more we can do here.  */
1454         {
1455           (*our_level)++;
1456           advance = 0;          /* Our parent shouldn't advance also. */
1457         }
1458       else if (*our_level > 0)
1459         /* We had multiple levels, but used them up; reset to zero.  */
1460         *our_level = 0;
1461     }
1462
1463   return !advance;
1464 }
1465 \f
1466 /* Print the documentation for ARGP to STREAM; if POST is false, then
1467    everything preceeding a `\v' character in the documentation strings (or
1468    the whole string, for those with none) is printed, otherwise, everything
1469    following the `\v' character (nothing for strings without).  Each separate
1470    bit of documentation is separated a blank line, and if PRE_BLANK is true,
1471    then the first is as well.  If FIRST_ONLY is true, only the first
1472    occurrence is output.  Returns true if anything was output.  */
1473 static int
1474 argp_doc (const struct argp *argp, const struct argp_state *state,
1475           int post, int pre_blank, int first_only,
1476           argp_fmtstream_t stream)
1477 {
1478   const char *text;
1479   const char *inp_text;
1480   size_t inp_text_len = 0;
1481   const char *trans_text;
1482   void *input = 0;
1483   int anything = 0;
1484   const struct argp_child *child = argp->children;
1485
1486   if (argp->doc)
1487     {
1488       char *vt = strchr (argp->doc, '\v');
1489       if (vt)
1490         {
1491           if (post)
1492             inp_text = vt + 1;
1493           else
1494             {
1495               inp_text_len = vt - argp->doc;
1496               inp_text = __strndup (argp->doc, inp_text_len);
1497             }
1498         }
1499       else
1500         inp_text = post ? 0 : argp->doc;
1501       trans_text = inp_text ? dgettext (argp->argp_domain, inp_text) : NULL;
1502     }
1503   else
1504     trans_text = inp_text = 0;
1505
1506   if (argp->help_filter)
1507     /* We have to filter the doc strings.  */
1508     {
1509       input = __argp_input (argp, state);
1510       text =
1511         (*argp->help_filter) (post
1512                               ? ARGP_KEY_HELP_POST_DOC
1513                               : ARGP_KEY_HELP_PRE_DOC,
1514                               trans_text, input);
1515     }
1516   else
1517     text = (const char *) trans_text;
1518
1519   if (text)
1520     {
1521       if (pre_blank)
1522         __argp_fmtstream_putc (stream, '\n');
1523
1524       __argp_fmtstream_puts (stream, text);
1525
1526       if (__argp_fmtstream_point (stream) > __argp_fmtstream_lmargin (stream))
1527         __argp_fmtstream_putc (stream, '\n');
1528
1529       anything = 1;
1530     }
1531
1532   if (text && text != trans_text)
1533     free ((char *) text);       /* Free TEXT returned from the help filter.  */
1534
1535   if (inp_text && inp_text_len)
1536     free ((char *) inp_text);   /* We copied INP_TEXT, so free it now.  */
1537
1538   if (post && argp->help_filter)
1539     /* Now see if we have to output a ARGP_KEY_HELP_EXTRA text.  */
1540     {
1541       text = (*argp->help_filter) (ARGP_KEY_HELP_EXTRA, 0, input);
1542       if (text)
1543         {
1544           if (anything || pre_blank)
1545             __argp_fmtstream_putc (stream, '\n');
1546           __argp_fmtstream_puts (stream, text);
1547           free ((char *) text);
1548           if (__argp_fmtstream_point (stream)
1549               > __argp_fmtstream_lmargin (stream))
1550             __argp_fmtstream_putc (stream, '\n');
1551           anything = 1;
1552         }
1553     }
1554
1555   if (child)
1556     while (child->argp && !(first_only && anything))
1557       anything |=
1558         argp_doc ((child++)->argp, state,
1559                   post, anything || pre_blank, first_only,
1560                   stream);
1561
1562   return anything;
1563 }
1564 \f
1565 /* Output a usage message for ARGP to STREAM.  If called from
1566    argp_state_help, STATE is the relevent parsing state.  FLAGS are from the
1567    set ARGP_HELP_*.  NAME is what to use wherever a `program name' is
1568    needed. */
1569 static void
1570 _help (const struct argp *argp, const struct argp_state *state, FILE *stream,
1571        unsigned flags, char *name)
1572 {
1573   int anything = 0;             /* Whether we've output anything.  */
1574   struct hol *hol = 0;
1575   argp_fmtstream_t fs;
1576
1577   if (! stream)
1578     return;
1579
1580 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1581   __flockfile (stream);
1582 #endif
1583
1584   if (! uparams.valid)
1585     fill_in_uparams (state);
1586
1587   fs = __argp_make_fmtstream (stream, 0, uparams.rmargin, 0);
1588   if (! fs)
1589     {
1590 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1591       __funlockfile (stream);
1592 #endif
1593       return;
1594     }
1595
1596   if (flags & (ARGP_HELP_USAGE | ARGP_HELP_SHORT_USAGE | ARGP_HELP_LONG))
1597     {
1598       hol = argp_hol (argp, 0);
1599
1600       /* If present, these options always come last.  */
1601       hol_set_group (hol, "help", -1);
1602       hol_set_group (hol, "version", -1);
1603
1604       hol_sort (hol);
1605     }
1606
1607   if (flags & (ARGP_HELP_USAGE | ARGP_HELP_SHORT_USAGE))
1608     /* Print a short `Usage:' message.  */
1609     {
1610       int first_pattern = 1, more_patterns;
1611       size_t num_pattern_levels = argp_args_levels (argp);
1612       char *pattern_levels = alloca (num_pattern_levels);
1613
1614       memset (pattern_levels, 0, num_pattern_levels);
1615
1616       do
1617         {
1618           int old_lm;
1619           int old_wm = __argp_fmtstream_set_wmargin (fs, uparams.usage_indent);
1620           char *levels = pattern_levels;
1621
1622           if (first_pattern)
1623             __argp_fmtstream_printf (fs, "%s %s",
1624                                      dgettext (argp->argp_domain, "Usage:"),
1625                                      name);
1626           else
1627             __argp_fmtstream_printf (fs, "%s %s",
1628                                      dgettext (argp->argp_domain, "  or: "),
1629                                      name);
1630
1631           /* We set the lmargin as well as the wmargin, because hol_usage
1632              manually wraps options with newline to avoid annoying breaks.  */
1633           old_lm = __argp_fmtstream_set_lmargin (fs, uparams.usage_indent);
1634
1635           if (flags & ARGP_HELP_SHORT_USAGE)
1636             /* Just show where the options go.  */
1637             {
1638               if (hol->num_entries > 0)
1639                 __argp_fmtstream_puts (fs, dgettext (argp->argp_domain,
1640                                                      " [OPTION...]"));
1641             }
1642           else
1643             /* Actually print the options.  */
1644             {
1645               hol_usage (hol, fs);
1646               flags |= ARGP_HELP_SHORT_USAGE; /* But only do so once.  */
1647             }
1648
1649           more_patterns = argp_args_usage (argp, state, &levels, 1, fs);
1650
1651           __argp_fmtstream_set_wmargin (fs, old_wm);
1652           __argp_fmtstream_set_lmargin (fs, old_lm);
1653
1654           __argp_fmtstream_putc (fs, '\n');
1655           anything = 1;
1656
1657           first_pattern = 0;
1658         }
1659       while (more_patterns);
1660     }
1661
1662   if (flags & ARGP_HELP_PRE_DOC)
1663     anything |= argp_doc (argp, state, 0, 0, 1, fs);
1664
1665   if (flags & ARGP_HELP_SEE)
1666     {
1667       __argp_fmtstream_printf (fs, dgettext (argp->argp_domain, "\
1668 Try `%s --help' or `%s --usage' for more information.\n"),
1669                                name, name);
1670       anything = 1;
1671     }
1672
1673   if (flags & ARGP_HELP_LONG)
1674     /* Print a long, detailed help message.  */
1675     {
1676       /* Print info about all the options.  */
1677       if (hol->num_entries > 0)
1678         {
1679           if (anything)
1680             __argp_fmtstream_putc (fs, '\n');
1681           hol_help (hol, state, fs);
1682           anything = 1;
1683         }
1684     }
1685
1686   if (flags & ARGP_HELP_POST_DOC)
1687     /* Print any documentation strings at the end.  */
1688     anything |= argp_doc (argp, state, 1, anything, 0, fs);
1689
1690   if ((flags & ARGP_HELP_BUG_ADDR) && argp_program_bug_address)
1691     {
1692       if (anything)
1693         __argp_fmtstream_putc (fs, '\n');
1694       __argp_fmtstream_printf (fs, dgettext (argp->argp_domain,
1695                                              "Report bugs to %s.\n"),
1696                                argp_program_bug_address);
1697       anything = 1;
1698     }
1699
1700 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1701   __funlockfile (stream);
1702 #endif
1703
1704   if (hol)
1705     hol_free (hol);
1706
1707   __argp_fmtstream_free (fs);
1708 }
1709 \f
1710 /* Output a usage message for ARGP to STREAM.  FLAGS are from the set
1711    ARGP_HELP_*.  NAME is what to use wherever a `program name' is needed. */
1712 void __argp_help (const struct argp *argp, FILE *stream,
1713                   unsigned flags, char *name)
1714 {
1715   struct argp_state state;
1716   memset (&state, 0, sizeof state);
1717   state.root_argp = argp;
1718   _help (argp, &state, stream, flags, name);
1719 }
1720 #ifdef weak_alias
1721 weak_alias (__argp_help, argp_help)
1722 #endif
1723
1724 #if ! (defined _LIBC || HAVE_DECL_PROGRAM_INVOCATION_SHORT_NAME)
1725 char *
1726 __argp_short_program_name (void)
1727 {
1728 # if HAVE_DECL_PROGRAM_INVOCATION_NAME
1729   return __argp_base_name (program_invocation_name);
1730 # else
1731   /* FIXME: What now? Miles suggests that it is better to use NULL,
1732      but currently the value is passed on directly to fputs_unlocked,
1733      so that requires more changes. */
1734 # if __GNUC__
1735 #  warning No reasonable value to return
1736 # endif /* __GNUC__ */
1737   return "";
1738 # endif
1739 }
1740 #endif
1741
1742 /* Output, if appropriate, a usage message for STATE to STREAM.  FLAGS are
1743    from the set ARGP_HELP_*.  */
1744 void
1745 __argp_state_help (const struct argp_state *state, FILE *stream, unsigned flags)
1746 {
1747   if ((!state || ! (state->flags & ARGP_NO_ERRS)) && stream)
1748     {
1749       if (state && (state->flags & ARGP_LONG_ONLY))
1750         flags |= ARGP_HELP_LONG_ONLY;
1751
1752       _help (state ? state->root_argp : 0, state, stream, flags,
1753              state ? state->name : __argp_short_program_name ());
1754
1755       if (!state || ! (state->flags & ARGP_NO_EXIT))
1756         {
1757           if (flags & ARGP_HELP_EXIT_ERR)
1758             exit (argp_err_exit_status);
1759           if (flags & ARGP_HELP_EXIT_OK)
1760             exit (0);
1761         }
1762   }
1763 }
1764 #ifdef weak_alias
1765 weak_alias (__argp_state_help, argp_state_help)
1766 #endif
1767 \f
1768 /* If appropriate, print the printf string FMT and following args, preceded
1769    by the program name and `:', to stderr, and followed by a `Try ... --help'
1770    message, then exit (1).  */
1771 void
1772 __argp_error (const struct argp_state *state, const char *fmt, ...)
1773 {
1774   if (!state || !(state->flags & ARGP_NO_ERRS))
1775     {
1776       FILE *stream = state ? state->err_stream : stderr;
1777
1778       if (stream)
1779         {
1780           va_list ap;
1781
1782 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1783           __flockfile (stream);
1784 #endif
1785
1786           va_start (ap, fmt);
1787
1788 #ifdef USE_IN_LIBIO
1789           if (_IO_fwide (stream, 0) > 0)
1790             {
1791               char *buf;
1792
1793               if (__asprintf (&buf, fmt, ap) < 0)
1794                 buf = NULL;
1795
1796               __fwprintf (stream, L"%s: %s\n",
1797                           state ? state->name : __argp_short_program_name (),
1798                           buf);
1799
1800               free (buf);
1801             }
1802           else
1803 #endif
1804             {
1805               fputs_unlocked (state
1806                               ? state->name : __argp_short_program_name (),
1807                               stream);
1808               putc_unlocked (':', stream);
1809               putc_unlocked (' ', stream);
1810
1811               vfprintf (stream, fmt, ap);
1812
1813               putc_unlocked ('\n', stream);
1814             }
1815
1816           __argp_state_help (state, stream, ARGP_HELP_STD_ERR);
1817
1818           va_end (ap);
1819
1820 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1821           __funlockfile (stream);
1822 #endif
1823         }
1824     }
1825 }
1826 #ifdef weak_alias
1827 weak_alias (__argp_error, argp_error)
1828 #endif
1829 \f
1830 /* Similar to the standard gnu error-reporting function error(), but will
1831    respect the ARGP_NO_EXIT and ARGP_NO_ERRS flags in STATE, and will print
1832    to STATE->err_stream.  This is useful for argument parsing code that is
1833    shared between program startup (when exiting is desired) and runtime
1834    option parsing (when typically an error code is returned instead).  The
1835    difference between this function and argp_error is that the latter is for
1836    *parsing errors*, and the former is for other problems that occur during
1837    parsing but don't reflect a (syntactic) problem with the input.  */
1838 void
1839 __argp_failure (const struct argp_state *state, int status, int errnum,
1840                 const char *fmt, ...)
1841 {
1842   if (!state || !(state->flags & ARGP_NO_ERRS))
1843     {
1844       FILE *stream = state ? state->err_stream : stderr;
1845
1846       if (stream)
1847         {
1848 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1849           __flockfile (stream);
1850 #endif
1851
1852 #ifdef USE_IN_LIBIO
1853           if (_IO_fwide (stream, 0) > 0)
1854             __fwprintf (stream, L"%s",
1855                         state ? state->name : __argp_short_program_name ());
1856           else
1857 #endif
1858             fputs_unlocked (state
1859                             ? state->name : __argp_short_program_name (),
1860                             stream);
1861
1862           if (fmt)
1863             {
1864               va_list ap;
1865
1866               va_start (ap, fmt);
1867 #ifdef USE_IN_LIBIO
1868               if (_IO_fwide (stream, 0) > 0)
1869                 {
1870                   char *buf;
1871
1872                   if (__asprintf (&buf, fmt, ap) < 0)
1873                     buf = NULL;
1874
1875                   __fwprintf (stream, L": %s", buf);
1876
1877                   free (buf);
1878                 }
1879               else
1880 #endif
1881                 {
1882                   putc_unlocked (':', stream);
1883                   putc_unlocked (' ', stream);
1884
1885                   vfprintf (stream, fmt, ap);
1886                 }
1887
1888               va_end (ap);
1889             }
1890
1891           if (errnum)
1892             {
1893               char buf[200];
1894
1895 #ifdef USE_IN_LIBIO
1896               if (_IO_fwide (stream, 0) > 0)
1897                 __fwprintf (stream, L": %s",
1898                             __strerror_r (errnum, buf, sizeof (buf)));
1899               else
1900 #endif
1901                 {
1902                   char const *s = NULL;
1903                   putc_unlocked (':', stream);
1904                   putc_unlocked (' ', stream);
1905 #if _LIBC || (HAVE_DECL_STRERROR_R && STRERROR_R_CHAR_P)
1906                   s = __strerror_r (errnum, buf, sizeof buf);
1907 #elif HAVE_DECL_STRERROR_R
1908                   if (__strerror_r (errnum, buf, sizeof buf) == 0)
1909                     s = buf;
1910 #endif
1911 #if !_LIBC
1912                   if (! s && ! (s = strerror (errnum)))
1913                     s = dgettext (state->root_argp->argp_domain,
1914                                   "Unknown system error");
1915 #endif
1916                   fputs (s, stream);
1917                 }
1918             }
1919
1920 #ifdef USE_IN_LIBIO
1921           if (_IO_fwide (stream, 0) > 0)
1922             putwc_unlocked (L'\n', stream);
1923           else
1924 #endif
1925             putc_unlocked ('\n', stream);
1926
1927 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1928           __funlockfile (stream);
1929 #endif
1930
1931           if (status && (!state || !(state->flags & ARGP_NO_EXIT)))
1932             exit (status);
1933         }
1934     }
1935 }
1936 #ifdef weak_alias
1937 weak_alias (__argp_failure, argp_failure)
1938 #endif