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