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