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