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