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