Update.
[glibc.git] / argp / argp-help.c
blobd78060d12cefd26149a6aa967d0c7e3d1e94b76a
1 /* Hierarchial argument parsing help output
2 Copyright (C) 1995, 1996, 1997, 1998, 1999 Free Software Foundation, Inc.
3 This file is part of the GNU C Library.
4 Written by Miles Bader <miles@gnu.ai.mit.edu>.
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.
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.
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. */
21 #ifndef _GNU_SOURCE
22 # define _GNU_SOURCE 1
23 #endif
25 #ifdef HAVE_CONFIG_H
26 #include <config.h>
27 #endif
29 #ifndef alloca
30 # ifdef __GNUC__
31 # define alloca __builtin_alloca
32 # define HAVE_ALLOCA 1
33 # else
34 # if defined HAVE_ALLOCA_H || defined _LIBC
35 # include <alloca.h>
36 # else
37 # ifdef _AIX
38 #pragma alloca
39 # else
40 # ifndef alloca
41 char *alloca ();
42 # endif
43 # endif
44 # endif
45 # endif
46 #endif
48 #include <stddef.h>
49 #include <stdlib.h>
50 #include <string.h>
51 #include <assert.h>
52 #include <stdarg.h>
53 #include <malloc.h>
54 #include <ctype.h>
56 #ifndef _
57 /* This is for other GNU distributions with internationalized messages. */
58 # ifdef HAVE_LIBINTL_H
59 # include <libintl.h>
60 # else
61 # define dgettext(domain, msgid) (msgid)
62 # endif
63 #endif
65 #ifdef USE_IN_LIBIO
66 # define flockfile(s) _IO_flockfile (s)
67 # define funlockfile(s) _IO_funlockfile (s)
68 #endif
70 #include "argp.h"
71 #include "argp-fmtstream.h"
72 #include "argp-namefrob.h"
74 /* User-selectable (using an environment variable) formatting parameters.
76 These may be specified in an environment variable called `ARGP_HELP_FMT',
77 with a contents like: VAR1=VAL1,VAR2=VAL2,BOOLVAR2,no-BOOLVAR2
78 Where VALn must be a positive integer. The list of variables is in the
79 UPARAM_NAMES vector, below. */
81 /* Default parameters. */
82 #define DUP_ARGS 0 /* True if option argument can be duplicated. */
83 #define DUP_ARGS_NOTE 1 /* True to print a note about duplicate args. */
84 #define SHORT_OPT_COL 2 /* column in which short options start */
85 #define LONG_OPT_COL 6 /* column in which long options start */
86 #define DOC_OPT_COL 2 /* column in which doc options start */
87 #define OPT_DOC_COL 29 /* column in which option text starts */
88 #define HEADER_COL 1 /* column in which group headers are printed */
89 #define USAGE_INDENT 12 /* indentation of wrapped usage lines */
90 #define RMARGIN 79 /* right margin used for wrapping */
92 /* User-selectable (using an environment variable) formatting parameters.
93 They must all be of type `int' for the parsing code to work. */
94 struct uparams
96 /* If true, arguments for an option are shown with both short and long
97 options, even when a given option has both, e.g. `-x ARG, --longx=ARG'.
98 If false, then if an option has both, the argument is only shown with
99 the long one, e.g., `-x, --longx=ARG', and a message indicating that
100 this really means both is printed below the options. */
101 int dup_args;
103 /* This is true if when DUP_ARGS is false, and some duplicate arguments have
104 been suppressed, an explanatory message should be printed. */
105 int dup_args_note;
107 /* Various output columns. */
108 int short_opt_col;
109 int long_opt_col;
110 int doc_opt_col;
111 int opt_doc_col;
112 int header_col;
113 int usage_indent;
114 int rmargin;
116 int valid; /* True when the values in here are valid. */
119 /* This is a global variable, as user options are only ever read once. */
120 static struct uparams uparams = {
121 DUP_ARGS, DUP_ARGS_NOTE,
122 SHORT_OPT_COL, LONG_OPT_COL, DOC_OPT_COL, OPT_DOC_COL, HEADER_COL,
123 USAGE_INDENT, RMARGIN,
127 /* A particular uparam, and what the user name is. */
128 struct uparam_name
130 const char *name; /* User name. */
131 int is_bool; /* Whether it's `boolean'. */
132 size_t uparams_offs; /* Location of the (int) field in UPARAMS. */
135 /* The name-field mappings we know about. */
136 static const struct uparam_name uparam_names[] =
138 { "dup-args", 1, offsetof (struct uparams, dup_args) },
139 { "dup-args-note", 1, offsetof (struct uparams, dup_args_note) },
140 { "short-opt-col", 0, offsetof (struct uparams, short_opt_col) },
141 { "long-opt-col", 0, offsetof (struct uparams, long_opt_col) },
142 { "doc-opt-col", 0, offsetof (struct uparams, doc_opt_col) },
143 { "opt-doc-col", 0, offsetof (struct uparams, opt_doc_col) },
144 { "header-col", 0, offsetof (struct uparams, header_col) },
145 { "usage-indent", 0, offsetof (struct uparams, usage_indent) },
146 { "rmargin", 0, offsetof (struct uparams, rmargin) },
147 { 0 }
150 /* Read user options from the environment, and fill in UPARAMS appropiately. */
151 static void
152 fill_in_uparams (const struct argp_state *state)
154 const char *var = getenv ("ARGP_HELP_FMT");
156 #define SKIPWS(p) do { while (isspace (*p)) p++; } while (0);
158 if (var)
159 /* Parse var. */
160 while (*var)
162 SKIPWS (var);
164 if (isalpha (*var))
166 size_t var_len;
167 const struct uparam_name *un;
168 int unspec = 0, val = 0;
169 const char *arg = var;
171 while (isalnum (*arg) || *arg == '-' || *arg == '_')
172 arg++;
173 var_len = arg - var;
175 SKIPWS (arg);
177 if (*arg == '\0' || *arg == ',')
178 unspec = 1;
179 else if (*arg == '=')
181 arg++;
182 SKIPWS (arg);
185 if (unspec)
187 if (var[0] == 'n' && var[1] == 'o' && var[2] == '-')
189 val = 0;
190 var += 3;
191 var_len -= 3;
193 else
194 val = 1;
196 else if (isdigit (*arg))
198 val = atoi (arg);
199 while (isdigit (*arg))
200 arg++;
201 SKIPWS (arg);
204 for (un = uparam_names; un->name; un++)
205 if (strlen (un->name) == var_len
206 && strncmp (var, un->name, var_len) == 0)
208 if (unspec && !un->is_bool)
209 __argp_failure (state, 0, 0,
210 dgettext (state->root_argp->argp_domain, "\
211 %.*s: ARGP_HELP_FMT parameter requires a value"),
212 (int) var_len, var);
213 else
214 *(int *)((char *)&uparams + un->uparams_offs) = val;
215 break;
217 if (! un->name)
218 __argp_failure (state, 0, 0,
219 dgettext (state->root_argp->argp_domain, "\
220 %.*s: Unknown ARGP_HELP_FMT parameter"),
221 (int) var_len, var);
223 var = arg;
224 if (*var == ',')
225 var++;
227 else if (*var)
229 __argp_failure (state, 0, 0,
230 dgettext (state->root_argp->argp_domain,
231 "Garbage in ARGP_HELP_FMT: %s"), var);
232 break;
237 /* Returns true if OPT hasn't been marked invisible. Visibility only affects
238 whether OPT is displayed or used in sorting, not option shadowing. */
239 #define ovisible(opt) (! ((opt)->flags & OPTION_HIDDEN))
241 /* Returns true if OPT is an alias for an earlier option. */
242 #define oalias(opt) ((opt)->flags & OPTION_ALIAS)
244 /* Returns true if OPT is an documentation-only entry. */
245 #define odoc(opt) ((opt)->flags & OPTION_DOC)
247 /* Returns true if OPT is the end-of-list marker for a list of options. */
248 #define oend(opt) __option_is_end (opt)
250 /* Returns true if OPT has a short option. */
251 #define oshort(opt) __option_is_short (opt)
254 The help format for a particular option is like:
256 -xARG, -yARG, --long1=ARG, --long2=ARG Documentation...
258 Where ARG will be omitted if there's no argument, for this option, or
259 will be surrounded by "[" and "]" appropiately if the argument is
260 optional. The documentation string is word-wrapped appropiately, and if
261 the list of options is long enough, it will be started on a separate line.
262 If there are no short options for a given option, the first long option is
263 indented slighly in a way that's supposed to make most long options appear
264 to be in a separate column.
266 For example, the following output (from ps):
268 -p PID, --pid=PID List the process PID
269 --pgrp=PGRP List processes in the process group PGRP
270 -P, -x, --no-parent Include processes without parents
271 -Q, --all-fields Don't elide unusable fields (normally if there's
272 some reason ps can't print a field for any
273 process, it's removed from the output entirely)
274 -r, --reverse, --gratuitously-long-reverse-option
275 Reverse the order of any sort
276 --session[=SID] Add the processes from the session SID (which
277 defaults to the sid of the current process)
279 Here are some more options:
280 -f ZOT, --foonly=ZOT Glork a foonly
281 -z, --zaza Snit a zar
283 -?, --help Give this help list
284 --usage Give a short usage message
285 -V, --version Print program version
287 The struct argp_option array for the above could look like:
290 {"pid", 'p', "PID", 0, "List the process PID"},
291 {"pgrp", OPT_PGRP, "PGRP", 0, "List processes in the process group PGRP"},
292 {"no-parent", 'P', 0, 0, "Include processes without parents"},
293 {0, 'x', 0, OPTION_ALIAS},
294 {"all-fields",'Q', 0, 0, "Don't elide unusable fields (normally"
295 " if there's some reason ps can't"
296 " print a field for any process, it's"
297 " removed from the output entirely)" },
298 {"reverse", 'r', 0, 0, "Reverse the order of any sort"},
299 {"gratuitously-long-reverse-option", 0, 0, OPTION_ALIAS},
300 {"session", OPT_SESS, "SID", OPTION_ARG_OPTIONAL,
301 "Add the processes from the session"
302 " SID (which defaults to the sid of"
303 " the current process)" },
305 {0,0,0,0, "Here are some more options:"},
306 {"foonly", 'f', "ZOT", 0, "Glork a foonly"},
307 {"zaza", 'z', 0, 0, "Snit a zar"},
312 Note that the last three options are automatically supplied by argp_parse,
313 unless you tell it not to with ARGP_NO_HELP.
317 /* Returns true if CH occurs between BEG and END. */
318 static int
319 find_char (char ch, char *beg, char *end)
321 while (beg < end)
322 if (*beg == ch)
323 return 1;
324 else
325 beg++;
326 return 0;
329 struct hol_cluster; /* fwd decl */
331 struct hol_entry
333 /* First option. */
334 const struct argp_option *opt;
335 /* Number of options (including aliases). */
336 unsigned num;
338 /* A pointers into the HOL's short_options field, to the first short option
339 letter for this entry. The order of the characters following this point
340 corresponds to the order of options pointed to by OPT, and there are at
341 most NUM. A short option recorded in a option following OPT is only
342 valid if it occurs in the right place in SHORT_OPTIONS (otherwise it's
343 probably been shadowed by some other entry). */
344 char *short_options;
346 /* Entries are sorted by their group first, in the order:
347 1, 2, ..., n, 0, -m, ..., -2, -1
348 and then alphabetically within each group. The default is 0. */
349 int group;
351 /* The cluster of options this entry belongs to, or 0 if none. */
352 struct hol_cluster *cluster;
354 /* The argp from which this option came. */
355 const struct argp *argp;
358 /* A cluster of entries to reflect the argp tree structure. */
359 struct hol_cluster
361 /* A descriptive header printed before options in this cluster. */
362 const char *header;
364 /* Used to order clusters within the same group with the same parent,
365 according to the order in which they occured in the parent argp's child
366 list. */
367 int index;
369 /* How to sort this cluster with respect to options and other clusters at the
370 same depth (clusters always follow options in the same group). */
371 int group;
373 /* The cluster to which this cluster belongs, or 0 if it's at the base
374 level. */
375 struct hol_cluster *parent;
377 /* The argp from which this cluster is (eventually) derived. */
378 const struct argp *argp;
380 /* The distance this cluster is from the root. */
381 int depth;
383 /* Clusters in a given hol are kept in a linked list, to make freeing them
384 possible. */
385 struct hol_cluster *next;
388 /* A list of options for help. */
389 struct hol
391 /* An array of hol_entry's. */
392 struct hol_entry *entries;
393 /* The number of entries in this hol. If this field is zero, the others
394 are undefined. */
395 unsigned num_entries;
397 /* A string containing all short options in this HOL. Each entry contains
398 pointers into this string, so the order can't be messed with blindly. */
399 char *short_options;
401 /* Clusters of entries in this hol. */
402 struct hol_cluster *clusters;
405 /* Create a struct hol from the options in ARGP. CLUSTER is the
406 hol_cluster in which these entries occur, or 0, if at the root. */
407 static struct hol *
408 make_hol (const struct argp *argp, struct hol_cluster *cluster)
410 char *so;
411 const struct argp_option *o;
412 const struct argp_option *opts = argp->options;
413 struct hol_entry *entry;
414 unsigned num_short_options = 0;
415 struct hol *hol = malloc (sizeof (struct hol));
417 assert (hol);
419 hol->num_entries = 0;
420 hol->clusters = 0;
422 if (opts)
424 int cur_group = 0;
426 /* The first option must not be an alias. */
427 assert (! oalias (opts));
429 /* Calculate the space needed. */
430 for (o = opts; ! oend (o); o++)
432 if (! oalias (o))
433 hol->num_entries++;
434 if (oshort (o))
435 num_short_options++; /* This is an upper bound. */
438 hol->entries = malloc (sizeof (struct hol_entry) * hol->num_entries);
439 hol->short_options = malloc (num_short_options + 1);
441 assert (hol->entries && hol->short_options);
443 /* Fill in the entries. */
444 so = hol->short_options;
445 for (o = opts, entry = hol->entries; ! oend (o); entry++)
447 entry->opt = o;
448 entry->num = 0;
449 entry->short_options = so;
450 entry->group = cur_group =
451 o->group
452 ? o->group
453 : ((!o->name && !o->key)
454 ? cur_group + 1
455 : cur_group);
456 entry->cluster = cluster;
457 entry->argp = argp;
461 entry->num++;
462 if (oshort (o) && ! find_char (o->key, hol->short_options, so))
463 /* O has a valid short option which hasn't already been used.*/
464 *so++ = o->key;
465 o++;
467 while (! oend (o) && oalias (o));
469 *so = '\0'; /* null terminated so we can find the length */
472 return hol;
475 /* Add a new cluster to HOL, with the given GROUP and HEADER (taken from the
476 associated argp child list entry), INDEX, and PARENT, and return a pointer
477 to it. ARGP is the argp that this cluster results from. */
478 static struct hol_cluster *
479 hol_add_cluster (struct hol *hol, int group, const char *header, int index,
480 struct hol_cluster *parent, const struct argp *argp)
482 struct hol_cluster *cl = malloc (sizeof (struct hol_cluster));
483 if (cl)
485 cl->group = group;
486 cl->header = header;
488 cl->index = index;
489 cl->parent = parent;
490 cl->argp = argp;
491 cl->depth = parent ? parent->depth + 1 : 0;
493 cl->next = hol->clusters;
494 hol->clusters = cl;
496 return cl;
499 /* Free HOL and any resources it uses. */
500 static void
501 hol_free (struct hol *hol)
503 struct hol_cluster *cl = hol->clusters;
505 while (cl)
507 struct hol_cluster *next = cl->next;
508 free (cl);
509 cl = next;
512 if (hol->num_entries > 0)
514 free (hol->entries);
515 free (hol->short_options);
518 free (hol);
521 static inline int
522 hol_entry_short_iterate (const struct hol_entry *entry,
523 int (*func)(const struct argp_option *opt,
524 const struct argp_option *real,
525 const char *domain, void *cookie),
526 const char *domain, void *cookie)
528 unsigned nopts;
529 int val = 0;
530 const struct argp_option *opt, *real = entry->opt;
531 char *so = entry->short_options;
533 for (opt = real, nopts = entry->num; nopts > 0 && !val; opt++, nopts--)
534 if (oshort (opt) && *so == opt->key)
536 if (!oalias (opt))
537 real = opt;
538 if (ovisible (opt))
539 val = (*func)(opt, real, domain, cookie);
540 so++;
543 return val;
546 static inline int
547 hol_entry_long_iterate (const struct hol_entry *entry,
548 int (*func)(const struct argp_option *opt,
549 const struct argp_option *real,
550 const char *domain, void *cookie),
551 const char *domain, void *cookie)
553 unsigned nopts;
554 int val = 0;
555 const struct argp_option *opt, *real = entry->opt;
557 for (opt = real, nopts = entry->num; nopts > 0 && !val; opt++, nopts--)
558 if (opt->name)
560 if (!oalias (opt))
561 real = opt;
562 if (ovisible (opt))
563 val = (*func)(opt, real, domain, cookie);
566 return val;
569 /* Iterator that returns true for the first short option. */
570 static inline int
571 until_short (const struct argp_option *opt, const struct argp_option *real,
572 const char *domain, void *cookie)
574 return oshort (opt) ? opt->key : 0;
577 /* Returns the first valid short option in ENTRY, or 0 if there is none. */
578 static char
579 hol_entry_first_short (const struct hol_entry *entry)
581 return hol_entry_short_iterate (entry, until_short,
582 entry->argp->argp_domain, 0);
585 /* Returns the first valid long option in ENTRY, or 0 if there is none. */
586 static const char *
587 hol_entry_first_long (const struct hol_entry *entry)
589 const struct argp_option *opt;
590 unsigned num;
591 for (opt = entry->opt, num = entry->num; num > 0; opt++, num--)
592 if (opt->name && ovisible (opt))
593 return opt->name;
594 return 0;
597 /* Returns the entry in HOL with the long option name NAME, or 0 if there is
598 none. */
599 static struct hol_entry *
600 hol_find_entry (struct hol *hol, const char *name)
602 struct hol_entry *entry = hol->entries;
603 unsigned num_entries = hol->num_entries;
605 while (num_entries-- > 0)
607 const struct argp_option *opt = entry->opt;
608 unsigned num_opts = entry->num;
610 while (num_opts-- > 0)
611 if (opt->name && ovisible (opt) && strcmp (opt->name, name) == 0)
612 return entry;
613 else
614 opt++;
616 entry++;
619 return 0;
622 /* If an entry with the long option NAME occurs in HOL, set it's special
623 sort position to GROUP. */
624 static void
625 hol_set_group (struct hol *hol, const char *name, int group)
627 struct hol_entry *entry = hol_find_entry (hol, name);
628 if (entry)
629 entry->group = group;
632 /* Order by group: 0, 1, 2, ..., n, -m, ..., -2, -1.
633 EQ is what to return if GROUP1 and GROUP2 are the same. */
634 static int
635 group_cmp (int group1, int group2, int eq)
637 if (group1 == group2)
638 return eq;
639 else if ((group1 < 0 && group2 < 0) || (group1 >= 0 && group2 >= 0))
640 return group1 - group2;
641 else
642 return group2 - group1;
645 /* Compare clusters CL1 & CL2 by the order that they should appear in
646 output. */
647 static int
648 hol_cluster_cmp (const struct hol_cluster *cl1, const struct hol_cluster *cl2)
650 /* If one cluster is deeper than the other, use its ancestor at the same
651 level, so that finding the common ancestor is straightforward. */
652 while (cl1->depth < cl2->depth)
653 cl1 = cl1->parent;
654 while (cl2->depth < cl1->depth)
655 cl2 = cl2->parent;
657 /* Now reduce both clusters to their ancestors at the point where both have
658 a common parent; these can be directly compared. */
659 while (cl1->parent != cl2->parent)
660 cl1 = cl1->parent, cl2 = cl2->parent;
662 return group_cmp (cl1->group, cl2->group, cl2->index - cl1->index);
665 /* Return the ancestor of CL that's just below the root (i.e., has a parent
666 of 0). */
667 static struct hol_cluster *
668 hol_cluster_base (struct hol_cluster *cl)
670 while (cl->parent)
671 cl = cl->parent;
672 return cl;
675 /* Return true if CL1 is a child of CL2. */
676 static int
677 hol_cluster_is_child (const struct hol_cluster *cl1,
678 const struct hol_cluster *cl2)
680 while (cl1 && cl1 != cl2)
681 cl1 = cl1->parent;
682 return cl1 == cl2;
685 /* Given the name of a OPTION_DOC option, modifies NAME to start at the tail
686 that should be used for comparisons, and returns true iff it should be
687 treated as a non-option. */
688 static int
689 canon_doc_option (const char **name)
691 int non_opt;
692 /* Skip initial whitespace. */
693 while (isspace (**name))
694 (*name)++;
695 /* Decide whether this looks like an option (leading `-') or not. */
696 non_opt = (**name != '-');
697 /* Skip until part of name used for sorting. */
698 while (**name && !isalnum (**name))
699 (*name)++;
700 return non_opt;
703 /* Order ENTRY1 & ENTRY2 by the order which they should appear in a help
704 listing. */
705 static int
706 hol_entry_cmp (const struct hol_entry *entry1,
707 const struct hol_entry *entry2)
709 /* The group numbers by which the entries should be ordered; if either is
710 in a cluster, then this is just the group within the cluster. */
711 int group1 = entry1->group, group2 = entry2->group;
713 if (entry1->cluster != entry2->cluster)
715 /* The entries are not within the same cluster, so we can't compare them
716 directly, we have to use the appropiate clustering level too. */
717 if (! entry1->cluster)
718 /* ENTRY1 is at the `base level', not in a cluster, so we have to
719 compare it's group number with that of the base cluster in which
720 ENTRY2 resides. Note that if they're in the same group, the
721 clustered option always comes laster. */
722 return group_cmp (group1, hol_cluster_base (entry2->cluster)->group, -1);
723 else if (! entry2->cluster)
724 /* Likewise, but ENTRY2's not in a cluster. */
725 return group_cmp (hol_cluster_base (entry1->cluster)->group, group2, 1);
726 else
727 /* Both entries are in clusters, we can just compare the clusters. */
728 return hol_cluster_cmp (entry1->cluster, entry2->cluster);
730 else if (group1 == group2)
731 /* The entries are both in the same cluster and group, so compare them
732 alphabetically. */
734 int short1 = hol_entry_first_short (entry1);
735 int short2 = hol_entry_first_short (entry2);
736 int doc1 = odoc (entry1->opt);
737 int doc2 = odoc (entry2->opt);
738 const char *long1 = hol_entry_first_long (entry1);
739 const char *long2 = hol_entry_first_long (entry2);
741 if (doc1)
742 doc1 = canon_doc_option (&long1);
743 if (doc2)
744 doc2 = canon_doc_option (&long2);
746 if (doc1 != doc2)
747 /* `documentation' options always follow normal options (or
748 documentation options that *look* like normal options). */
749 return doc1 - doc2;
750 else if (!short1 && !short2 && long1 && long2)
751 /* Only long options. */
752 return __strcasecmp (long1, long2);
753 else
754 /* Compare short/short, long/short, short/long, using the first
755 character of long options. Entries without *any* valid
756 options (such as options with OPTION_HIDDEN set) will be put
757 first, but as they're not displayed, it doesn't matter where
758 they are. */
760 char first1 = short1 ? short1 : long1 ? *long1 : 0;
761 char first2 = short2 ? short2 : long2 ? *long2 : 0;
762 #ifdef _tolower
763 int lower_cmp = _tolower (first1) - _tolower (first2);
764 #else
765 int lower_cmp = tolower (first1) - tolower (first2);
766 #endif
767 /* Compare ignoring case, except when the options are both the
768 same letter, in which case lower-case always comes first. */
769 return lower_cmp ? lower_cmp : first2 - first1;
772 else
773 /* Within the same cluster, but not the same group, so just compare
774 groups. */
775 return group_cmp (group1, group2, 0);
778 /* Version of hol_entry_cmp with correct signature for qsort. */
779 static int
780 hol_entry_qcmp (const void *entry1_v, const void *entry2_v)
782 return hol_entry_cmp (entry1_v, entry2_v);
785 /* Sort HOL by group and alphabetically by option name (with short options
786 taking precedence over long). Since the sorting is for display purposes
787 only, the shadowing of options isn't effected. */
788 static void
789 hol_sort (struct hol *hol)
791 if (hol->num_entries > 0)
792 qsort (hol->entries, hol->num_entries, sizeof (struct hol_entry),
793 hol_entry_qcmp);
796 /* Append MORE to HOL, destroying MORE in the process. Options in HOL shadow
797 any in MORE with the same name. */
798 static void
799 hol_append (struct hol *hol, struct hol *more)
801 struct hol_cluster **cl_end = &hol->clusters;
803 /* Steal MORE's cluster list, and add it to the end of HOL's. */
804 while (*cl_end)
805 cl_end = &(*cl_end)->next;
806 *cl_end = more->clusters;
807 more->clusters = 0;
809 /* Merge entries. */
810 if (more->num_entries > 0)
812 if (hol->num_entries == 0)
814 hol->num_entries = more->num_entries;
815 hol->entries = more->entries;
816 hol->short_options = more->short_options;
817 more->num_entries = 0; /* Mark MORE's fields as invalid. */
819 else
820 /* Append the entries in MORE to those in HOL, taking care to only add
821 non-shadowed SHORT_OPTIONS values. */
823 unsigned left;
824 char *so, *more_so;
825 struct hol_entry *e;
826 unsigned num_entries = hol->num_entries + more->num_entries;
827 struct hol_entry *entries =
828 malloc (num_entries * sizeof (struct hol_entry));
829 unsigned hol_so_len = strlen (hol->short_options);
830 char *short_options =
831 malloc (hol_so_len + strlen (more->short_options) + 1);
833 __mempcpy (__mempcpy (entries, hol->entries,
834 hol->num_entries * sizeof (struct hol_entry)),
835 more->entries,
836 more->num_entries * sizeof (struct hol_entry));
838 __mempcpy (short_options, hol->short_options, hol_so_len);
840 /* Fix up the short options pointers from HOL. */
841 for (e = entries, left = hol->num_entries; left > 0; e++, left--)
842 e->short_options += (short_options - hol->short_options);
844 /* Now add the short options from MORE, fixing up its entries
845 too. */
846 so = short_options + hol_so_len;
847 more_so = more->short_options;
848 for (left = more->num_entries; left > 0; e++, left--)
850 int opts_left;
851 const struct argp_option *opt;
853 e->short_options = so;
855 for (opts_left = e->num, opt = e->opt; opts_left; opt++, opts_left--)
857 int ch = *more_so;
858 if (oshort (opt) && ch == opt->key)
859 /* The next short option in MORE_SO, CH, is from OPT. */
861 if (! find_char (ch, short_options,
862 short_options + hol_so_len))
863 /* The short option CH isn't shadowed by HOL's options,
864 so add it to the sum. */
865 *so++ = ch;
866 more_so++;
871 *so = '\0';
873 free (hol->entries);
874 free (hol->short_options);
876 hol->entries = entries;
877 hol->num_entries = num_entries;
878 hol->short_options = short_options;
882 hol_free (more);
885 /* Inserts enough spaces to make sure STREAM is at column COL. */
886 static void
887 indent_to (argp_fmtstream_t stream, unsigned col)
889 int needed = col - __argp_fmtstream_point (stream);
890 while (needed-- > 0)
891 __argp_fmtstream_putc (stream, ' ');
894 /* Output to STREAM either a space, or a newline if there isn't room for at
895 least ENSURE characters before the right margin. */
896 static void
897 space (argp_fmtstream_t stream, size_t ensure)
899 if (__argp_fmtstream_point (stream) + ensure
900 >= __argp_fmtstream_rmargin (stream))
901 __argp_fmtstream_putc (stream, '\n');
902 else
903 __argp_fmtstream_putc (stream, ' ');
906 /* If the option REAL has an argument, we print it in using the printf
907 format REQ_FMT or OPT_FMT depending on whether it's a required or
908 optional argument. */
909 static void
910 arg (const struct argp_option *real, const char *req_fmt, const char *opt_fmt,
911 const char *domain, argp_fmtstream_t stream)
913 if (real->arg)
915 if (real->flags & OPTION_ARG_OPTIONAL)
916 __argp_fmtstream_printf (stream, opt_fmt,
917 dgettext (domain, real->arg));
918 else
919 __argp_fmtstream_printf (stream, req_fmt,
920 dgettext (domain, real->arg));
924 /* Helper functions for hol_entry_help. */
926 /* State used during the execution of hol_help. */
927 struct hol_help_state
929 /* PREV_ENTRY should contain the previous entry printed, or 0. */
930 struct hol_entry *prev_entry;
932 /* If an entry is in a different group from the previous one, and SEP_GROUPS
933 is true, then a blank line will be printed before any output. */
934 int sep_groups;
936 /* True if a duplicate option argument was suppressed (only ever set if
937 UPARAMS.dup_args is false). */
938 int suppressed_dup_arg;
941 /* Some state used while printing a help entry (used to communicate with
942 helper functions). See the doc for hol_entry_help for more info, as most
943 of the fields are copied from its arguments. */
944 struct pentry_state
946 const struct hol_entry *entry;
947 argp_fmtstream_t stream;
948 struct hol_help_state *hhstate;
950 /* True if nothing's been printed so far. */
951 int first;
953 /* If non-zero, the state that was used to print this help. */
954 const struct argp_state *state;
957 /* If a user doc filter should be applied to DOC, do so. */
958 static const char *
959 filter_doc (const char *doc, int key, const struct argp *argp,
960 const struct argp_state *state)
962 if (argp->help_filter)
963 /* We must apply a user filter to this output. */
965 void *input = __argp_input (argp, state);
966 return (*argp->help_filter) (key, doc, input);
968 else
969 /* No filter. */
970 return doc;
973 /* Prints STR as a header line, with the margin lines set appropiately, and
974 notes the fact that groups should be separated with a blank line. ARGP is
975 the argp that should dictate any user doc filtering to take place. Note
976 that the previous wrap margin isn't restored, but the left margin is reset
977 to 0. */
978 static void
979 print_header (const char *str, const struct argp *argp,
980 struct pentry_state *pest)
982 const char *tstr = dgettext (argp->argp_domain, str);
983 const char *fstr = filter_doc (tstr, ARGP_KEY_HELP_HEADER, argp, pest->state);
985 if (fstr)
987 if (*fstr)
989 if (pest->hhstate->prev_entry)
990 /* Precede with a blank line. */
991 __argp_fmtstream_putc (pest->stream, '\n');
992 indent_to (pest->stream, uparams.header_col);
993 __argp_fmtstream_set_lmargin (pest->stream, uparams.header_col);
994 __argp_fmtstream_set_wmargin (pest->stream, uparams.header_col);
995 __argp_fmtstream_puts (pest->stream, fstr);
996 __argp_fmtstream_set_lmargin (pest->stream, 0);
997 __argp_fmtstream_putc (pest->stream, '\n');
1000 pest->hhstate->sep_groups = 1; /* Separate subsequent groups. */
1003 if (fstr != tstr)
1004 free ((char *) fstr);
1007 /* Inserts a comma if this isn't the first item on the line, and then makes
1008 sure we're at least to column COL. If this *is* the first item on a line,
1009 prints any pending whitespace/headers that should precede this line. Also
1010 clears FIRST. */
1011 static void
1012 comma (unsigned col, struct pentry_state *pest)
1014 if (pest->first)
1016 const struct hol_entry *pe = pest->hhstate->prev_entry;
1017 const struct hol_cluster *cl = pest->entry->cluster;
1019 if (pest->hhstate->sep_groups && pe && pest->entry->group != pe->group)
1020 __argp_fmtstream_putc (pest->stream, '\n');
1022 if (cl && cl->header && *cl->header
1023 && (!pe
1024 || (pe->cluster != cl
1025 && !hol_cluster_is_child (pe->cluster, cl))))
1026 /* If we're changing clusters, then this must be the start of the
1027 ENTRY's cluster unless that is an ancestor of the previous one
1028 (in which case we had just popped into a sub-cluster for a bit).
1029 If so, then print the cluster's header line. */
1031 int old_wm = __argp_fmtstream_wmargin (pest->stream);
1032 print_header (cl->header, cl->argp, pest);
1033 __argp_fmtstream_set_wmargin (pest->stream, old_wm);
1036 pest->first = 0;
1038 else
1039 __argp_fmtstream_puts (pest->stream, ", ");
1041 indent_to (pest->stream, col);
1044 /* Print help for ENTRY to STREAM. */
1045 static void
1046 hol_entry_help (struct hol_entry *entry, const struct argp_state *state,
1047 argp_fmtstream_t stream, struct hol_help_state *hhstate)
1049 unsigned num;
1050 const struct argp_option *real = entry->opt, *opt;
1051 char *so = entry->short_options;
1052 int have_long_opt = 0; /* We have any long options. */
1053 /* Saved margins. */
1054 int old_lm = __argp_fmtstream_set_lmargin (stream, 0);
1055 int old_wm = __argp_fmtstream_wmargin (stream);
1056 /* PEST is a state block holding some of our variables that we'd like to
1057 share with helper functions. */
1058 struct pentry_state pest = { entry, stream, hhstate, 1, state };
1060 if (! odoc (real))
1061 for (opt = real, num = entry->num; num > 0; opt++, num--)
1062 if (opt->name && ovisible (opt))
1064 have_long_opt = 1;
1065 break;
1068 /* First emit short options. */
1069 __argp_fmtstream_set_wmargin (stream, uparams.short_opt_col); /* For truly bizarre cases. */
1070 for (opt = real, num = entry->num; num > 0; opt++, num--)
1071 if (oshort (opt) && opt->key == *so)
1072 /* OPT has a valid (non shadowed) short option. */
1074 if (ovisible (opt))
1076 comma (uparams.short_opt_col, &pest);
1077 __argp_fmtstream_putc (stream, '-');
1078 __argp_fmtstream_putc (stream, *so);
1079 if (!have_long_opt || uparams.dup_args)
1080 arg (real, " %s", "[%s]", state->root_argp->argp_domain, stream);
1081 else if (real->arg)
1082 hhstate->suppressed_dup_arg = 1;
1084 so++;
1087 /* Now, long options. */
1088 if (odoc (real))
1089 /* A `documentation' option. */
1091 __argp_fmtstream_set_wmargin (stream, uparams.doc_opt_col);
1092 for (opt = real, num = entry->num; num > 0; opt++, num--)
1093 if (opt->name && ovisible (opt))
1095 comma (uparams.doc_opt_col, &pest);
1096 /* Calling gettext here isn't quite right, since sorting will
1097 have been done on the original; but documentation options
1098 should be pretty rare anyway... */
1099 __argp_fmtstream_puts (stream,
1100 dgettext (state->root_argp->argp_domain,
1101 opt->name));
1104 else
1105 /* A real long option. */
1107 int first_long_opt = 1;
1109 __argp_fmtstream_set_wmargin (stream, uparams.long_opt_col);
1110 for (opt = real, num = entry->num; num > 0; opt++, num--)
1111 if (opt->name && ovisible (opt))
1113 comma (uparams.long_opt_col, &pest);
1114 __argp_fmtstream_printf (stream, "--%s", opt->name);
1115 if (first_long_opt || uparams.dup_args)
1116 arg (real, "=%s", "[=%s]", state->root_argp->argp_domain,
1117 stream);
1118 else if (real->arg)
1119 hhstate->suppressed_dup_arg = 1;
1123 /* Next, documentation strings. */
1124 __argp_fmtstream_set_lmargin (stream, 0);
1126 if (pest.first)
1128 /* Didn't print any switches, what's up? */
1129 if (!oshort (real) && !real->name)
1130 /* This is a group header, print it nicely. */
1131 print_header (real->doc, entry->argp, &pest);
1132 else
1133 /* Just a totally shadowed option or null header; print nothing. */
1134 goto cleanup; /* Just return, after cleaning up. */
1136 else
1138 const char *tstr = real->doc ? dgettext (state->root_argp->argp_domain,
1139 real->doc) : 0;
1140 const char *fstr = filter_doc (tstr, real->key, entry->argp, state);
1141 if (fstr && *fstr)
1143 unsigned int col = __argp_fmtstream_point (stream);
1145 __argp_fmtstream_set_lmargin (stream, uparams.opt_doc_col);
1146 __argp_fmtstream_set_wmargin (stream, uparams.opt_doc_col);
1148 if (col > (unsigned int) (uparams.opt_doc_col + 3))
1149 __argp_fmtstream_putc (stream, '\n');
1150 else if (col >= (unsigned int) uparams.opt_doc_col)
1151 __argp_fmtstream_puts (stream, " ");
1152 else
1153 indent_to (stream, uparams.opt_doc_col);
1155 __argp_fmtstream_puts (stream, fstr);
1157 if (fstr && fstr != tstr)
1158 free ((char *) fstr);
1160 /* Reset the left margin. */
1161 __argp_fmtstream_set_lmargin (stream, 0);
1162 __argp_fmtstream_putc (stream, '\n');
1165 hhstate->prev_entry = entry;
1167 cleanup:
1168 __argp_fmtstream_set_lmargin (stream, old_lm);
1169 __argp_fmtstream_set_wmargin (stream, old_wm);
1172 /* Output a long help message about the options in HOL to STREAM. */
1173 static void
1174 hol_help (struct hol *hol, const struct argp_state *state,
1175 argp_fmtstream_t stream)
1177 unsigned num;
1178 struct hol_entry *entry;
1179 struct hol_help_state hhstate = { 0, 0, 0 };
1181 for (entry = hol->entries, num = hol->num_entries; num > 0; entry++, num--)
1182 hol_entry_help (entry, state, stream, &hhstate);
1184 if (hhstate.suppressed_dup_arg && uparams.dup_args_note)
1186 const char *tstr = dgettext (state->root_argp->argp_domain, "\
1187 Mandatory or optional arguments to long options are also mandatory or \
1188 optional for any corresponding short options.");
1189 const char *fstr = filter_doc (tstr, ARGP_KEY_HELP_DUP_ARGS_NOTE,
1190 state ? state->root_argp : 0, state);
1191 if (fstr && *fstr)
1193 __argp_fmtstream_putc (stream, '\n');
1194 __argp_fmtstream_puts (stream, fstr);
1195 __argp_fmtstream_putc (stream, '\n');
1197 if (fstr && fstr != tstr)
1198 free ((char *) fstr);
1202 /* Helper functions for hol_usage. */
1204 /* If OPT is a short option without an arg, append its key to the string
1205 pointer pointer to by COOKIE, and advance the pointer. */
1206 static int
1207 add_argless_short_opt (const struct argp_option *opt,
1208 const struct argp_option *real,
1209 const char *domain, void *cookie)
1211 char **snao_end = cookie;
1212 if (!(opt->arg || real->arg)
1213 && !((opt->flags | real->flags) & OPTION_NO_USAGE))
1214 *(*snao_end)++ = opt->key;
1215 return 0;
1218 /* If OPT is a short option with an arg, output a usage entry for it to the
1219 stream pointed at by COOKIE. */
1220 static int
1221 usage_argful_short_opt (const struct argp_option *opt,
1222 const struct argp_option *real,
1223 const char *domain, void *cookie)
1225 argp_fmtstream_t stream = cookie;
1226 const char *arg = opt->arg;
1227 int flags = opt->flags | real->flags;
1229 if (! arg)
1230 arg = real->arg;
1232 if (arg && !(flags & OPTION_NO_USAGE))
1234 arg = dgettext (domain, arg);
1236 if (flags & OPTION_ARG_OPTIONAL)
1237 __argp_fmtstream_printf (stream, " [-%c[%s]]", opt->key, arg);
1238 else
1240 /* Manually do line wrapping so that it (probably) won't
1241 get wrapped at the embedded space. */
1242 space (stream, 6 + strlen (arg));
1243 __argp_fmtstream_printf (stream, "[-%c %s]", opt->key, arg);
1247 return 0;
1250 /* Output a usage entry for the long option opt to the stream pointed at by
1251 COOKIE. */
1252 static int
1253 usage_long_opt (const struct argp_option *opt,
1254 const struct argp_option *real,
1255 const char *domain, void *cookie)
1257 argp_fmtstream_t stream = cookie;
1258 const char *arg = opt->arg;
1259 int flags = opt->flags | real->flags;
1261 if (! arg)
1262 arg = real->arg;
1264 if (! (flags & OPTION_NO_USAGE))
1266 if (arg)
1268 arg = dgettext (domain, arg);
1269 if (flags & OPTION_ARG_OPTIONAL)
1270 __argp_fmtstream_printf (stream, " [--%s[=%s]]", opt->name, arg);
1271 else
1272 __argp_fmtstream_printf (stream, " [--%s=%s]", opt->name, arg);
1274 else
1275 __argp_fmtstream_printf (stream, " [--%s]", opt->name);
1278 return 0;
1281 /* Print a short usage description for the arguments in HOL to STREAM. */
1282 static void
1283 hol_usage (struct hol *hol, argp_fmtstream_t stream)
1285 if (hol->num_entries > 0)
1287 unsigned nentries;
1288 struct hol_entry *entry;
1289 char *short_no_arg_opts = alloca (strlen (hol->short_options) + 1);
1290 char *snao_end = short_no_arg_opts;
1292 /* First we put a list of short options without arguments. */
1293 for (entry = hol->entries, nentries = hol->num_entries
1294 ; nentries > 0
1295 ; entry++, nentries--)
1296 hol_entry_short_iterate (entry, add_argless_short_opt,
1297 entry->argp->argp_domain, &snao_end);
1298 if (snao_end > short_no_arg_opts)
1300 *snao_end++ = 0;
1301 __argp_fmtstream_printf (stream, " [-%s]", short_no_arg_opts);
1304 /* Now a list of short options *with* arguments. */
1305 for (entry = hol->entries, nentries = hol->num_entries
1306 ; nentries > 0
1307 ; entry++, nentries--)
1308 hol_entry_short_iterate (entry, usage_argful_short_opt,
1309 entry->argp->argp_domain, stream);
1311 /* Finally, a list of long options (whew!). */
1312 for (entry = hol->entries, nentries = hol->num_entries
1313 ; nentries > 0
1314 ; entry++, nentries--)
1315 hol_entry_long_iterate (entry, usage_long_opt,
1316 entry->argp->argp_domain, stream);
1320 /* Make a HOL containing all levels of options in ARGP. CLUSTER is the
1321 cluster in which ARGP's entries should be clustered, or 0. */
1322 static struct hol *
1323 argp_hol (const struct argp *argp, struct hol_cluster *cluster)
1325 const struct argp_child *child = argp->children;
1326 struct hol *hol = make_hol (argp, cluster);
1327 if (child)
1328 while (child->argp)
1330 struct hol_cluster *child_cluster =
1331 ((child->group || child->header)
1332 /* Put CHILD->argp within its own cluster. */
1333 ? hol_add_cluster (hol, child->group, child->header,
1334 child - argp->children, cluster, argp)
1335 /* Just merge it into the parent's cluster. */
1336 : cluster);
1337 hol_append (hol, argp_hol (child->argp, child_cluster)) ;
1338 child++;
1340 return hol;
1343 /* Calculate how many different levels with alternative args strings exist in
1344 ARGP. */
1345 static size_t
1346 argp_args_levels (const struct argp *argp)
1348 size_t levels = 0;
1349 const struct argp_child *child = argp->children;
1351 if (argp->args_doc && strchr (argp->args_doc, '\n'))
1352 levels++;
1354 if (child)
1355 while (child->argp)
1356 levels += argp_args_levels ((child++)->argp);
1358 return levels;
1361 /* Print all the non-option args documented in ARGP to STREAM. Any output is
1362 preceded by a space. LEVELS is a pointer to a byte vector the length
1363 returned by argp_args_levels; it should be initialized to zero, and
1364 updated by this routine for the next call if ADVANCE is true. True is
1365 returned as long as there are more patterns to output. */
1366 static int
1367 argp_args_usage (const struct argp *argp, const struct argp_state *state,
1368 char **levels, int advance, argp_fmtstream_t stream)
1370 char *our_level = *levels;
1371 int multiple = 0;
1372 const struct argp_child *child = argp->children;
1373 const char *tdoc = dgettext (argp->argp_domain, argp->args_doc), *nl = 0;
1374 const char *fdoc = filter_doc (tdoc, ARGP_KEY_HELP_ARGS_DOC, argp, state);
1376 if (fdoc)
1378 const char *cp = fdoc;
1379 nl = strchr (cp, '\n');
1380 if (nl)
1381 /* This is a `multi-level' args doc; advance to the correct position
1382 as determined by our state in LEVELS, and update LEVELS. */
1384 int i;
1385 multiple = 1;
1386 for (i = 0; i < *our_level; i++)
1387 cp = nl + 1, nl = strchr (cp, '\n');
1388 (*levels)++;
1390 if (! nl)
1391 nl = cp + strlen (cp);
1393 /* Manually do line wrapping so that it (probably) won't get wrapped at
1394 any embedded spaces. */
1395 space (stream, 1 + nl - cp);
1397 __argp_fmtstream_write (stream, cp, nl - cp);
1399 if (fdoc && fdoc != tdoc)
1400 free ((char *)fdoc); /* Free user's modified doc string. */
1402 if (child)
1403 while (child->argp)
1404 advance = !argp_args_usage ((child++)->argp, state, levels, advance, stream);
1406 if (advance && multiple)
1408 /* Need to increment our level. */
1409 if (*nl)
1410 /* There's more we can do here. */
1412 (*our_level)++;
1413 advance = 0; /* Our parent shouldn't advance also. */
1415 else if (*our_level > 0)
1416 /* We had multiple levels, but used them up; reset to zero. */
1417 *our_level = 0;
1420 return !advance;
1423 /* Print the documentation for ARGP to STREAM; if POST is false, then
1424 everything preceeding a `\v' character in the documentation strings (or
1425 the whole string, for those with none) is printed, otherwise, everything
1426 following the `\v' character (nothing for strings without). Each separate
1427 bit of documentation is separated a blank line, and if PRE_BLANK is true,
1428 then the first is as well. If FIRST_ONLY is true, only the first
1429 occurance is output. Returns true if anything was output. */
1430 static int
1431 argp_doc (const struct argp *argp, const struct argp_state *state,
1432 int post, int pre_blank, int first_only,
1433 argp_fmtstream_t stream)
1435 const char *text;
1436 const char *inp_text;
1437 void *input = 0;
1438 int anything = 0;
1439 size_t inp_text_limit = 0;
1440 const char *doc = dgettext (argp->argp_domain, argp->doc);
1441 const struct argp_child *child = argp->children;
1443 if (doc)
1445 char *vt = strchr (doc, '\v');
1446 inp_text = post ? (vt ? vt + 1 : 0) : doc;
1447 inp_text_limit = (!post && vt) ? (vt - doc) : 0;
1449 else
1450 inp_text = 0;
1452 if (argp->help_filter)
1453 /* We have to filter the doc strings. */
1455 if (inp_text_limit)
1456 /* Copy INP_TEXT so that it's nul-terminated. */
1457 inp_text = __strndup (inp_text, inp_text_limit);
1458 input = __argp_input (argp, state);
1459 text =
1460 (*argp->help_filter) (post
1461 ? ARGP_KEY_HELP_POST_DOC
1462 : ARGP_KEY_HELP_PRE_DOC,
1463 inp_text, input);
1465 else
1466 text = (const char *) inp_text;
1468 if (text)
1470 if (pre_blank)
1471 __argp_fmtstream_putc (stream, '\n');
1473 if (text == inp_text && inp_text_limit)
1474 __argp_fmtstream_write (stream, inp_text, inp_text_limit);
1475 else
1476 __argp_fmtstream_puts (stream, text);
1478 if (__argp_fmtstream_point (stream) > __argp_fmtstream_lmargin (stream))
1479 __argp_fmtstream_putc (stream, '\n');
1481 anything = 1;
1484 if (text && text != inp_text)
1485 free ((char *) text); /* Free TEXT returned from the help filter. */
1486 if (inp_text && inp_text_limit && argp->help_filter)
1487 free ((char *) inp_text); /* We copied INP_TEXT, so free it now. */
1489 if (post && argp->help_filter)
1490 /* Now see if we have to output a ARGP_KEY_HELP_EXTRA text. */
1492 text = (*argp->help_filter) (ARGP_KEY_HELP_EXTRA, 0, input);
1493 if (text)
1495 if (anything || pre_blank)
1496 __argp_fmtstream_putc (stream, '\n');
1497 __argp_fmtstream_puts (stream, text);
1498 free ((char *) text);
1499 if (__argp_fmtstream_point (stream)
1500 > __argp_fmtstream_lmargin (stream))
1501 __argp_fmtstream_putc (stream, '\n');
1502 anything = 1;
1506 if (child)
1507 while (child->argp && !(first_only && anything))
1508 anything |=
1509 argp_doc ((child++)->argp, state,
1510 post, anything || pre_blank, first_only,
1511 stream);
1513 return anything;
1516 /* Output a usage message for ARGP to STREAM. If called from
1517 argp_state_help, STATE is the relevent parsing state. FLAGS are from the
1518 set ARGP_HELP_*. NAME is what to use wherever a `program name' is
1519 needed. */
1520 static void
1521 _help (const struct argp *argp, const struct argp_state *state, FILE *stream,
1522 unsigned flags, char *name)
1524 int anything = 0; /* Whether we've output anything. */
1525 struct hol *hol = 0;
1526 argp_fmtstream_t fs;
1528 if (! stream)
1529 return;
1531 flockfile (stream);
1533 if (! uparams.valid)
1534 fill_in_uparams (state);
1536 fs = __argp_make_fmtstream (stream, 0, uparams.rmargin, 0);
1537 if (! fs)
1539 funlockfile (stream);
1540 return;
1543 if (flags & (ARGP_HELP_USAGE | ARGP_HELP_SHORT_USAGE | ARGP_HELP_LONG))
1545 hol = argp_hol (argp, 0);
1547 /* If present, these options always come last. */
1548 hol_set_group (hol, "help", -1);
1549 hol_set_group (hol, "version", -1);
1551 hol_sort (hol);
1554 if (flags & (ARGP_HELP_USAGE | ARGP_HELP_SHORT_USAGE))
1555 /* Print a short `Usage:' message. */
1557 int first_pattern = 1, more_patterns;
1558 size_t num_pattern_levels = argp_args_levels (argp);
1559 char *pattern_levels = alloca (num_pattern_levels);
1561 memset (pattern_levels, 0, num_pattern_levels);
1565 int old_lm;
1566 int old_wm = __argp_fmtstream_set_wmargin (fs, uparams.usage_indent);
1567 char *levels = pattern_levels;
1569 if (first_pattern)
1570 __argp_fmtstream_printf (fs, "%s %s",
1571 dgettext (argp->argp_domain, "Usage:"),
1572 name);
1573 else
1574 __argp_fmtstream_printf (fs, "%s %s",
1575 dgettext (argp->argp_domain, " or: "),
1576 name);
1578 /* We set the lmargin as well as the wmargin, because hol_usage
1579 manually wraps options with newline to avoid annoying breaks. */
1580 old_lm = __argp_fmtstream_set_lmargin (fs, uparams.usage_indent);
1582 if (flags & ARGP_HELP_SHORT_USAGE)
1583 /* Just show where the options go. */
1585 if (hol->num_entries > 0)
1586 __argp_fmtstream_puts (fs, dgettext (argp->argp_domain,
1587 " [OPTION...]"));
1589 else
1590 /* Actually print the options. */
1592 hol_usage (hol, fs);
1593 flags |= ARGP_HELP_SHORT_USAGE; /* But only do so once. */
1596 more_patterns = argp_args_usage (argp, state, &levels, 1, fs);
1598 __argp_fmtstream_set_wmargin (fs, old_wm);
1599 __argp_fmtstream_set_lmargin (fs, old_lm);
1601 __argp_fmtstream_putc (fs, '\n');
1602 anything = 1;
1604 first_pattern = 0;
1606 while (more_patterns);
1609 if (flags & ARGP_HELP_PRE_DOC)
1610 anything |= argp_doc (argp, state, 0, 0, 1, fs);
1612 if (flags & ARGP_HELP_SEE)
1614 __argp_fmtstream_printf (fs, dgettext (argp->argp_domain, "\
1615 Try `%s --help' or `%s --usage' for more information.\n"),
1616 name, name);
1617 anything = 1;
1620 if (flags & ARGP_HELP_LONG)
1621 /* Print a long, detailed help message. */
1623 /* Print info about all the options. */
1624 if (hol->num_entries > 0)
1626 if (anything)
1627 __argp_fmtstream_putc (fs, '\n');
1628 hol_help (hol, state, fs);
1629 anything = 1;
1633 if (flags & ARGP_HELP_POST_DOC)
1634 /* Print any documentation strings at the end. */
1635 anything |= argp_doc (argp, state, 1, anything, 0, fs);
1637 if ((flags & ARGP_HELP_BUG_ADDR) && argp_program_bug_address)
1639 if (anything)
1640 __argp_fmtstream_putc (fs, '\n');
1641 __argp_fmtstream_printf (fs, dgettext (argp->argp_domain,
1642 "Report bugs to %s.\n"),
1643 argp_program_bug_address);
1644 anything = 1;
1647 funlockfile (stream);
1649 if (hol)
1650 hol_free (hol);
1652 __argp_fmtstream_free (fs);
1655 /* Output a usage message for ARGP to STREAM. FLAGS are from the set
1656 ARGP_HELP_*. NAME is what to use wherever a `program name' is needed. */
1657 void __argp_help (const struct argp *argp, FILE *stream,
1658 unsigned flags, char *name)
1660 _help (argp, 0, stream, flags, name);
1662 #ifdef weak_alias
1663 weak_alias (__argp_help, argp_help)
1664 #endif
1666 /* Output, if appropriate, a usage message for STATE to STREAM. FLAGS are
1667 from the set ARGP_HELP_*. */
1668 void
1669 __argp_state_help (const struct argp_state *state, FILE *stream, unsigned flags)
1671 if ((!state || ! (state->flags & ARGP_NO_ERRS)) && stream)
1673 if (state && (state->flags & ARGP_LONG_ONLY))
1674 flags |= ARGP_HELP_LONG_ONLY;
1676 _help (state ? state->root_argp : 0, state, stream, flags,
1677 state ? state->name : program_invocation_short_name);
1679 if (!state || ! (state->flags & ARGP_NO_EXIT))
1681 if (flags & ARGP_HELP_EXIT_ERR)
1682 exit (argp_err_exit_status);
1683 if (flags & ARGP_HELP_EXIT_OK)
1684 exit (0);
1688 #ifdef weak_alias
1689 weak_alias (__argp_state_help, argp_state_help)
1690 #endif
1692 /* If appropriate, print the printf string FMT and following args, preceded
1693 by the program name and `:', to stderr, and followed by a `Try ... --help'
1694 message, then exit (1). */
1695 void
1696 __argp_error (const struct argp_state *state, const char *fmt, ...)
1698 if (!state || !(state->flags & ARGP_NO_ERRS))
1700 FILE *stream = state ? state->err_stream : stderr;
1702 if (stream)
1704 va_list ap;
1706 flockfile (stream);
1708 fputs_unlocked (state ? state->name : program_invocation_short_name,
1709 stream);
1710 putc_unlocked (':', stream);
1711 putc_unlocked (' ', stream);
1713 va_start (ap, fmt);
1714 vfprintf (stream, fmt, ap);
1715 va_end (ap);
1717 putc_unlocked ('\n', stream);
1719 __argp_state_help (state, stream, ARGP_HELP_STD_ERR);
1721 funlockfile (stream);
1725 #ifdef weak_alias
1726 weak_alias (__argp_error, argp_error)
1727 #endif
1729 /* Similar to the standard gnu error-reporting function error(), but will
1730 respect the ARGP_NO_EXIT and ARGP_NO_ERRS flags in STATE, and will print
1731 to STATE->err_stream. This is useful for argument parsing code that is
1732 shared between program startup (when exiting is desired) and runtime
1733 option parsing (when typically an error code is returned instead). The
1734 difference between this function and argp_error is that the latter is for
1735 *parsing errors*, and the former is for other problems that occur during
1736 parsing but don't reflect a (syntactic) problem with the input. */
1737 void
1738 __argp_failure (const struct argp_state *state, int status, int errnum,
1739 const char *fmt, ...)
1741 if (!state || !(state->flags & ARGP_NO_ERRS))
1743 FILE *stream = state ? state->err_stream : stderr;
1745 if (stream)
1747 flockfile (stream);
1749 fputs_unlocked (state ? state->name : program_invocation_short_name,
1750 stream);
1752 if (fmt)
1754 va_list ap;
1756 putc_unlocked (':', stream);
1757 putc_unlocked (' ', stream);
1759 va_start (ap, fmt);
1760 vfprintf (stream, fmt, ap);
1761 va_end (ap);
1764 if (errnum)
1766 putc_unlocked (':', stream);
1767 putc_unlocked (' ', stream);
1768 fputs (strerror (errnum), stream);
1771 putc_unlocked ('\n', stream);
1773 funlockfile (stream);
1775 if (status && (!state || !(state->flags & ARGP_NO_EXIT)))
1776 exit (status);
1780 #ifdef weak_alias
1781 weak_alias (__argp_failure, argp_failure)
1782 #endif