.
[glibc/history.git] / argp / argp-help.c
blobc12b10e235fcb9901b53fd14b85cf86281ba204a
1 /* Hierarchial argument parsing help output
2 Copyright (C) 1995-2003, 2004, 2005, 2006, 2007
3 Free Software Foundation, Inc.
4 This file is part of the GNU C Library.
5 Written by Miles Bader <miles@gnu.ai.mit.edu>.
7 The GNU C Library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Lesser General Public
9 License as published by the Free Software Foundation; either
10 version 2.1 of the License, or (at your option) any later version.
12 The GNU C Library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Lesser General Public License for more details.
17 You should have received a copy of the GNU Lesser General Public
18 License along with the GNU C Library; if not, write to the Free
19 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
20 02111-1307 USA. */
22 #ifndef _GNU_SOURCE
23 # define _GNU_SOURCE 1
24 #endif
26 #ifdef HAVE_CONFIG_H
27 #include <config.h>
28 #endif
30 /* AIX requires this to be the first thing in the file. */
31 #ifndef __GNUC__
32 # if HAVE_ALLOCA_H || defined _LIBC
33 # include <alloca.h>
34 # else
35 # ifdef _AIX
36 #pragma alloca
37 # else
38 # ifndef alloca /* predefined by HP cc +Olibcalls */
39 char *alloca ();
40 # endif
41 # endif
42 # endif
43 #endif
45 #include <stddef.h>
46 #include <stdlib.h>
47 #include <string.h>
48 #include <assert.h>
49 #include <stdarg.h>
50 #include <ctype.h>
51 #include <limits.h>
52 #ifdef _LIBC
53 # include <../libio/libioP.h>
54 # include <wchar.h>
55 #endif
57 #ifndef _
58 /* This is for other GNU distributions with internationalized messages. */
59 # if defined HAVE_LIBINTL_H || defined _LIBC
60 # include <libintl.h>
61 # ifdef _LIBC
62 # undef dgettext
63 # define dgettext(domain, msgid) \
64 INTUSE(__dcgettext) (domain, msgid, LC_MESSAGES)
65 # endif
66 # else
67 # define dgettext(domain, msgid) (msgid)
68 # endif
69 #endif
71 #ifndef _LIBC
72 # if HAVE_STRERROR_R
73 # if !HAVE_DECL_STRERROR_R
74 char *strerror_r (int errnum, char *buf, size_t buflen);
75 # endif
76 # else
77 # if !HAVE_DECL_STRERROR
78 char *strerror (int errnum);
79 # endif
80 # endif
81 #endif
83 #include "argp.h"
84 #include "argp-fmtstream.h"
85 #include "argp-namefrob.h"
87 #ifndef SIZE_MAX
88 # define SIZE_MAX ((size_t) -1)
89 #endif
91 /* User-selectable (using an environment variable) formatting parameters.
93 These may be specified in an environment variable called `ARGP_HELP_FMT',
94 with a contents like: VAR1=VAL1,VAR2=VAL2,BOOLVAR2,no-BOOLVAR2
95 Where VALn must be a positive integer. The list of variables is in the
96 UPARAM_NAMES vector, below. */
98 /* Default parameters. */
99 #define DUP_ARGS 0 /* True if option argument can be duplicated. */
100 #define DUP_ARGS_NOTE 1 /* True to print a note about duplicate args. */
101 #define SHORT_OPT_COL 2 /* column in which short options start */
102 #define LONG_OPT_COL 6 /* column in which long options start */
103 #define DOC_OPT_COL 2 /* column in which doc options start */
104 #define OPT_DOC_COL 29 /* column in which option text starts */
105 #define HEADER_COL 1 /* column in which group headers are printed */
106 #define USAGE_INDENT 12 /* indentation of wrapped usage lines */
107 #define RMARGIN 79 /* right margin used for wrapping */
109 /* User-selectable (using an environment variable) formatting parameters.
110 They must all be of type `int' for the parsing code to work. */
111 struct uparams
113 /* If true, arguments for an option are shown with both short and long
114 options, even when a given option has both, e.g. `-x ARG, --longx=ARG'.
115 If false, then if an option has both, the argument is only shown with
116 the long one, e.g., `-x, --longx=ARG', and a message indicating that
117 this really means both is printed below the options. */
118 int dup_args;
120 /* This is true if when DUP_ARGS is false, and some duplicate arguments have
121 been suppressed, an explanatory message should be printed. */
122 int dup_args_note;
124 /* Various output columns. */
125 int short_opt_col;
126 int long_opt_col;
127 int doc_opt_col;
128 int opt_doc_col;
129 int header_col;
130 int usage_indent;
131 int rmargin;
134 /* This is a global variable, as user options are only ever read once. */
135 static struct uparams uparams = {
136 DUP_ARGS, DUP_ARGS_NOTE,
137 SHORT_OPT_COL, LONG_OPT_COL, DOC_OPT_COL, OPT_DOC_COL, HEADER_COL,
138 USAGE_INDENT, RMARGIN
141 /* A particular uparam, and what the user name is. */
142 struct uparam_name
144 const char name[14]; /* User name. */
145 bool is_bool; /* Whether it's `boolean'. */
146 uint8_t uparams_offs; /* Location of the (int) field in UPARAMS. */
149 /* The name-field mappings we know about. */
150 static const struct uparam_name uparam_names[] =
152 { "dup-args", true, offsetof (struct uparams, dup_args) },
153 { "dup-args-note", true, offsetof (struct uparams, dup_args_note) },
154 { "short-opt-col", false, offsetof (struct uparams, short_opt_col) },
155 { "long-opt-col", false, offsetof (struct uparams, long_opt_col) },
156 { "doc-opt-col", false, offsetof (struct uparams, doc_opt_col) },
157 { "opt-doc-col", false, offsetof (struct uparams, opt_doc_col) },
158 { "header-col", false, offsetof (struct uparams, header_col) },
159 { "usage-indent", false, offsetof (struct uparams, usage_indent) },
160 { "rmargin", false, offsetof (struct uparams, rmargin) }
162 #define nuparam_names (sizeof (uparam_names) / sizeof (uparam_names[0]))
164 /* Read user options from the environment, and fill in UPARAMS appropiately. */
165 static void
166 fill_in_uparams (const struct argp_state *state)
168 const char *var = getenv ("ARGP_HELP_FMT");
170 #define SKIPWS(p) do { while (isspace (*p)) p++; } while (0);
172 if (var)
173 /* Parse var. */
174 while (*var)
176 SKIPWS (var);
178 if (isalpha (*var))
180 size_t var_len;
181 const struct uparam_name *un;
182 int unspec = 0, val = 0;
183 const char *arg = var;
185 while (isalnum (*arg) || *arg == '-' || *arg == '_')
186 arg++;
187 var_len = arg - var;
189 SKIPWS (arg);
191 if (*arg == '\0' || *arg == ',')
192 unspec = 1;
193 else if (*arg == '=')
195 arg++;
196 SKIPWS (arg);
199 if (unspec)
201 if (var[0] == 'n' && var[1] == 'o' && var[2] == '-')
203 val = 0;
204 var += 3;
205 var_len -= 3;
207 else
208 val = 1;
210 else if (isdigit (*arg))
212 val = atoi (arg);
213 while (isdigit (*arg))
214 arg++;
215 SKIPWS (arg);
218 un = uparam_names;
219 size_t u;
220 for (u = 0; u < nuparam_names; ++un, ++u)
221 if (strlen (un->name) == var_len
222 && strncmp (var, un->name, var_len) == 0)
224 if (unspec && !un->is_bool)
225 __argp_failure (state, 0, 0,
226 dgettext (state == NULL ? NULL
227 : state->root_argp->argp_domain,
229 %.*s: ARGP_HELP_FMT parameter requires a value"),
230 (int) var_len, var);
231 else
232 *(int *)((char *)&uparams + un->uparams_offs) = val;
233 break;
235 if (u == nuparam_names)
236 __argp_failure (state, 0, 0,
237 dgettext (state == NULL ? NULL
238 : state->root_argp->argp_domain, "\
239 %.*s: Unknown ARGP_HELP_FMT parameter"),
240 (int) var_len, var);
242 var = arg;
243 if (*var == ',')
244 var++;
246 else if (*var)
248 __argp_failure (state, 0, 0,
249 dgettext (state == NULL ? NULL
250 : state->root_argp->argp_domain,
251 "Garbage in ARGP_HELP_FMT: %s"), var);
252 break;
257 /* Returns true if OPT hasn't been marked invisible. Visibility only affects
258 whether OPT is displayed or used in sorting, not option shadowing. */
259 #define ovisible(opt) (! ((opt)->flags & OPTION_HIDDEN))
261 /* Returns true if OPT is an alias for an earlier option. */
262 #define oalias(opt) ((opt)->flags & OPTION_ALIAS)
264 /* Returns true if OPT is an documentation-only entry. */
265 #define odoc(opt) ((opt)->flags & OPTION_DOC)
267 /* Returns true if OPT is the end-of-list marker for a list of options. */
268 #define oend(opt) __option_is_end (opt)
270 /* Returns true if OPT has a short option. */
271 #define oshort(opt) __option_is_short (opt)
274 The help format for a particular option is like:
276 -xARG, -yARG, --long1=ARG, --long2=ARG Documentation...
278 Where ARG will be omitted if there's no argument, for this option, or
279 will be surrounded by "[" and "]" appropiately if the argument is
280 optional. The documentation string is word-wrapped appropiately, and if
281 the list of options is long enough, it will be started on a separate line.
282 If there are no short options for a given option, the first long option is
283 indented slighly in a way that's supposed to make most long options appear
284 to be in a separate column.
286 For example, the following output (from ps):
288 -p PID, --pid=PID List the process PID
289 --pgrp=PGRP List processes in the process group PGRP
290 -P, -x, --no-parent Include processes without parents
291 -Q, --all-fields Don't elide unusable fields (normally if there's
292 some reason ps can't print a field for any
293 process, it's removed from the output entirely)
294 -r, --reverse, --gratuitously-long-reverse-option
295 Reverse the order of any sort
296 --session[=SID] Add the processes from the session SID (which
297 defaults to the sid of the current process)
299 Here are some more options:
300 -f ZOT, --foonly=ZOT Glork a foonly
301 -z, --zaza Snit a zar
303 -?, --help Give this help list
304 --usage Give a short usage message
305 -V, --version Print program version
307 The struct argp_option array for the above could look like:
310 {"pid", 'p', "PID", 0, "List the process PID"},
311 {"pgrp", OPT_PGRP, "PGRP", 0, "List processes in the process group PGRP"},
312 {"no-parent", 'P', 0, 0, "Include processes without parents"},
313 {0, 'x', 0, OPTION_ALIAS},
314 {"all-fields",'Q', 0, 0, "Don't elide unusable fields (normally"
315 " if there's some reason ps can't"
316 " print a field for any process, it's"
317 " removed from the output entirely)" },
318 {"reverse", 'r', 0, 0, "Reverse the order of any sort"},
319 {"gratuitously-long-reverse-option", 0, 0, OPTION_ALIAS},
320 {"session", OPT_SESS, "SID", OPTION_ARG_OPTIONAL,
321 "Add the processes from the session"
322 " SID (which defaults to the sid of"
323 " the current process)" },
325 {0,0,0,0, "Here are some more options:"},
326 {"foonly", 'f', "ZOT", 0, "Glork a foonly"},
327 {"zaza", 'z', 0, 0, "Snit a zar"},
332 Note that the last three options are automatically supplied by argp_parse,
333 unless you tell it not to with ARGP_NO_HELP.
337 /* Returns true if CH occurs between BEG and END. */
338 static int
339 find_char (char ch, char *beg, char *end)
341 while (beg < end)
342 if (*beg == ch)
343 return 1;
344 else
345 beg++;
346 return 0;
349 struct hol_cluster; /* fwd decl */
351 struct hol_entry
353 /* First option. */
354 const struct argp_option *opt;
355 /* Number of options (including aliases). */
356 unsigned num;
358 /* A pointers into the HOL's short_options field, to the first short option
359 letter for this entry. The order of the characters following this point
360 corresponds to the order of options pointed to by OPT, and there are at
361 most NUM. A short option recorded in a option following OPT is only
362 valid if it occurs in the right place in SHORT_OPTIONS (otherwise it's
363 probably been shadowed by some other entry). */
364 char *short_options;
366 /* Entries are sorted by their group first, in the order:
367 1, 2, ..., n, 0, -m, ..., -2, -1
368 and then alphabetically within each group. The default is 0. */
369 int group;
371 /* The cluster of options this entry belongs to, or 0 if none. */
372 struct hol_cluster *cluster;
374 /* The argp from which this option came. */
375 const struct argp *argp;
378 /* A cluster of entries to reflect the argp tree structure. */
379 struct hol_cluster
381 /* A descriptive header printed before options in this cluster. */
382 const char *header;
384 /* Used to order clusters within the same group with the same parent,
385 according to the order in which they occurred in the parent argp's child
386 list. */
387 int index;
389 /* How to sort this cluster with respect to options and other clusters at the
390 same depth (clusters always follow options in the same group). */
391 int group;
393 /* The cluster to which this cluster belongs, or 0 if it's at the base
394 level. */
395 struct hol_cluster *parent;
397 /* The argp from which this cluster is (eventually) derived. */
398 const struct argp *argp;
400 /* The distance this cluster is from the root. */
401 int depth;
403 /* Clusters in a given hol are kept in a linked list, to make freeing them
404 possible. */
405 struct hol_cluster *next;
408 /* A list of options for help. */
409 struct hol
411 /* An array of hol_entry's. */
412 struct hol_entry *entries;
413 /* The number of entries in this hol. If this field is zero, the others
414 are undefined. */
415 unsigned num_entries;
417 /* A string containing all short options in this HOL. Each entry contains
418 pointers into this string, so the order can't be messed with blindly. */
419 char *short_options;
421 /* Clusters of entries in this hol. */
422 struct hol_cluster *clusters;
425 /* Create a struct hol from the options in ARGP. CLUSTER is the
426 hol_cluster in which these entries occur, or 0, if at the root. */
427 static struct hol *
428 make_hol (const struct argp *argp, struct hol_cluster *cluster)
430 char *so;
431 const struct argp_option *o;
432 const struct argp_option *opts = argp->options;
433 struct hol_entry *entry;
434 unsigned num_short_options = 0;
435 struct hol *hol = malloc (sizeof (struct hol));
437 assert (hol);
439 hol->num_entries = 0;
440 hol->clusters = 0;
442 if (opts)
444 int cur_group = 0;
446 /* The first option must not be an alias. */
447 assert (! oalias (opts));
449 /* Calculate the space needed. */
450 for (o = opts; ! oend (o); o++)
452 if (! oalias (o))
453 hol->num_entries++;
454 if (oshort (o))
455 num_short_options++; /* This is an upper bound. */
458 hol->entries = malloc (sizeof (struct hol_entry) * hol->num_entries);
459 hol->short_options = malloc (num_short_options + 1);
461 assert (hol->entries && hol->short_options);
462 #if SIZE_MAX <= UINT_MAX
463 assert (hol->num_entries <= SIZE_MAX / sizeof (struct hol_entry));
464 #endif
466 /* Fill in the entries. */
467 so = hol->short_options;
468 for (o = opts, entry = hol->entries; ! oend (o); entry++)
470 entry->opt = o;
471 entry->num = 0;
472 entry->short_options = so;
473 entry->group = cur_group =
474 o->group
475 ? o->group
476 : ((!o->name && !o->key)
477 ? cur_group + 1
478 : cur_group);
479 entry->cluster = cluster;
480 entry->argp = argp;
484 entry->num++;
485 if (oshort (o) && ! find_char (o->key, hol->short_options, so))
486 /* O has a valid short option which hasn't already been used.*/
487 *so++ = o->key;
488 o++;
490 while (! oend (o) && oalias (o));
492 *so = '\0'; /* null terminated so we can find the length */
495 return hol;
498 /* Add a new cluster to HOL, with the given GROUP and HEADER (taken from the
499 associated argp child list entry), INDEX, and PARENT, and return a pointer
500 to it. ARGP is the argp that this cluster results from. */
501 static struct hol_cluster *
502 hol_add_cluster (struct hol *hol, int group, const char *header, int index,
503 struct hol_cluster *parent, const struct argp *argp)
505 struct hol_cluster *cl = malloc (sizeof (struct hol_cluster));
506 if (cl)
508 cl->group = group;
509 cl->header = header;
511 cl->index = index;
512 cl->parent = parent;
513 cl->argp = argp;
514 cl->depth = parent ? parent->depth + 1 : 0;
516 cl->next = hol->clusters;
517 hol->clusters = cl;
519 return cl;
522 /* Free HOL and any resources it uses. */
523 static void
524 hol_free (struct hol *hol)
526 struct hol_cluster *cl = hol->clusters;
528 while (cl)
530 struct hol_cluster *next = cl->next;
531 free (cl);
532 cl = next;
535 if (hol->num_entries > 0)
537 free (hol->entries);
538 free (hol->short_options);
541 free (hol);
544 static int
545 hol_entry_short_iterate (const struct hol_entry *entry,
546 int (*func)(const struct argp_option *opt,
547 const struct argp_option *real,
548 const char *domain, void *cookie),
549 const char *domain, void *cookie)
551 unsigned nopts;
552 int val = 0;
553 const struct argp_option *opt, *real = entry->opt;
554 char *so = entry->short_options;
556 for (opt = real, nopts = entry->num; nopts > 0 && !val; opt++, nopts--)
557 if (oshort (opt) && *so == opt->key)
559 if (!oalias (opt))
560 real = opt;
561 if (ovisible (opt))
562 val = (*func)(opt, real, domain, cookie);
563 so++;
566 return val;
569 static inline int
570 __attribute__ ((always_inline))
571 hol_entry_long_iterate (const struct hol_entry *entry,
572 int (*func)(const struct argp_option *opt,
573 const struct argp_option *real,
574 const char *domain, void *cookie),
575 const char *domain, void *cookie)
577 unsigned nopts;
578 int val = 0;
579 const struct argp_option *opt, *real = entry->opt;
581 for (opt = real, nopts = entry->num; nopts > 0 && !val; opt++, nopts--)
582 if (opt->name)
584 if (!oalias (opt))
585 real = opt;
586 if (ovisible (opt))
587 val = (*func)(opt, real, domain, cookie);
590 return val;
593 /* Iterator that returns true for the first short option. */
594 static inline int
595 until_short (const struct argp_option *opt, const struct argp_option *real,
596 const char *domain, void *cookie)
598 return oshort (opt) ? opt->key : 0;
601 /* Returns the first valid short option in ENTRY, or 0 if there is none. */
602 static char
603 hol_entry_first_short (const struct hol_entry *entry)
605 return hol_entry_short_iterate (entry, until_short,
606 entry->argp->argp_domain, 0);
609 /* Returns the first valid long option in ENTRY, or 0 if there is none. */
610 static const char *
611 hol_entry_first_long (const struct hol_entry *entry)
613 const struct argp_option *opt;
614 unsigned num;
615 for (opt = entry->opt, num = entry->num; num > 0; opt++, num--)
616 if (opt->name && ovisible (opt))
617 return opt->name;
618 return 0;
621 /* Returns the entry in HOL with the long option name NAME, or 0 if there is
622 none. */
623 static struct hol_entry *
624 hol_find_entry (struct hol *hol, const char *name)
626 struct hol_entry *entry = hol->entries;
627 unsigned num_entries = hol->num_entries;
629 while (num_entries-- > 0)
631 const struct argp_option *opt = entry->opt;
632 unsigned num_opts = entry->num;
634 while (num_opts-- > 0)
635 if (opt->name && ovisible (opt) && strcmp (opt->name, name) == 0)
636 return entry;
637 else
638 opt++;
640 entry++;
643 return 0;
646 /* If an entry with the long option NAME occurs in HOL, set it's special
647 sort position to GROUP. */
648 static void
649 hol_set_group (struct hol *hol, const char *name, int group)
651 struct hol_entry *entry = hol_find_entry (hol, name);
652 if (entry)
653 entry->group = group;
656 /* Order by group: 0, 1, 2, ..., n, -m, ..., -2, -1.
657 EQ is what to return if GROUP1 and GROUP2 are the same. */
658 static int
659 group_cmp (int group1, int group2, int eq)
661 if (group1 == group2)
662 return eq;
663 else if ((group1 < 0 && group2 < 0) || (group1 >= 0 && group2 >= 0))
664 return group1 - group2;
665 else
666 return group2 - group1;
669 /* Compare clusters CL1 & CL2 by the order that they should appear in
670 output. */
671 static int
672 hol_cluster_cmp (const struct hol_cluster *cl1, const struct hol_cluster *cl2)
674 /* If one cluster is deeper than the other, use its ancestor at the same
675 level, so that finding the common ancestor is straightforward. */
676 while (cl1->depth > cl2->depth)
677 cl1 = cl1->parent;
678 while (cl2->depth > cl1->depth)
679 cl2 = cl2->parent;
681 /* Now reduce both clusters to their ancestors at the point where both have
682 a common parent; these can be directly compared. */
683 while (cl1->parent != cl2->parent)
684 cl1 = cl1->parent, cl2 = cl2->parent;
686 return group_cmp (cl1->group, cl2->group, cl2->index - cl1->index);
689 /* Return the ancestor of CL that's just below the root (i.e., has a parent
690 of 0). */
691 static struct hol_cluster *
692 hol_cluster_base (struct hol_cluster *cl)
694 while (cl->parent)
695 cl = cl->parent;
696 return cl;
699 /* Return true if CL1 is a child of CL2. */
700 static int
701 hol_cluster_is_child (const struct hol_cluster *cl1,
702 const struct hol_cluster *cl2)
704 while (cl1 && cl1 != cl2)
705 cl1 = cl1->parent;
706 return cl1 == cl2;
709 /* Given the name of a OPTION_DOC option, modifies NAME to start at the tail
710 that should be used for comparisons, and returns true iff it should be
711 treated as a non-option. */
712 static int
713 canon_doc_option (const char **name)
715 int non_opt;
716 /* Skip initial whitespace. */
717 while (isspace (**name))
718 (*name)++;
719 /* Decide whether this looks like an option (leading `-') or not. */
720 non_opt = (**name != '-');
721 /* Skip until part of name used for sorting. */
722 while (**name && !isalnum (**name))
723 (*name)++;
724 return non_opt;
727 /* Order ENTRY1 & ENTRY2 by the order which they should appear in a help
728 listing. */
729 static int
730 hol_entry_cmp (const struct hol_entry *entry1,
731 const struct hol_entry *entry2)
733 /* The group numbers by which the entries should be ordered; if either is
734 in a cluster, then this is just the group within the cluster. */
735 int group1 = entry1->group, group2 = entry2->group;
737 if (entry1->cluster != entry2->cluster)
739 /* The entries are not within the same cluster, so we can't compare them
740 directly, we have to use the appropiate clustering level too. */
741 if (! entry1->cluster)
742 /* ENTRY1 is at the `base level', not in a cluster, so we have to
743 compare it's group number with that of the base cluster in which
744 ENTRY2 resides. Note that if they're in the same group, the
745 clustered option always comes laster. */
746 return group_cmp (group1, hol_cluster_base (entry2->cluster)->group, -1);
747 else if (! entry2->cluster)
748 /* Likewise, but ENTRY2's not in a cluster. */
749 return group_cmp (hol_cluster_base (entry1->cluster)->group, group2, 1);
750 else
751 /* Both entries are in clusters, we can just compare the clusters. */
752 return hol_cluster_cmp (entry1->cluster, entry2->cluster);
754 else if (group1 == group2)
755 /* The entries are both in the same cluster and group, so compare them
756 alphabetically. */
758 int short1 = hol_entry_first_short (entry1);
759 int short2 = hol_entry_first_short (entry2);
760 int doc1 = odoc (entry1->opt);
761 int doc2 = odoc (entry2->opt);
762 const char *long1 = hol_entry_first_long (entry1);
763 const char *long2 = hol_entry_first_long (entry2);
765 if (doc1)
766 doc1 = long1 != NULL && canon_doc_option (&long1);
767 if (doc2)
768 doc2 = long2 != NULL && canon_doc_option (&long2);
770 if (doc1 != doc2)
771 /* `documentation' options always follow normal options (or
772 documentation options that *look* like normal options). */
773 return doc1 - doc2;
774 else if (!short1 && !short2 && long1 && long2)
775 /* Only long options. */
776 return __strcasecmp (long1, long2);
777 else
778 /* Compare short/short, long/short, short/long, using the first
779 character of long options. Entries without *any* valid
780 options (such as options with OPTION_HIDDEN set) will be put
781 first, but as they're not displayed, it doesn't matter where
782 they are. */
784 char first1 = short1 ? short1 : long1 ? *long1 : 0;
785 char first2 = short2 ? short2 : long2 ? *long2 : 0;
786 #ifdef _tolower
787 int lower_cmp = _tolower (first1) - _tolower (first2);
788 #else
789 int lower_cmp = tolower (first1) - tolower (first2);
790 #endif
791 /* Compare ignoring case, except when the options are both the
792 same letter, in which case lower-case always comes first. */
793 return lower_cmp ? lower_cmp : first2 - first1;
796 else
797 /* Within the same cluster, but not the same group, so just compare
798 groups. */
799 return group_cmp (group1, group2, 0);
802 /* Version of hol_entry_cmp with correct signature for qsort. */
803 static int
804 hol_entry_qcmp (const void *entry1_v, const void *entry2_v)
806 return hol_entry_cmp (entry1_v, entry2_v);
809 /* Sort HOL by group and alphabetically by option name (with short options
810 taking precedence over long). Since the sorting is for display purposes
811 only, the shadowing of options isn't effected. */
812 static void
813 hol_sort (struct hol *hol)
815 if (hol->num_entries > 0)
816 qsort (hol->entries, hol->num_entries, sizeof (struct hol_entry),
817 hol_entry_qcmp);
820 /* Append MORE to HOL, destroying MORE in the process. Options in HOL shadow
821 any in MORE with the same name. */
822 static void
823 hol_append (struct hol *hol, struct hol *more)
825 struct hol_cluster **cl_end = &hol->clusters;
827 /* Steal MORE's cluster list, and add it to the end of HOL's. */
828 while (*cl_end)
829 cl_end = &(*cl_end)->next;
830 *cl_end = more->clusters;
831 more->clusters = 0;
833 /* Merge entries. */
834 if (more->num_entries > 0)
836 if (hol->num_entries == 0)
838 hol->num_entries = more->num_entries;
839 hol->entries = more->entries;
840 hol->short_options = more->short_options;
841 more->num_entries = 0; /* Mark MORE's fields as invalid. */
843 else
844 /* Append the entries in MORE to those in HOL, taking care to only add
845 non-shadowed SHORT_OPTIONS values. */
847 unsigned left;
848 char *so, *more_so;
849 struct hol_entry *e;
850 unsigned num_entries = hol->num_entries + more->num_entries;
851 struct hol_entry *entries =
852 malloc (num_entries * sizeof (struct hol_entry));
853 unsigned hol_so_len = strlen (hol->short_options);
854 char *short_options =
855 malloc (hol_so_len + strlen (more->short_options) + 1);
857 assert (entries && short_options);
858 #if SIZE_MAX <= UINT_MAX
859 assert (num_entries <= SIZE_MAX / sizeof (struct hol_entry));
860 #endif
862 __mempcpy (__mempcpy (entries, hol->entries,
863 hol->num_entries * sizeof (struct hol_entry)),
864 more->entries,
865 more->num_entries * sizeof (struct hol_entry));
867 __mempcpy (short_options, hol->short_options, hol_so_len);
869 /* Fix up the short options pointers from HOL. */
870 for (e = entries, left = hol->num_entries; left > 0; e++, left--)
871 e->short_options += (short_options - hol->short_options);
873 /* Now add the short options from MORE, fixing up its entries
874 too. */
875 so = short_options + hol_so_len;
876 more_so = more->short_options;
877 for (left = more->num_entries; left > 0; e++, left--)
879 int opts_left;
880 const struct argp_option *opt;
882 e->short_options = so;
884 for (opts_left = e->num, opt = e->opt; opts_left; opt++, opts_left--)
886 int ch = *more_so;
887 if (oshort (opt) && ch == opt->key)
888 /* The next short option in MORE_SO, CH, is from OPT. */
890 if (! find_char (ch, short_options,
891 short_options + hol_so_len))
892 /* The short option CH isn't shadowed by HOL's options,
893 so add it to the sum. */
894 *so++ = ch;
895 more_so++;
900 *so = '\0';
902 free (hol->entries);
903 free (hol->short_options);
905 hol->entries = entries;
906 hol->num_entries = num_entries;
907 hol->short_options = short_options;
911 hol_free (more);
914 /* Inserts enough spaces to make sure STREAM is at column COL. */
915 static void
916 indent_to (argp_fmtstream_t stream, unsigned col)
918 int needed = col - __argp_fmtstream_point (stream);
919 while (needed-- > 0)
920 __argp_fmtstream_putc (stream, ' ');
923 /* Output to STREAM either a space, or a newline if there isn't room for at
924 least ENSURE characters before the right margin. */
925 static void
926 space (argp_fmtstream_t stream, size_t ensure)
928 if (__argp_fmtstream_point (stream) + ensure
929 >= __argp_fmtstream_rmargin (stream))
930 __argp_fmtstream_putc (stream, '\n');
931 else
932 __argp_fmtstream_putc (stream, ' ');
935 /* If the option REAL has an argument, we print it in using the printf
936 format REQ_FMT or OPT_FMT depending on whether it's a required or
937 optional argument. */
938 static void
939 arg (const struct argp_option *real, const char *req_fmt, const char *opt_fmt,
940 const char *domain, argp_fmtstream_t stream)
942 if (real->arg)
944 if (real->flags & OPTION_ARG_OPTIONAL)
945 __argp_fmtstream_printf (stream, opt_fmt,
946 dgettext (domain, real->arg));
947 else
948 __argp_fmtstream_printf (stream, req_fmt,
949 dgettext (domain, real->arg));
953 /* Helper functions for hol_entry_help. */
955 /* State used during the execution of hol_help. */
956 struct hol_help_state
958 /* PREV_ENTRY should contain the previous entry printed, or 0. */
959 struct hol_entry *prev_entry;
961 /* If an entry is in a different group from the previous one, and SEP_GROUPS
962 is true, then a blank line will be printed before any output. */
963 int sep_groups;
965 /* True if a duplicate option argument was suppressed (only ever set if
966 UPARAMS.dup_args is false). */
967 int suppressed_dup_arg;
970 /* Some state used while printing a help entry (used to communicate with
971 helper functions). See the doc for hol_entry_help for more info, as most
972 of the fields are copied from its arguments. */
973 struct pentry_state
975 const struct hol_entry *entry;
976 argp_fmtstream_t stream;
977 struct hol_help_state *hhstate;
979 /* True if nothing's been printed so far. */
980 int first;
982 /* If non-zero, the state that was used to print this help. */
983 const struct argp_state *state;
986 /* If a user doc filter should be applied to DOC, do so. */
987 static const char *
988 filter_doc (const char *doc, int key, const struct argp *argp,
989 const struct argp_state *state)
991 if (argp && argp->help_filter)
992 /* We must apply a user filter to this output. */
994 void *input = __argp_input (argp, state);
995 return (*argp->help_filter) (key, doc, input);
997 else
998 /* No filter. */
999 return doc;
1002 /* Prints STR as a header line, with the margin lines set appropiately, and
1003 notes the fact that groups should be separated with a blank line. ARGP is
1004 the argp that should dictate any user doc filtering to take place. Note
1005 that the previous wrap margin isn't restored, but the left margin is reset
1006 to 0. */
1007 static void
1008 print_header (const char *str, const struct argp *argp,
1009 struct pentry_state *pest)
1011 const char *tstr = dgettext (argp->argp_domain, str);
1012 const char *fstr = filter_doc (tstr, ARGP_KEY_HELP_HEADER, argp, pest->state);
1014 if (fstr)
1016 if (*fstr)
1018 if (pest->hhstate->prev_entry)
1019 /* Precede with a blank line. */
1020 __argp_fmtstream_putc (pest->stream, '\n');
1021 indent_to (pest->stream, uparams.header_col);
1022 __argp_fmtstream_set_lmargin (pest->stream, uparams.header_col);
1023 __argp_fmtstream_set_wmargin (pest->stream, uparams.header_col);
1024 __argp_fmtstream_puts (pest->stream, fstr);
1025 __argp_fmtstream_set_lmargin (pest->stream, 0);
1026 __argp_fmtstream_putc (pest->stream, '\n');
1029 pest->hhstate->sep_groups = 1; /* Separate subsequent groups. */
1032 if (fstr != tstr)
1033 free ((char *) fstr);
1036 /* Inserts a comma if this isn't the first item on the line, and then makes
1037 sure we're at least to column COL. If this *is* the first item on a line,
1038 prints any pending whitespace/headers that should precede this line. Also
1039 clears FIRST. */
1040 static void
1041 comma (unsigned col, struct pentry_state *pest)
1043 if (pest->first)
1045 const struct hol_entry *pe = pest->hhstate->prev_entry;
1046 const struct hol_cluster *cl = pest->entry->cluster;
1048 if (pest->hhstate->sep_groups && pe && pest->entry->group != pe->group)
1049 __argp_fmtstream_putc (pest->stream, '\n');
1051 if (cl && cl->header && *cl->header
1052 && (!pe
1053 || (pe->cluster != cl
1054 && !hol_cluster_is_child (pe->cluster, cl))))
1055 /* If we're changing clusters, then this must be the start of the
1056 ENTRY's cluster unless that is an ancestor of the previous one
1057 (in which case we had just popped into a sub-cluster for a bit).
1058 If so, then print the cluster's header line. */
1060 int old_wm = __argp_fmtstream_wmargin (pest->stream);
1061 print_header (cl->header, cl->argp, pest);
1062 __argp_fmtstream_set_wmargin (pest->stream, old_wm);
1065 pest->first = 0;
1067 else
1068 __argp_fmtstream_puts (pest->stream, ", ");
1070 indent_to (pest->stream, col);
1073 /* Print help for ENTRY to STREAM. */
1074 static void
1075 hol_entry_help (struct hol_entry *entry, const struct argp_state *state,
1076 argp_fmtstream_t stream, struct hol_help_state *hhstate)
1078 unsigned num;
1079 const struct argp_option *real = entry->opt, *opt;
1080 char *so = entry->short_options;
1081 int have_long_opt = 0; /* We have any long options. */
1082 /* Saved margins. */
1083 int old_lm = __argp_fmtstream_set_lmargin (stream, 0);
1084 int old_wm = __argp_fmtstream_wmargin (stream);
1085 /* PEST is a state block holding some of our variables that we'd like to
1086 share with helper functions. */
1087 struct pentry_state pest = { entry, stream, hhstate, 1, state };
1089 if (! odoc (real))
1090 for (opt = real, num = entry->num; num > 0; opt++, num--)
1091 if (opt->name && ovisible (opt))
1093 have_long_opt = 1;
1094 break;
1097 /* First emit short options. */
1098 __argp_fmtstream_set_wmargin (stream, uparams.short_opt_col); /* For truly bizarre cases. */
1099 for (opt = real, num = entry->num; num > 0; opt++, num--)
1100 if (oshort (opt) && opt->key == *so)
1101 /* OPT has a valid (non shadowed) short option. */
1103 if (ovisible (opt))
1105 comma (uparams.short_opt_col, &pest);
1106 __argp_fmtstream_putc (stream, '-');
1107 __argp_fmtstream_putc (stream, *so);
1108 if (!have_long_opt || uparams.dup_args)
1109 arg (real, " %s", "[%s]",
1110 state == NULL ? NULL : state->root_argp->argp_domain,
1111 stream);
1112 else if (real->arg)
1113 hhstate->suppressed_dup_arg = 1;
1115 so++;
1118 /* Now, long options. */
1119 if (odoc (real))
1120 /* A `documentation' option. */
1122 __argp_fmtstream_set_wmargin (stream, uparams.doc_opt_col);
1123 for (opt = real, num = entry->num; num > 0; opt++, num--)
1124 if (opt->name && ovisible (opt))
1126 comma (uparams.doc_opt_col, &pest);
1127 /* Calling gettext here isn't quite right, since sorting will
1128 have been done on the original; but documentation options
1129 should be pretty rare anyway... */
1130 __argp_fmtstream_puts (stream,
1131 dgettext (state == NULL ? NULL
1132 : state->root_argp->argp_domain,
1133 opt->name));
1136 else
1137 /* A real long option. */
1139 __argp_fmtstream_set_wmargin (stream, uparams.long_opt_col);
1140 for (opt = real, num = entry->num; num > 0; opt++, num--)
1141 if (opt->name && ovisible (opt))
1143 comma (uparams.long_opt_col, &pest);
1144 __argp_fmtstream_printf (stream, "--%s", opt->name);
1145 arg (real, "=%s", "[=%s]",
1146 state == NULL ? NULL : state->root_argp->argp_domain, stream);
1150 /* Next, documentation strings. */
1151 __argp_fmtstream_set_lmargin (stream, 0);
1153 if (pest.first)
1155 /* Didn't print any switches, what's up? */
1156 if (!oshort (real) && !real->name)
1157 /* This is a group header, print it nicely. */
1158 print_header (real->doc, entry->argp, &pest);
1159 else
1160 /* Just a totally shadowed option or null header; print nothing. */
1161 goto cleanup; /* Just return, after cleaning up. */
1163 else
1165 const char *tstr = real->doc ? dgettext (state == NULL ? NULL
1166 : state->root_argp->argp_domain,
1167 real->doc) : 0;
1168 const char *fstr = filter_doc (tstr, real->key, entry->argp, state);
1169 if (fstr && *fstr)
1171 unsigned int col = __argp_fmtstream_point (stream);
1173 __argp_fmtstream_set_lmargin (stream, uparams.opt_doc_col);
1174 __argp_fmtstream_set_wmargin (stream, uparams.opt_doc_col);
1176 if (col > (unsigned int) (uparams.opt_doc_col + 3))
1177 __argp_fmtstream_putc (stream, '\n');
1178 else if (col >= (unsigned int) uparams.opt_doc_col)
1179 __argp_fmtstream_puts (stream, " ");
1180 else
1181 indent_to (stream, uparams.opt_doc_col);
1183 __argp_fmtstream_puts (stream, fstr);
1185 if (fstr && fstr != tstr)
1186 free ((char *) fstr);
1188 /* Reset the left margin. */
1189 __argp_fmtstream_set_lmargin (stream, 0);
1190 __argp_fmtstream_putc (stream, '\n');
1193 hhstate->prev_entry = entry;
1195 cleanup:
1196 __argp_fmtstream_set_lmargin (stream, old_lm);
1197 __argp_fmtstream_set_wmargin (stream, old_wm);
1200 /* Output a long help message about the options in HOL to STREAM. */
1201 static void
1202 hol_help (struct hol *hol, const struct argp_state *state,
1203 argp_fmtstream_t stream)
1205 unsigned num;
1206 struct hol_entry *entry;
1207 struct hol_help_state hhstate = { 0, 0, 0 };
1209 for (entry = hol->entries, num = hol->num_entries; num > 0; entry++, num--)
1210 hol_entry_help (entry, state, stream, &hhstate);
1212 if (hhstate.suppressed_dup_arg && uparams.dup_args_note)
1214 const char *tstr = dgettext (state == NULL ? NULL
1215 : state->root_argp->argp_domain, "\
1216 Mandatory or optional arguments to long options are also mandatory or \
1217 optional for any corresponding short options.");
1218 const char *fstr = filter_doc (tstr, ARGP_KEY_HELP_DUP_ARGS_NOTE,
1219 state ? state->root_argp : 0, state);
1220 if (fstr && *fstr)
1222 __argp_fmtstream_putc (stream, '\n');
1223 __argp_fmtstream_puts (stream, fstr);
1224 __argp_fmtstream_putc (stream, '\n');
1226 if (fstr && fstr != tstr)
1227 free ((char *) fstr);
1231 /* Helper functions for hol_usage. */
1233 /* If OPT is a short option without an arg, append its key to the string
1234 pointer pointer to by COOKIE, and advance the pointer. */
1235 static int
1236 add_argless_short_opt (const struct argp_option *opt,
1237 const struct argp_option *real,
1238 const char *domain, void *cookie)
1240 char **snao_end = cookie;
1241 if (!(opt->arg || real->arg)
1242 && !((opt->flags | real->flags) & OPTION_NO_USAGE))
1243 *(*snao_end)++ = opt->key;
1244 return 0;
1247 /* If OPT is a short option with an arg, output a usage entry for it to the
1248 stream pointed at by COOKIE. */
1249 static int
1250 usage_argful_short_opt (const struct argp_option *opt,
1251 const struct argp_option *real,
1252 const char *domain, void *cookie)
1254 argp_fmtstream_t stream = cookie;
1255 const char *arg = opt->arg;
1256 int flags = opt->flags | real->flags;
1258 if (! arg)
1259 arg = real->arg;
1261 if (arg && !(flags & OPTION_NO_USAGE))
1263 arg = dgettext (domain, arg);
1265 if (flags & OPTION_ARG_OPTIONAL)
1266 __argp_fmtstream_printf (stream, " [-%c[%s]]", opt->key, arg);
1267 else
1269 /* Manually do line wrapping so that it (probably) won't
1270 get wrapped at the embedded space. */
1271 space (stream, 6 + strlen (arg));
1272 __argp_fmtstream_printf (stream, "[-%c %s]", opt->key, arg);
1276 return 0;
1279 /* Output a usage entry for the long option opt to the stream pointed at by
1280 COOKIE. */
1281 static int
1282 usage_long_opt (const struct argp_option *opt,
1283 const struct argp_option *real,
1284 const char *domain, void *cookie)
1286 argp_fmtstream_t stream = cookie;
1287 const char *arg = opt->arg;
1288 int flags = opt->flags | real->flags;
1290 if (! arg)
1291 arg = real->arg;
1293 if (! (flags & OPTION_NO_USAGE))
1295 if (arg)
1297 arg = dgettext (domain, arg);
1298 if (flags & OPTION_ARG_OPTIONAL)
1299 __argp_fmtstream_printf (stream, " [--%s[=%s]]", opt->name, arg);
1300 else
1301 __argp_fmtstream_printf (stream, " [--%s=%s]", opt->name, arg);
1303 else
1304 __argp_fmtstream_printf (stream, " [--%s]", opt->name);
1307 return 0;
1310 /* Print a short usage description for the arguments in HOL to STREAM. */
1311 static void
1312 hol_usage (struct hol *hol, argp_fmtstream_t stream)
1314 if (hol->num_entries > 0)
1316 unsigned nentries;
1317 struct hol_entry *entry;
1318 char *short_no_arg_opts = alloca (strlen (hol->short_options) + 1);
1319 char *snao_end = short_no_arg_opts;
1321 /* First we put a list of short options without arguments. */
1322 for (entry = hol->entries, nentries = hol->num_entries
1323 ; nentries > 0
1324 ; entry++, nentries--)
1325 hol_entry_short_iterate (entry, add_argless_short_opt,
1326 entry->argp->argp_domain, &snao_end);
1327 if (snao_end > short_no_arg_opts)
1329 *snao_end++ = 0;
1330 __argp_fmtstream_printf (stream, " [-%s]", short_no_arg_opts);
1333 /* Now a list of short options *with* arguments. */
1334 for (entry = hol->entries, nentries = hol->num_entries
1335 ; nentries > 0
1336 ; entry++, nentries--)
1337 hol_entry_short_iterate (entry, usage_argful_short_opt,
1338 entry->argp->argp_domain, stream);
1340 /* Finally, a list of long options (whew!). */
1341 for (entry = hol->entries, nentries = hol->num_entries
1342 ; nentries > 0
1343 ; entry++, nentries--)
1344 hol_entry_long_iterate (entry, usage_long_opt,
1345 entry->argp->argp_domain, stream);
1349 /* Make a HOL containing all levels of options in ARGP. CLUSTER is the
1350 cluster in which ARGP's entries should be clustered, or 0. */
1351 static struct hol *
1352 argp_hol (const struct argp *argp, struct hol_cluster *cluster)
1354 const struct argp_child *child = argp->children;
1355 struct hol *hol = make_hol (argp, cluster);
1356 if (child)
1357 while (child->argp)
1359 struct hol_cluster *child_cluster =
1360 ((child->group || child->header)
1361 /* Put CHILD->argp within its own cluster. */
1362 ? hol_add_cluster (hol, child->group, child->header,
1363 child - argp->children, cluster, argp)
1364 /* Just merge it into the parent's cluster. */
1365 : cluster);
1366 hol_append (hol, argp_hol (child->argp, child_cluster)) ;
1367 child++;
1369 return hol;
1372 /* Calculate how many different levels with alternative args strings exist in
1373 ARGP. */
1374 static size_t
1375 argp_args_levels (const struct argp *argp)
1377 size_t levels = 0;
1378 const struct argp_child *child = argp->children;
1380 if (argp->args_doc && strchr (argp->args_doc, '\n'))
1381 levels++;
1383 if (child)
1384 while (child->argp)
1385 levels += argp_args_levels ((child++)->argp);
1387 return levels;
1390 /* Print all the non-option args documented in ARGP to STREAM. Any output is
1391 preceded by a space. LEVELS is a pointer to a byte vector the length
1392 returned by argp_args_levels; it should be initialized to zero, and
1393 updated by this routine for the next call if ADVANCE is true. True is
1394 returned as long as there are more patterns to output. */
1395 static int
1396 argp_args_usage (const struct argp *argp, const struct argp_state *state,
1397 char **levels, int advance, argp_fmtstream_t stream)
1399 char *our_level = *levels;
1400 int multiple = 0;
1401 const struct argp_child *child = argp->children;
1402 const char *tdoc = dgettext (argp->argp_domain, argp->args_doc), *nl = 0;
1403 const char *fdoc = filter_doc (tdoc, ARGP_KEY_HELP_ARGS_DOC, argp, state);
1405 if (fdoc)
1407 const char *cp = fdoc;
1408 nl = __strchrnul (cp, '\n');
1409 if (*nl != '\0')
1410 /* This is a `multi-level' args doc; advance to the correct position
1411 as determined by our state in LEVELS, and update LEVELS. */
1413 int i;
1414 multiple = 1;
1415 for (i = 0; i < *our_level; i++)
1416 cp = nl + 1, nl = __strchrnul (cp, '\n');
1417 (*levels)++;
1420 /* Manually do line wrapping so that it (probably) won't get wrapped at
1421 any embedded spaces. */
1422 space (stream, 1 + nl - cp);
1424 __argp_fmtstream_write (stream, cp, nl - cp);
1426 if (fdoc && fdoc != tdoc)
1427 free ((char *)fdoc); /* Free user's modified doc string. */
1429 if (child)
1430 while (child->argp)
1431 advance = !argp_args_usage ((child++)->argp, state, levels, advance, stream);
1433 if (advance && multiple)
1435 /* Need to increment our level. */
1436 if (*nl)
1437 /* There's more we can do here. */
1439 (*our_level)++;
1440 advance = 0; /* Our parent shouldn't advance also. */
1442 else if (*our_level > 0)
1443 /* We had multiple levels, but used them up; reset to zero. */
1444 *our_level = 0;
1447 return !advance;
1450 /* Print the documentation for ARGP to STREAM; if POST is false, then
1451 everything preceeding a `\v' character in the documentation strings (or
1452 the whole string, for those with none) is printed, otherwise, everything
1453 following the `\v' character (nothing for strings without). Each separate
1454 bit of documentation is separated a blank line, and if PRE_BLANK is true,
1455 then the first is as well. If FIRST_ONLY is true, only the first
1456 occurrence is output. Returns true if anything was output. */
1457 static int
1458 argp_doc (const struct argp *argp, const struct argp_state *state,
1459 int post, int pre_blank, int first_only,
1460 argp_fmtstream_t stream)
1462 const char *text;
1463 const char *inp_text;
1464 void *input = 0;
1465 int anything = 0;
1466 size_t inp_text_limit = 0;
1467 const char *doc = dgettext (argp->argp_domain, argp->doc);
1468 const struct argp_child *child = argp->children;
1470 if (doc)
1472 char *vt = strchr (doc, '\v');
1473 inp_text = post ? (vt ? vt + 1 : 0) : doc;
1474 inp_text_limit = (!post && vt) ? (vt - doc) : 0;
1476 else
1477 inp_text = 0;
1479 if (argp->help_filter)
1480 /* We have to filter the doc strings. */
1482 if (inp_text_limit)
1483 /* Copy INP_TEXT so that it's nul-terminated. */
1484 inp_text = __strndup (inp_text, inp_text_limit);
1485 input = __argp_input (argp, state);
1486 text =
1487 (*argp->help_filter) (post
1488 ? ARGP_KEY_HELP_POST_DOC
1489 : ARGP_KEY_HELP_PRE_DOC,
1490 inp_text, input);
1492 else
1493 text = (const char *) inp_text;
1495 if (text)
1497 if (pre_blank)
1498 __argp_fmtstream_putc (stream, '\n');
1500 if (text == inp_text && inp_text_limit)
1501 __argp_fmtstream_write (stream, inp_text, inp_text_limit);
1502 else
1503 __argp_fmtstream_puts (stream, text);
1505 if (__argp_fmtstream_point (stream) > __argp_fmtstream_lmargin (stream))
1506 __argp_fmtstream_putc (stream, '\n');
1508 anything = 1;
1511 if (text && text != inp_text)
1512 free ((char *) text); /* Free TEXT returned from the help filter. */
1513 if (inp_text && inp_text_limit && argp->help_filter)
1514 free ((char *) inp_text); /* We copied INP_TEXT, so free it now. */
1516 if (post && argp->help_filter)
1517 /* Now see if we have to output a ARGP_KEY_HELP_EXTRA text. */
1519 text = (*argp->help_filter) (ARGP_KEY_HELP_EXTRA, 0, input);
1520 if (text)
1522 if (anything || pre_blank)
1523 __argp_fmtstream_putc (stream, '\n');
1524 __argp_fmtstream_puts (stream, text);
1525 free ((char *) text);
1526 if (__argp_fmtstream_point (stream)
1527 > __argp_fmtstream_lmargin (stream))
1528 __argp_fmtstream_putc (stream, '\n');
1529 anything = 1;
1533 if (child)
1534 while (child->argp && !(first_only && anything))
1535 anything |=
1536 argp_doc ((child++)->argp, state,
1537 post, anything || pre_blank, first_only,
1538 stream);
1540 return anything;
1543 /* Output a usage message for ARGP to STREAM. If called from
1544 argp_state_help, STATE is the relevent parsing state. FLAGS are from the
1545 set ARGP_HELP_*. NAME is what to use wherever a `program name' is
1546 needed. */
1547 static void
1548 _help (const struct argp *argp, const struct argp_state *state, FILE *stream,
1549 unsigned flags, char *name)
1551 int anything = 0; /* Whether we've output anything. */
1552 struct hol *hol = 0;
1553 argp_fmtstream_t fs;
1555 if (! stream)
1556 return;
1558 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1559 __flockfile (stream);
1560 #endif
1562 fill_in_uparams (state);
1564 fs = __argp_make_fmtstream (stream, 0, uparams.rmargin, 0);
1565 if (! fs)
1567 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1568 __funlockfile (stream);
1569 #endif
1570 return;
1573 if (flags & (ARGP_HELP_USAGE | ARGP_HELP_SHORT_USAGE | ARGP_HELP_LONG))
1575 hol = argp_hol (argp, 0);
1577 /* If present, these options always come last. */
1578 hol_set_group (hol, "help", -1);
1579 hol_set_group (hol, "version", -1);
1581 hol_sort (hol);
1584 if (flags & (ARGP_HELP_USAGE | ARGP_HELP_SHORT_USAGE))
1585 /* Print a short `Usage:' message. */
1587 int first_pattern = 1, more_patterns;
1588 size_t num_pattern_levels = argp_args_levels (argp);
1589 char *pattern_levels = alloca (num_pattern_levels);
1591 memset (pattern_levels, 0, num_pattern_levels);
1595 int old_lm;
1596 int old_wm = __argp_fmtstream_set_wmargin (fs, uparams.usage_indent);
1597 char *levels = pattern_levels;
1599 if (first_pattern)
1600 __argp_fmtstream_printf (fs, "%s %s",
1601 dgettext (argp->argp_domain, "Usage:"),
1602 name);
1603 else
1604 __argp_fmtstream_printf (fs, "%s %s",
1605 dgettext (argp->argp_domain, " or: "),
1606 name);
1608 /* We set the lmargin as well as the wmargin, because hol_usage
1609 manually wraps options with newline to avoid annoying breaks. */
1610 old_lm = __argp_fmtstream_set_lmargin (fs, uparams.usage_indent);
1612 if (flags & ARGP_HELP_SHORT_USAGE)
1613 /* Just show where the options go. */
1615 if (hol->num_entries > 0)
1616 __argp_fmtstream_puts (fs, dgettext (argp->argp_domain,
1617 " [OPTION...]"));
1619 else
1620 /* Actually print the options. */
1622 hol_usage (hol, fs);
1623 flags |= ARGP_HELP_SHORT_USAGE; /* But only do so once. */
1626 more_patterns = argp_args_usage (argp, state, &levels, 1, fs);
1628 __argp_fmtstream_set_wmargin (fs, old_wm);
1629 __argp_fmtstream_set_lmargin (fs, old_lm);
1631 __argp_fmtstream_putc (fs, '\n');
1632 anything = 1;
1634 first_pattern = 0;
1636 while (more_patterns);
1639 if (flags & ARGP_HELP_PRE_DOC)
1640 anything |= argp_doc (argp, state, 0, 0, 1, fs);
1642 if (flags & ARGP_HELP_SEE)
1644 __argp_fmtstream_printf (fs, dgettext (argp->argp_domain, "\
1645 Try `%s --help' or `%s --usage' for more information.\n"),
1646 name, name);
1647 anything = 1;
1650 if (flags & ARGP_HELP_LONG)
1651 /* Print a long, detailed help message. */
1653 /* Print info about all the options. */
1654 if (hol->num_entries > 0)
1656 if (anything)
1657 __argp_fmtstream_putc (fs, '\n');
1658 hol_help (hol, state, fs);
1659 anything = 1;
1663 if (flags & ARGP_HELP_POST_DOC)
1664 /* Print any documentation strings at the end. */
1665 anything |= argp_doc (argp, state, 1, anything, 0, fs);
1667 if ((flags & ARGP_HELP_BUG_ADDR) && argp_program_bug_address)
1669 if (anything)
1670 __argp_fmtstream_putc (fs, '\n');
1671 __argp_fmtstream_printf (fs, dgettext (argp->argp_domain,
1672 "Report bugs to %s.\n"),
1673 argp_program_bug_address);
1674 anything = 1;
1677 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1678 __funlockfile (stream);
1679 #endif
1681 if (hol)
1682 hol_free (hol);
1684 __argp_fmtstream_free (fs);
1687 /* Output a usage message for ARGP to STREAM. FLAGS are from the set
1688 ARGP_HELP_*. NAME is what to use wherever a `program name' is needed. */
1689 void __argp_help (const struct argp *argp, FILE *stream,
1690 unsigned flags, char *name)
1692 _help (argp, 0, stream, flags, name);
1694 #ifdef weak_alias
1695 weak_alias (__argp_help, argp_help)
1696 #endif
1698 #ifndef _LIBC
1699 char *__argp_basename (char *name)
1701 char *short_name = strrchr (name, '/');
1702 return short_name ? short_name + 1 : name;
1705 char *
1706 __argp_short_program_name (void)
1708 # if HAVE_DECL_PROGRAM_INVOCATION_SHORT_NAME
1709 return program_invocation_short_name;
1710 # elif HAVE_DECL_PROGRAM_INVOCATION_NAME
1711 return __argp_basename (program_invocation_name);
1712 # else
1713 /* FIXME: What now? Miles suggests that it is better to use NULL,
1714 but currently the value is passed on directly to fputs_unlocked,
1715 so that requires more changes. */
1716 # if __GNUC__
1717 # warning No reasonable value to return
1718 # endif /* __GNUC__ */
1719 return "";
1720 # endif
1722 #endif
1724 /* Output, if appropriate, a usage message for STATE to STREAM. FLAGS are
1725 from the set ARGP_HELP_*. */
1726 void
1727 __argp_state_help (const struct argp_state *state, FILE *stream, unsigned flags)
1729 if ((!state || ! (state->flags & ARGP_NO_ERRS)) && stream)
1731 if (state && (state->flags & ARGP_LONG_ONLY))
1732 flags |= ARGP_HELP_LONG_ONLY;
1734 _help (state ? state->root_argp : 0, state, stream, flags,
1735 state ? state->name : __argp_short_program_name ());
1737 if (!state || ! (state->flags & ARGP_NO_EXIT))
1739 if (flags & ARGP_HELP_EXIT_ERR)
1740 exit (argp_err_exit_status);
1741 if (flags & ARGP_HELP_EXIT_OK)
1742 exit (0);
1746 #ifdef weak_alias
1747 weak_alias (__argp_state_help, argp_state_help)
1748 #endif
1750 /* If appropriate, print the printf string FMT and following args, preceded
1751 by the program name and `:', to stderr, and followed by a `Try ... --help'
1752 message, then exit (1). */
1753 void
1754 __argp_error (const struct argp_state *state, const char *fmt, ...)
1756 if (!state || !(state->flags & ARGP_NO_ERRS))
1758 FILE *stream = state ? state->err_stream : stderr;
1760 if (stream)
1762 va_list ap;
1764 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1765 __flockfile (stream);
1766 #endif
1768 va_start (ap, fmt);
1770 #ifdef _LIBC
1771 char *buf;
1773 if (_IO_vasprintf (&buf, fmt, ap) < 0)
1774 buf = NULL;
1776 __fxprintf (stream, "%s: %s\n",
1777 state ? state->name : __argp_short_program_name (), buf);
1779 free (buf);
1780 #else
1781 fputs_unlocked (state ? state->name : __argp_short_program_name (),
1782 stream);
1783 putc_unlocked (':', stream);
1784 putc_unlocked (' ', stream);
1786 vfprintf (stream, fmt, ap);
1788 putc_unlocked ('\n', stream);
1789 #endif
1791 __argp_state_help (state, stream, ARGP_HELP_STD_ERR);
1793 va_end (ap);
1795 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1796 __funlockfile (stream);
1797 #endif
1801 #ifdef weak_alias
1802 weak_alias (__argp_error, argp_error)
1803 #endif
1805 /* Similar to the standard gnu error-reporting function error(), but will
1806 respect the ARGP_NO_EXIT and ARGP_NO_ERRS flags in STATE, and will print
1807 to STATE->err_stream. This is useful for argument parsing code that is
1808 shared between program startup (when exiting is desired) and runtime
1809 option parsing (when typically an error code is returned instead). The
1810 difference between this function and argp_error is that the latter is for
1811 *parsing errors*, and the former is for other problems that occur during
1812 parsing but don't reflect a (syntactic) problem with the input. */
1813 void
1814 __argp_failure (const struct argp_state *state, int status, int errnum,
1815 const char *fmt, ...)
1817 if (!state || !(state->flags & ARGP_NO_ERRS))
1819 FILE *stream = state ? state->err_stream : stderr;
1821 if (stream)
1823 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1824 __flockfile (stream);
1825 #endif
1827 #ifdef _LIBC
1828 __fxprintf (stream, "%s",
1829 state ? state->name : __argp_short_program_name ());
1830 #else
1831 fputs_unlocked (state ? state->name : __argp_short_program_name (),
1832 stream);
1833 #endif
1835 if (fmt)
1837 va_list ap;
1839 va_start (ap, fmt);
1840 #ifdef _LIBC
1841 char *buf;
1843 if (_IO_vasprintf (&buf, fmt, ap) < 0)
1844 buf = NULL;
1846 __fxprintf (stream, ": %s", buf);
1848 free (buf);
1849 #else
1850 putc_unlocked (':', stream);
1851 putc_unlocked (' ', stream);
1853 vfprintf (stream, fmt, ap);
1854 #endif
1856 va_end (ap);
1859 if (errnum)
1861 char buf[200];
1863 #ifdef _LIBC
1864 __fxprintf (stream, ": %s",
1865 __strerror_r (errnum, buf, sizeof (buf)));
1866 #else
1867 putc_unlocked (':', stream);
1868 putc_unlocked (' ', stream);
1869 # ifdef HAVE_STRERROR_R
1870 fputs (__strerror_r (errnum, buf, sizeof (buf)), stream);
1871 # else
1872 fputs (strerror (errnum), stream);
1873 # endif
1874 #endif
1877 #ifdef USE_IN_LIBIO
1878 if (_IO_fwide (stream, 0) > 0)
1879 putwc_unlocked (L'\n', stream);
1880 else
1881 #endif
1882 putc_unlocked ('\n', stream);
1884 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1885 __funlockfile (stream);
1886 #endif
1888 if (status && (!state || !(state->flags & ARGP_NO_EXIT)))
1889 exit (status);
1893 #ifdef weak_alias
1894 weak_alias (__argp_failure, argp_failure)
1895 #endif