Use _tolower instead of tolower if possible.
[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 = strchr (cp, '\n');
1380       if (nl)
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 = strchr (cp, '\n');
1388           (*levels)++;
1389         }
1390       if (! nl)
1391         nl = cp + strlen (cp);
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    occurance 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           fputs_unlocked (state ? state->name : program_invocation_short_name,
1709                           stream);
1710           putc_unlocked (':', stream);
1711           putc_unlocked (' ', stream);
1712
1713           va_start (ap, fmt);
1714           vfprintf (stream, fmt, ap);
1715           va_end (ap);
1716
1717           putc_unlocked ('\n', stream);
1718
1719           __argp_state_help (state, stream, ARGP_HELP_STD_ERR);
1720
1721           funlockfile (stream);
1722         }
1723     }
1724 }
1725 #ifdef weak_alias
1726 weak_alias (__argp_error, argp_error)
1727 #endif
1728 \f
1729 /* Similar to the standard gnu error-reporting function error(), but will
1730    respect the ARGP_NO_EXIT and ARGP_NO_ERRS flags in STATE, and will print
1731    to STATE->err_stream.  This is useful for argument parsing code that is
1732    shared between program startup (when exiting is desired) and runtime
1733    option parsing (when typically an error code is returned instead).  The
1734    difference between this function and argp_error is that the latter is for
1735    *parsing errors*, and the former is for other problems that occur during
1736    parsing but don't reflect a (syntactic) problem with the input.  */
1737 void
1738 __argp_failure (const struct argp_state *state, int status, int errnum,
1739                 const char *fmt, ...)
1740 {
1741   if (!state || !(state->flags & ARGP_NO_ERRS))
1742     {
1743       FILE *stream = state ? state->err_stream : stderr;
1744
1745       if (stream)
1746         {
1747           flockfile (stream);
1748
1749           fputs_unlocked (state ? state->name : program_invocation_short_name,
1750                           stream);
1751
1752           if (fmt)
1753             {
1754               va_list ap;
1755
1756               putc_unlocked (':', stream);
1757               putc_unlocked (' ', stream);
1758
1759               va_start (ap, fmt);
1760               vfprintf (stream, fmt, ap);
1761               va_end (ap);
1762             }
1763
1764           if (errnum)
1765             {
1766               putc_unlocked (':', stream);
1767               putc_unlocked (' ', stream);
1768               fputs (strerror (errnum), stream);
1769             }
1770
1771           putc_unlocked ('\n', stream);
1772
1773           funlockfile (stream);
1774
1775           if (status && (!state || !(state->flags & ARGP_NO_EXIT)))
1776             exit (status);
1777         }
1778     }
1779 }
1780 #ifdef weak_alias
1781 weak_alias (__argp_failure, argp_failure)
1782 #endif