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