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