Fixup indentation.
[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               {
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           int lower_cmp = tolower (first1) - tolower (first2);
763           /* Compare ignoring case, except when the options are both the
764              same letter, in which case lower-case always comes first.  */
765           return lower_cmp ? lower_cmp : first2 - first1;
766         }
767     }
768   else
769     /* Within the same cluster, but not the same group, so just compare
770        groups.  */
771     return group_cmp (group1, group2, 0);
772 }
773
774 /* Version of hol_entry_cmp with correct signature for qsort.  */
775 static int
776 hol_entry_qcmp (const void *entry1_v, const void *entry2_v)
777 {
778   return hol_entry_cmp (entry1_v, entry2_v);
779 }
780
781 /* Sort HOL by group and alphabetically by option name (with short options
782    taking precedence over long).  Since the sorting is for display purposes
783    only, the shadowing of options isn't effected.  */
784 static void
785 hol_sort (struct hol *hol)
786 {
787   if (hol->num_entries > 0)
788     qsort (hol->entries, hol->num_entries, sizeof (struct hol_entry),
789            hol_entry_qcmp);
790 }
791 \f
792 /* Append MORE to HOL, destroying MORE in the process.  Options in HOL shadow
793    any in MORE with the same name.  */
794 static void
795 hol_append (struct hol *hol, struct hol *more)
796 {
797   struct hol_cluster **cl_end = &hol->clusters;
798
799   /* Steal MORE's cluster list, and add it to the end of HOL's.  */
800   while (*cl_end)
801     cl_end = &(*cl_end)->next;
802   *cl_end = more->clusters;
803   more->clusters = 0;
804
805   /* Merge entries.  */
806   if (more->num_entries > 0)
807     {
808       if (hol->num_entries == 0)
809         {
810           hol->num_entries = more->num_entries;
811           hol->entries = more->entries;
812           hol->short_options = more->short_options;
813           more->num_entries = 0;        /* Mark MORE's fields as invalid.  */
814         }
815       else
816         /* Append the entries in MORE to those in HOL, taking care to only add
817            non-shadowed SHORT_OPTIONS values.  */
818         {
819           unsigned left;
820           char *so, *more_so;
821           struct hol_entry *e;
822           unsigned num_entries = hol->num_entries + more->num_entries;
823           struct hol_entry *entries =
824             malloc (num_entries * sizeof (struct hol_entry));
825           unsigned hol_so_len = strlen (hol->short_options);
826           char *short_options =
827             malloc (hol_so_len + strlen (more->short_options) + 1);
828
829           __mempcpy (__mempcpy (entries, hol->entries,
830                                 hol->num_entries * sizeof (struct hol_entry)),
831                      more->entries,
832                      more->num_entries * sizeof (struct hol_entry));
833
834           __mempcpy (short_options, hol->short_options, hol_so_len);
835
836           /* Fix up the short options pointers from HOL.  */
837           for (e = entries, left = hol->num_entries; left > 0; e++, left--)
838             e->short_options += (short_options - hol->short_options);
839
840           /* Now add the short options from MORE, fixing up its entries
841              too.  */
842           so = short_options + hol_so_len;
843           more_so = more->short_options;
844           for (left = more->num_entries; left > 0; e++, left--)
845             {
846               int opts_left;
847               const struct argp_option *opt;
848
849               e->short_options = so;
850
851               for (opts_left = e->num, opt = e->opt; opts_left; opt++, opts_left--)
852                 {
853                   int ch = *more_so;
854                   if (oshort (opt) && ch == opt->key)
855                     /* The next short option in MORE_SO, CH, is from OPT.  */
856                     {
857                       if (! find_char (ch, short_options,
858                                        short_options + hol_so_len))
859                         /* The short option CH isn't shadowed by HOL's options,
860                            so add it to the sum.  */
861                         *so++ = ch;
862                       more_so++;
863                     }
864                 }
865             }
866
867           *so = '\0';
868
869           free (hol->entries);
870           free (hol->short_options);
871
872           hol->entries = entries;
873           hol->num_entries = num_entries;
874           hol->short_options = short_options;
875         }
876     }
877
878   hol_free (more);
879 }
880 \f
881 /* Inserts enough spaces to make sure STREAM is at column COL.  */
882 static void
883 indent_to (argp_fmtstream_t stream, unsigned col)
884 {
885   int needed = col - __argp_fmtstream_point (stream);
886   while (needed-- > 0)
887     __argp_fmtstream_putc (stream, ' ');
888 }
889
890 /* Output to STREAM either a space, or a newline if there isn't room for at
891    least ENSURE characters before the right margin.  */
892 static void
893 space (argp_fmtstream_t stream, size_t ensure)
894 {
895   if (__argp_fmtstream_point (stream) + ensure
896       >= __argp_fmtstream_rmargin (stream))
897     __argp_fmtstream_putc (stream, '\n');
898   else
899     __argp_fmtstream_putc (stream, ' ');
900 }
901
902 /* If the option REAL has an argument, we print it in using the printf
903    format REQ_FMT or OPT_FMT depending on whether it's a required or
904    optional argument.  */
905 static void
906 arg (const struct argp_option *real, const char *req_fmt, const char *opt_fmt,
907      const char *domain, argp_fmtstream_t stream)
908 {
909   if (real->arg)
910     {
911       if (real->flags & OPTION_ARG_OPTIONAL)
912         __argp_fmtstream_printf (stream, opt_fmt,
913                                  dgettext (domain, real->arg));
914       else
915         __argp_fmtstream_printf (stream, req_fmt,
916                                  dgettext (domain, real->arg));
917     }
918 }
919 \f
920 /* Helper functions for hol_entry_help.  */
921
922 /* State used during the execution of hol_help.  */
923 struct hol_help_state
924 {
925   /* PREV_ENTRY should contain the previous entry printed, or 0.  */
926   struct hol_entry *prev_entry;
927
928   /* If an entry is in a different group from the previous one, and SEP_GROUPS
929      is true, then a blank line will be printed before any output. */
930   int sep_groups;
931
932   /* True if a duplicate option argument was suppressed (only ever set if
933      UPARAMS.dup_args is false).  */
934   int suppressed_dup_arg;
935 };
936
937 /* Some state used while printing a help entry (used to communicate with
938    helper functions).  See the doc for hol_entry_help for more info, as most
939    of the fields are copied from its arguments.  */
940 struct pentry_state
941 {
942   const struct hol_entry *entry;
943   argp_fmtstream_t stream;
944   struct hol_help_state *hhstate;
945
946   /* True if nothing's been printed so far.  */
947   int first;
948
949   /* If non-zero, the state that was used to print this help.  */
950   const struct argp_state *state;
951 };
952
953 /* If a user doc filter should be applied to DOC, do so.  */
954 static const char *
955 filter_doc (const char *doc, int key, const struct argp *argp,
956             const struct argp_state *state)
957 {
958   if (argp->help_filter)
959     /* We must apply a user filter to this output.  */
960     {
961       void *input = __argp_input (argp, state);
962       return (*argp->help_filter) (key, doc, input);
963     }
964   else
965     /* No filter.  */
966     return doc;
967 }
968
969 /* Prints STR as a header line, with the margin lines set appropiately, and
970    notes the fact that groups should be separated with a blank line.  ARGP is
971    the argp that should dictate any user doc filtering to take place.  Note
972    that the previous wrap margin isn't restored, but the left margin is reset
973    to 0.  */
974 static void
975 print_header (const char *str, const struct argp *argp,
976               struct pentry_state *pest)
977 {
978   const char *tstr = dgettext (argp->argp_domain, str);
979   const char *fstr = filter_doc (tstr, ARGP_KEY_HELP_HEADER, argp, pest->state);
980
981   if (fstr)
982     {
983       if (*fstr)
984         {
985           if (pest->hhstate->prev_entry)
986             /* Precede with a blank line.  */
987             __argp_fmtstream_putc (pest->stream, '\n');
988           indent_to (pest->stream, uparams.header_col);
989           __argp_fmtstream_set_lmargin (pest->stream, uparams.header_col);
990           __argp_fmtstream_set_wmargin (pest->stream, uparams.header_col);
991           __argp_fmtstream_puts (pest->stream, fstr);
992           __argp_fmtstream_set_lmargin (pest->stream, 0);
993           __argp_fmtstream_putc (pest->stream, '\n');
994         }
995
996       pest->hhstate->sep_groups = 1; /* Separate subsequent groups. */
997     }
998
999   if (fstr != tstr)
1000     free ((char *) fstr);
1001 }
1002
1003 /* Inserts a comma if this isn't the first item on the line, and then makes
1004    sure we're at least to column COL.  If this *is* the first item on a line,
1005    prints any pending whitespace/headers that should precede this line. Also
1006    clears FIRST.  */
1007 static void
1008 comma (unsigned col, struct pentry_state *pest)
1009 {
1010   if (pest->first)
1011     {
1012       const struct hol_entry *pe = pest->hhstate->prev_entry;
1013       const struct hol_cluster *cl = pest->entry->cluster;
1014
1015       if (pest->hhstate->sep_groups && pe && pest->entry->group != pe->group)
1016         __argp_fmtstream_putc (pest->stream, '\n');
1017
1018       if (cl && cl->header && *cl->header
1019           && (!pe
1020               || (pe->cluster != cl
1021                   && !hol_cluster_is_child (pe->cluster, cl))))
1022         /* If we're changing clusters, then this must be the start of the
1023            ENTRY's cluster unless that is an ancestor of the previous one
1024            (in which case we had just popped into a sub-cluster for a bit).
1025            If so, then print the cluster's header line.  */
1026         {
1027           int old_wm = __argp_fmtstream_wmargin (pest->stream);
1028           print_header (cl->header, cl->argp, pest);
1029           __argp_fmtstream_set_wmargin (pest->stream, old_wm);
1030         }
1031
1032       pest->first = 0;
1033     }
1034   else
1035     __argp_fmtstream_puts (pest->stream, ", ");
1036
1037   indent_to (pest->stream, col);
1038 }
1039 \f
1040 /* Print help for ENTRY to STREAM.  */
1041 static void
1042 hol_entry_help (struct hol_entry *entry, const struct argp_state *state,
1043                 argp_fmtstream_t stream, struct hol_help_state *hhstate)
1044 {
1045   unsigned num;
1046   const struct argp_option *real = entry->opt, *opt;
1047   char *so = entry->short_options;
1048   int have_long_opt = 0;        /* We have any long options.  */
1049   /* Saved margins.  */
1050   int old_lm = __argp_fmtstream_set_lmargin (stream, 0);
1051   int old_wm = __argp_fmtstream_wmargin (stream);
1052   /* PEST is a state block holding some of our variables that we'd like to
1053      share with helper functions.  */
1054   struct pentry_state pest = { entry, stream, hhstate, 1, state };
1055
1056   if (! odoc (real))
1057     for (opt = real, num = entry->num; num > 0; opt++, num--)
1058       if (opt->name && ovisible (opt))
1059         {
1060           have_long_opt = 1;
1061           break;
1062         }
1063
1064   /* First emit short options.  */
1065   __argp_fmtstream_set_wmargin (stream, uparams.short_opt_col); /* For truly bizarre cases. */
1066   for (opt = real, num = entry->num; num > 0; opt++, num--)
1067     if (oshort (opt) && opt->key == *so)
1068       /* OPT has a valid (non shadowed) short option.  */
1069       {
1070         if (ovisible (opt))
1071           {
1072             comma (uparams.short_opt_col, &pest);
1073             __argp_fmtstream_putc (stream, '-');
1074             __argp_fmtstream_putc (stream, *so);
1075             if (!have_long_opt || uparams.dup_args)
1076               arg (real, " %s", "[%s]", state->root_argp->argp_domain, stream);
1077             else if (real->arg)
1078               hhstate->suppressed_dup_arg = 1;
1079           }
1080         so++;
1081       }
1082
1083   /* Now, long options.  */
1084   if (odoc (real))
1085     /* A `documentation' option.  */
1086     {
1087       __argp_fmtstream_set_wmargin (stream, uparams.doc_opt_col);
1088       for (opt = real, num = entry->num; num > 0; opt++, num--)
1089         if (opt->name && ovisible (opt))
1090           {
1091             comma (uparams.doc_opt_col, &pest);
1092             /* Calling gettext here isn't quite right, since sorting will
1093                have been done on the original; but documentation options
1094                should be pretty rare anyway...  */
1095             __argp_fmtstream_puts (stream,
1096                                    dgettext (state->root_argp->argp_domain,
1097                                              opt->name));
1098           }
1099     }
1100   else
1101     /* A real long option.  */
1102     {
1103       int first_long_opt = 1;
1104
1105       __argp_fmtstream_set_wmargin (stream, uparams.long_opt_col);
1106       for (opt = real, num = entry->num; num > 0; opt++, num--)
1107         if (opt->name && ovisible (opt))
1108           {
1109             comma (uparams.long_opt_col, &pest);
1110             __argp_fmtstream_printf (stream, "--%s", opt->name);
1111             if (first_long_opt || uparams.dup_args)
1112               arg (real, "=%s", "[=%s]", state->root_argp->argp_domain,
1113                    stream);
1114             else if (real->arg)
1115               hhstate->suppressed_dup_arg = 1;
1116           }
1117     }
1118
1119   /* Next, documentation strings.  */
1120   __argp_fmtstream_set_lmargin (stream, 0);
1121
1122   if (pest.first)
1123     {
1124       /* Didn't print any switches, what's up?  */
1125       if (!oshort (real) && !real->name)
1126         /* This is a group header, print it nicely.  */
1127         print_header (real->doc, entry->argp, &pest);
1128       else
1129         /* Just a totally shadowed option or null header; print nothing.  */
1130         goto cleanup;           /* Just return, after cleaning up.  */
1131     }
1132   else
1133     {
1134       const char *tstr = real->doc ? dgettext (state->root_argp->argp_domain,
1135                                                real->doc) : 0;
1136       const char *fstr = filter_doc (tstr, real->key, entry->argp, state);
1137       if (fstr && *fstr)
1138         {
1139           unsigned int col = __argp_fmtstream_point (stream);
1140
1141           __argp_fmtstream_set_lmargin (stream, uparams.opt_doc_col);
1142           __argp_fmtstream_set_wmargin (stream, uparams.opt_doc_col);
1143
1144           if (col > (unsigned int) (uparams.opt_doc_col + 3))
1145             __argp_fmtstream_putc (stream, '\n');
1146           else if (col >= (unsigned int) uparams.opt_doc_col)
1147             __argp_fmtstream_puts (stream, "   ");
1148           else
1149             indent_to (stream, uparams.opt_doc_col);
1150
1151           __argp_fmtstream_puts (stream, fstr);
1152         }
1153       if (fstr && fstr != tstr)
1154         free ((char *) fstr);
1155
1156       /* Reset the left margin.  */
1157       __argp_fmtstream_set_lmargin (stream, 0);
1158       __argp_fmtstream_putc (stream, '\n');
1159     }
1160
1161   hhstate->prev_entry = entry;
1162
1163 cleanup:
1164   __argp_fmtstream_set_lmargin (stream, old_lm);
1165   __argp_fmtstream_set_wmargin (stream, old_wm);
1166 }
1167 \f
1168 /* Output a long help message about the options in HOL to STREAM.  */
1169 static void
1170 hol_help (struct hol *hol, const struct argp_state *state,
1171           argp_fmtstream_t stream)
1172 {
1173   unsigned num;
1174   struct hol_entry *entry;
1175   struct hol_help_state hhstate = { 0, 0, 0 };
1176
1177   for (entry = hol->entries, num = hol->num_entries; num > 0; entry++, num--)
1178     hol_entry_help (entry, state, stream, &hhstate);
1179
1180   if (hhstate.suppressed_dup_arg && uparams.dup_args_note)
1181     {
1182       const char *tstr = dgettext (state->root_argp->argp_domain, "\
1183 Mandatory or optional arguments to long options are also mandatory or \
1184 optional for any corresponding short options.");
1185       const char *fstr = filter_doc (tstr, ARGP_KEY_HELP_DUP_ARGS_NOTE,
1186                                      state ? state->root_argp : 0, state);
1187       if (fstr && *fstr)
1188         {
1189           __argp_fmtstream_putc (stream, '\n');
1190           __argp_fmtstream_puts (stream, fstr);
1191           __argp_fmtstream_putc (stream, '\n');
1192         }
1193       if (fstr && fstr != tstr)
1194         free ((char *) fstr);
1195     }
1196 }
1197 \f
1198 /* Helper functions for hol_usage.  */
1199
1200 /* If OPT is a short option without an arg, append its key to the string
1201    pointer pointer to by COOKIE, and advance the pointer.  */
1202 static int
1203 add_argless_short_opt (const struct argp_option *opt,
1204                        const struct argp_option *real,
1205                        const char *domain, void *cookie)
1206 {
1207   char **snao_end = cookie;
1208   if (!(opt->arg || real->arg)
1209       && !((opt->flags | real->flags) & OPTION_NO_USAGE))
1210     *(*snao_end)++ = opt->key;
1211   return 0;
1212 }
1213
1214 /* If OPT is a short option with an arg, output a usage entry for it to the
1215    stream pointed at by COOKIE.  */
1216 static int
1217 usage_argful_short_opt (const struct argp_option *opt,
1218                         const struct argp_option *real,
1219                         const char *domain, void *cookie)
1220 {
1221   argp_fmtstream_t stream = cookie;
1222   const char *arg = opt->arg;
1223   int flags = opt->flags | real->flags;
1224
1225   if (! arg)
1226     arg = real->arg;
1227
1228   if (arg && !(flags & OPTION_NO_USAGE))
1229     {
1230       arg = dgettext (domain, arg);
1231
1232       if (flags & OPTION_ARG_OPTIONAL)
1233         __argp_fmtstream_printf (stream, " [-%c[%s]]", opt->key, arg);
1234       else
1235         {
1236           /* Manually do line wrapping so that it (probably) won't
1237              get wrapped at the embedded space.  */
1238           space (stream, 6 + strlen (arg));
1239           __argp_fmtstream_printf (stream, "[-%c %s]", opt->key, arg);
1240         }
1241     }
1242
1243   return 0;
1244 }
1245
1246 /* Output a usage entry for the long option opt to the stream pointed at by
1247    COOKIE.  */
1248 static int
1249 usage_long_opt (const struct argp_option *opt,
1250                 const struct argp_option *real,
1251                 const char *domain, void *cookie)
1252 {
1253   argp_fmtstream_t stream = cookie;
1254   const char *arg = opt->arg;
1255   int flags = opt->flags | real->flags;
1256
1257   if (! arg)
1258     arg = real->arg;
1259
1260   if (! (flags & OPTION_NO_USAGE))
1261     {
1262       if (arg)
1263         {
1264           arg = dgettext (domain, arg);
1265           if (flags & OPTION_ARG_OPTIONAL)
1266             __argp_fmtstream_printf (stream, " [--%s[=%s]]", opt->name, arg);
1267           else
1268             __argp_fmtstream_printf (stream, " [--%s=%s]", opt->name, arg);
1269         }
1270       else
1271         __argp_fmtstream_printf (stream, " [--%s]", opt->name);
1272     }
1273
1274   return 0;
1275 }
1276 \f
1277 /* Print a short usage description for the arguments in HOL to STREAM.  */
1278 static void
1279 hol_usage (struct hol *hol, argp_fmtstream_t stream)
1280 {
1281   if (hol->num_entries > 0)
1282     {
1283       unsigned nentries;
1284       struct hol_entry *entry;
1285       char *short_no_arg_opts = alloca (strlen (hol->short_options) + 1);
1286       char *snao_end = short_no_arg_opts;
1287
1288       /* First we put a list of short options without arguments.  */
1289       for (entry = hol->entries, nentries = hol->num_entries
1290            ; nentries > 0
1291            ; entry++, nentries--)
1292         hol_entry_short_iterate (entry, add_argless_short_opt,
1293                                  entry->argp->argp_domain, &snao_end);
1294       if (snao_end > short_no_arg_opts)
1295         {
1296           *snao_end++ = 0;
1297           __argp_fmtstream_printf (stream, " [-%s]", short_no_arg_opts);
1298         }
1299
1300       /* Now a list of short options *with* arguments.  */
1301       for (entry = hol->entries, nentries = hol->num_entries
1302            ; nentries > 0
1303            ; entry++, nentries--)
1304         hol_entry_short_iterate (entry, usage_argful_short_opt,
1305                                  entry->argp->argp_domain, stream);
1306
1307       /* Finally, a list of long options (whew!).  */
1308       for (entry = hol->entries, nentries = hol->num_entries
1309            ; nentries > 0
1310            ; entry++, nentries--)
1311         hol_entry_long_iterate (entry, usage_long_opt,
1312                                 entry->argp->argp_domain, stream);
1313     }
1314 }
1315 \f
1316 /* Make a HOL containing all levels of options in ARGP.  CLUSTER is the
1317    cluster in which ARGP's entries should be clustered, or 0.  */
1318 static struct hol *
1319 argp_hol (const struct argp *argp, struct hol_cluster *cluster)
1320 {
1321   const struct argp_child *child = argp->children;
1322   struct hol *hol = make_hol (argp, cluster);
1323   if (child)
1324     while (child->argp)
1325       {
1326         struct hol_cluster *child_cluster =
1327           ((child->group || child->header)
1328            /* Put CHILD->argp within its own cluster.  */
1329            ? hol_add_cluster (hol, child->group, child->header,
1330                               child - argp->children, cluster, argp)
1331            /* Just merge it into the parent's cluster.  */
1332            : cluster);
1333         hol_append (hol, argp_hol (child->argp, child_cluster)) ;
1334         child++;
1335       }
1336   return hol;
1337 }
1338 \f
1339 /* Calculate how many different levels with alternative args strings exist in
1340    ARGP.  */
1341 static size_t
1342 argp_args_levels (const struct argp *argp)
1343 {
1344   size_t levels = 0;
1345   const struct argp_child *child = argp->children;
1346
1347   if (argp->args_doc && strchr (argp->args_doc, '\n'))
1348     levels++;
1349
1350   if (child)
1351     while (child->argp)
1352       levels += argp_args_levels ((child++)->argp);
1353
1354   return levels;
1355 }
1356
1357 /* Print all the non-option args documented in ARGP to STREAM.  Any output is
1358    preceded by a space.  LEVELS is a pointer to a byte vector the length
1359    returned by argp_args_levels; it should be initialized to zero, and
1360    updated by this routine for the next call if ADVANCE is true.  True is
1361    returned as long as there are more patterns to output.  */
1362 static int
1363 argp_args_usage (const struct argp *argp, const struct argp_state *state,
1364                  char **levels, int advance, argp_fmtstream_t stream)
1365 {
1366   char *our_level = *levels;
1367   int multiple = 0;
1368   const struct argp_child *child = argp->children;
1369   const char *tdoc = dgettext (argp->argp_domain, argp->args_doc), *nl = 0;
1370   const char *fdoc = filter_doc (tdoc, ARGP_KEY_HELP_ARGS_DOC, argp, state);
1371
1372   if (fdoc)
1373     {
1374       const char *cp = fdoc;
1375       nl = strchr (cp, '\n');
1376       if (nl)
1377         /* This is a `multi-level' args doc; advance to the correct position
1378            as determined by our state in LEVELS, and update LEVELS.  */
1379         {
1380           int i;
1381           multiple = 1;
1382           for (i = 0; i < *our_level; i++)
1383             cp = nl + 1, nl = strchr (cp, '\n');
1384           (*levels)++;
1385         }
1386       if (! nl)
1387         nl = cp + strlen (cp);
1388
1389       /* Manually do line wrapping so that it (probably) won't get wrapped at
1390          any embedded spaces.  */
1391       space (stream, 1 + nl - cp);
1392
1393       __argp_fmtstream_write (stream, cp, nl - cp);
1394     }
1395   if (fdoc && fdoc != tdoc)
1396     free ((char *)fdoc);        /* Free user's modified doc string.  */
1397
1398   if (child)
1399     while (child->argp)
1400       advance = !argp_args_usage ((child++)->argp, state, levels, advance, stream);
1401
1402   if (advance && multiple)
1403     {
1404       /* Need to increment our level.  */
1405       if (*nl)
1406         /* There's more we can do here.  */
1407         {
1408           (*our_level)++;
1409           advance = 0;          /* Our parent shouldn't advance also. */
1410         }
1411       else if (*our_level > 0)
1412         /* We had multiple levels, but used them up; reset to zero.  */
1413         *our_level = 0;
1414     }
1415
1416   return !advance;
1417 }
1418 \f
1419 /* Print the documentation for ARGP to STREAM; if POST is false, then
1420    everything preceeding a `\v' character in the documentation strings (or
1421    the whole string, for those with none) is printed, otherwise, everything
1422    following the `\v' character (nothing for strings without).  Each separate
1423    bit of documentation is separated a blank line, and if PRE_BLANK is true,
1424    then the first is as well.  If FIRST_ONLY is true, only the first
1425    occurance is output.  Returns true if anything was output.  */
1426 static int
1427 argp_doc (const struct argp *argp, const struct argp_state *state,
1428           int post, int pre_blank, int first_only,
1429           argp_fmtstream_t stream)
1430 {
1431   const char *text;
1432   const char *inp_text;
1433   void *input = 0;
1434   int anything = 0;
1435   size_t inp_text_limit = 0;
1436   const char *doc = dgettext (argp->argp_domain, argp->doc);
1437   const struct argp_child *child = argp->children;
1438
1439   if (doc)
1440     {
1441       char *vt = strchr (doc, '\v');
1442       inp_text = post ? (vt ? vt + 1 : 0) : doc;
1443       inp_text_limit = (!post && vt) ? (vt - doc) : 0;
1444     }
1445   else
1446     inp_text = 0;
1447
1448   if (argp->help_filter)
1449     /* We have to filter the doc strings.  */
1450     {
1451       if (inp_text_limit)
1452         /* Copy INP_TEXT so that it's nul-terminated.  */
1453         inp_text = __strndup (inp_text, inp_text_limit);
1454       input = __argp_input (argp, state);
1455       text =
1456         (*argp->help_filter) (post
1457                               ? ARGP_KEY_HELP_POST_DOC
1458                               : ARGP_KEY_HELP_PRE_DOC,
1459                               inp_text, input);
1460     }
1461   else
1462     text = (const char *) inp_text;
1463
1464   if (text)
1465     {
1466       if (pre_blank)
1467         __argp_fmtstream_putc (stream, '\n');
1468
1469       if (text == inp_text && inp_text_limit)
1470         __argp_fmtstream_write (stream, inp_text, inp_text_limit);
1471       else
1472         __argp_fmtstream_puts (stream, text);
1473
1474       if (__argp_fmtstream_point (stream) > __argp_fmtstream_lmargin (stream))
1475         __argp_fmtstream_putc (stream, '\n');
1476
1477       anything = 1;
1478     }
1479
1480   if (text && text != inp_text)
1481     free ((char *) text);       /* Free TEXT returned from the help filter.  */
1482   if (inp_text && inp_text_limit && argp->help_filter)
1483     free ((char *) inp_text);   /* We copied INP_TEXT, so free it now.  */
1484
1485   if (post && argp->help_filter)
1486     /* Now see if we have to output a ARGP_KEY_HELP_EXTRA text.  */
1487     {
1488       text = (*argp->help_filter) (ARGP_KEY_HELP_EXTRA, 0, input);
1489       if (text)
1490         {
1491           if (anything || pre_blank)
1492             __argp_fmtstream_putc (stream, '\n');
1493           __argp_fmtstream_puts (stream, text);
1494           free ((char *) text);
1495           if (__argp_fmtstream_point (stream)
1496               > __argp_fmtstream_lmargin (stream))
1497             __argp_fmtstream_putc (stream, '\n');
1498           anything = 1;
1499         }
1500     }
1501
1502   if (child)
1503     while (child->argp && !(first_only && anything))
1504       anything |=
1505         argp_doc ((child++)->argp, state,
1506                   post, anything || pre_blank, first_only,
1507                   stream);
1508
1509   return anything;
1510 }
1511 \f
1512 /* Output a usage message for ARGP to STREAM.  If called from
1513    argp_state_help, STATE is the relevent parsing state.  FLAGS are from the
1514    set ARGP_HELP_*.  NAME is what to use wherever a `program name' is
1515    needed. */
1516 static void
1517 _help (const struct argp *argp, const struct argp_state *state, FILE *stream,
1518        unsigned flags, char *name)
1519 {
1520   int anything = 0;             /* Whether we've output anything.  */
1521   struct hol *hol = 0;
1522   argp_fmtstream_t fs;
1523
1524   if (! stream)
1525     return;
1526
1527   flockfile (stream);
1528
1529   if (! uparams.valid)
1530     fill_in_uparams (state);
1531
1532   fs = __argp_make_fmtstream (stream, 0, uparams.rmargin, 0);
1533   if (! fs)
1534     {
1535       funlockfile (stream);
1536       return;
1537     }
1538
1539   if (flags & (ARGP_HELP_USAGE | ARGP_HELP_SHORT_USAGE | ARGP_HELP_LONG))
1540     {
1541       hol = argp_hol (argp, 0);
1542
1543       /* If present, these options always come last.  */
1544       hol_set_group (hol, "help", -1);
1545       hol_set_group (hol, "version", -1);
1546
1547       hol_sort (hol);
1548     }
1549
1550   if (flags & (ARGP_HELP_USAGE | ARGP_HELP_SHORT_USAGE))
1551     /* Print a short `Usage:' message.  */
1552     {
1553       int first_pattern = 1, more_patterns;
1554       size_t num_pattern_levels = argp_args_levels (argp);
1555       char *pattern_levels = alloca (num_pattern_levels);
1556
1557       memset (pattern_levels, 0, num_pattern_levels);
1558
1559       do
1560         {
1561           int old_lm;
1562           int old_wm = __argp_fmtstream_set_wmargin (fs, uparams.usage_indent);
1563           char *levels = pattern_levels;
1564
1565           if (first_pattern)
1566             __argp_fmtstream_printf (fs, "%s %s",
1567                                      dgettext (argp->argp_domain, "Usage:"),
1568                                      name);
1569           else
1570             __argp_fmtstream_printf (fs, "%s %s",
1571                                      dgettext (argp->argp_domain, "  or: "),
1572                                      name);
1573
1574           /* We set the lmargin as well as the wmargin, because hol_usage
1575              manually wraps options with newline to avoid annoying breaks.  */
1576           old_lm = __argp_fmtstream_set_lmargin (fs, uparams.usage_indent);
1577
1578           if (flags & ARGP_HELP_SHORT_USAGE)
1579             /* Just show where the options go.  */
1580             {
1581               if (hol->num_entries > 0)
1582                 __argp_fmtstream_puts (fs, dgettext (argp->argp_domain,
1583                                                      " [OPTION...]"));
1584             }
1585           else
1586             /* Actually print the options.  */
1587             {
1588               hol_usage (hol, fs);
1589               flags |= ARGP_HELP_SHORT_USAGE; /* But only do so once.  */
1590             }
1591
1592           more_patterns = argp_args_usage (argp, state, &levels, 1, fs);
1593
1594           __argp_fmtstream_set_wmargin (fs, old_wm);
1595           __argp_fmtstream_set_lmargin (fs, old_lm);
1596
1597           __argp_fmtstream_putc (fs, '\n');
1598           anything = 1;
1599
1600           first_pattern = 0;
1601         }
1602       while (more_patterns);
1603     }
1604
1605   if (flags & ARGP_HELP_PRE_DOC)
1606     anything |= argp_doc (argp, state, 0, 0, 1, fs);
1607
1608   if (flags & ARGP_HELP_SEE)
1609     {
1610       __argp_fmtstream_printf (fs, dgettext (argp->argp_domain, "\
1611 Try `%s --help' or `%s --usage' for more information.\n"),
1612                                name, name);
1613       anything = 1;
1614     }
1615
1616   if (flags & ARGP_HELP_LONG)
1617     /* Print a long, detailed help message.  */
1618     {
1619       /* Print info about all the options.  */
1620       if (hol->num_entries > 0)
1621         {
1622           if (anything)
1623             __argp_fmtstream_putc (fs, '\n');
1624           hol_help (hol, state, fs);
1625           anything = 1;
1626         }
1627     }
1628
1629   if (flags & ARGP_HELP_POST_DOC)
1630     /* Print any documentation strings at the end.  */
1631     anything |= argp_doc (argp, state, 1, anything, 0, fs);
1632
1633   if ((flags & ARGP_HELP_BUG_ADDR) && argp_program_bug_address)
1634     {
1635       if (anything)
1636         __argp_fmtstream_putc (fs, '\n');
1637       __argp_fmtstream_printf (fs, dgettext (argp->argp_domain,
1638                                              "Report bugs to %s.\n"),
1639                                argp_program_bug_address);
1640       anything = 1;
1641     }
1642
1643   funlockfile (stream);
1644
1645   if (hol)
1646     hol_free (hol);
1647
1648   __argp_fmtstream_free (fs);
1649 }
1650 \f
1651 /* Output a usage message for ARGP to STREAM.  FLAGS are from the set
1652    ARGP_HELP_*.  NAME is what to use wherever a `program name' is needed. */
1653 void __argp_help (const struct argp *argp, FILE *stream,
1654                   unsigned flags, char *name)
1655 {
1656   _help (argp, 0, stream, flags, name);
1657 }
1658 #ifdef weak_alias
1659 weak_alias (__argp_help, argp_help)
1660 #endif
1661
1662 /* Output, if appropriate, a usage message for STATE to STREAM.  FLAGS are
1663    from the set ARGP_HELP_*.  */
1664 void
1665 __argp_state_help (const struct argp_state *state, FILE *stream, unsigned flags)
1666 {
1667   if ((!state || ! (state->flags & ARGP_NO_ERRS)) && stream)
1668     {
1669       if (state && (state->flags & ARGP_LONG_ONLY))
1670         flags |= ARGP_HELP_LONG_ONLY;
1671
1672       _help (state ? state->root_argp : 0, state, stream, flags,
1673              state ? state->name : program_invocation_short_name);
1674
1675       if (!state || ! (state->flags & ARGP_NO_EXIT))
1676         {
1677           if (flags & ARGP_HELP_EXIT_ERR)
1678             exit (argp_err_exit_status);
1679           if (flags & ARGP_HELP_EXIT_OK)
1680             exit (0);
1681         }
1682   }
1683 }
1684 #ifdef weak_alias
1685 weak_alias (__argp_state_help, argp_state_help)
1686 #endif
1687 \f
1688 /* If appropriate, print the printf string FMT and following args, preceded
1689    by the program name and `:', to stderr, and followed by a `Try ... --help'
1690    message, then exit (1).  */
1691 void
1692 __argp_error (const struct argp_state *state, const char *fmt, ...)
1693 {
1694   if (!state || !(state->flags & ARGP_NO_ERRS))
1695     {
1696       FILE *stream = state ? state->err_stream : stderr;
1697
1698       if (stream)
1699         {
1700           va_list ap;
1701
1702           flockfile (stream);
1703
1704           fputs_unlocked (state ? state->name : program_invocation_short_name,
1705                           stream);
1706           putc_unlocked (':', stream);
1707           putc_unlocked (' ', stream);
1708
1709           va_start (ap, fmt);
1710           vfprintf (stream, fmt, ap);
1711           va_end (ap);
1712
1713           putc_unlocked ('\n', stream);
1714
1715           __argp_state_help (state, stream, ARGP_HELP_STD_ERR);
1716
1717           funlockfile (stream);
1718         }
1719     }
1720 }
1721 #ifdef weak_alias
1722 weak_alias (__argp_error, argp_error)
1723 #endif
1724 \f
1725 /* Similar to the standard gnu error-reporting function error(), but will
1726    respect the ARGP_NO_EXIT and ARGP_NO_ERRS flags in STATE, and will print
1727    to STATE->err_stream.  This is useful for argument parsing code that is
1728    shared between program startup (when exiting is desired) and runtime
1729    option parsing (when typically an error code is returned instead).  The
1730    difference between this function and argp_error is that the latter is for
1731    *parsing errors*, and the former is for other problems that occur during
1732    parsing but don't reflect a (syntactic) problem with the input.  */
1733 void
1734 __argp_failure (const struct argp_state *state, int status, int errnum,
1735                 const char *fmt, ...)
1736 {
1737   if (!state || !(state->flags & ARGP_NO_ERRS))
1738     {
1739       FILE *stream = state ? state->err_stream : stderr;
1740
1741       if (stream)
1742         {
1743           flockfile (stream);
1744
1745           fputs_unlocked (state ? state->name : program_invocation_short_name,
1746                           stream);
1747
1748           if (fmt)
1749             {
1750               va_list ap;
1751
1752               putc_unlocked (':', stream);
1753               putc_unlocked (' ', stream);
1754
1755               va_start (ap, fmt);
1756               vfprintf (stream, fmt, ap);
1757               va_end (ap);
1758             }
1759
1760           if (errnum)
1761             {
1762               putc_unlocked (':', stream);
1763               putc_unlocked (' ', stream);
1764               fputs (strerror (errnum), stream);
1765             }
1766
1767           putc_unlocked ('\n', stream);
1768
1769           funlockfile (stream);
1770
1771           if (status && (!state || !(state->flags & ARGP_NO_EXIT)))
1772             exit (status);
1773         }
1774     }
1775 }
1776 #ifdef weak_alias
1777 weak_alias (__argp_failure, argp_failure)
1778 #endif