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