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