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