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