Updated gnulib and added hash-pjw-bare
[gnutls.git] / gl / argp-help.c
blobc46703c03b5b4ea07f7ce9ab33bb71f5d97fc068
1 /* Hierarchical argument parsing help output
2 Copyright (C) 1995-2005, 2007, 2009-2012 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 This program is free software: you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 3 of the License, or
9 (at your option) any later version.
11 This program 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
14 GNU General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with this program. If not, see <http://www.gnu.org/licenses/>. */
19 #ifndef _GNU_SOURCE
20 # define _GNU_SOURCE 1
21 #endif
23 #ifdef HAVE_CONFIG_H
24 # include <config.h>
25 #endif
27 #include <alloca.h>
28 #include <errno.h>
29 #include <stddef.h>
30 #include <stdlib.h>
31 #include <string.h>
32 #include <strings.h>
33 #include <assert.h>
34 #include <stdarg.h>
35 #include <ctype.h>
36 #include <limits.h>
37 #ifdef USE_IN_LIBIO
38 # include <wchar.h>
39 #endif
41 #ifdef _LIBC
42 # include <libintl.h>
43 # undef dgettext
44 # define dgettext(domain, msgid) \
45 INTUSE(__dcgettext) (domain, msgid, LC_MESSAGES)
46 #else
47 # include "gettext.h"
48 #endif
50 #include "argp.h"
51 #include "argp-fmtstream.h"
52 #include "argp-namefrob.h"
54 #ifndef SIZE_MAX
55 # define SIZE_MAX ((size_t) -1)
56 #endif
58 /* User-selectable (using an environment variable) formatting parameters.
60 These may be specified in an environment variable called 'ARGP_HELP_FMT',
61 with a contents like: VAR1=VAL1,VAR2=VAL2,BOOLVAR2,no-BOOLVAR2
62 Where VALn must be a positive integer. The list of variables is in the
63 UPARAM_NAMES vector, below. */
65 /* Default parameters. */
66 #define DUP_ARGS 0 /* True if option argument can be duplicated. */
67 #define DUP_ARGS_NOTE 1 /* True to print a note about duplicate args. */
68 #define SHORT_OPT_COL 2 /* column in which short options start */
69 #define LONG_OPT_COL 6 /* column in which long options start */
70 #define DOC_OPT_COL 2 /* column in which doc options start */
71 #define OPT_DOC_COL 29 /* column in which option text starts */
72 #define HEADER_COL 1 /* column in which group headers are printed */
73 #define USAGE_INDENT 12 /* indentation of wrapped usage lines */
74 #define RMARGIN 79 /* right margin used for wrapping */
76 /* User-selectable (using an environment variable) formatting parameters.
77 They must all be of type 'int' for the parsing code to work. */
78 struct uparams
80 /* If true, arguments for an option are shown with both short and long
81 options, even when a given option has both, e.g. '-x ARG, --longx=ARG'.
82 If false, then if an option has both, the argument is only shown with
83 the long one, e.g., '-x, --longx=ARG', and a message indicating that
84 this really means both is printed below the options. */
85 int dup_args;
87 /* This is true if when DUP_ARGS is false, and some duplicate arguments have
88 been suppressed, an explanatory message should be printed. */
89 int dup_args_note;
91 /* Various output columns. */
92 int short_opt_col; /* column in which short options start */
93 int long_opt_col; /* column in which long options start */
94 int doc_opt_col; /* column in which doc options start */
95 int opt_doc_col; /* column in which option text starts */
96 int header_col; /* column in which group headers are printed */
97 int usage_indent; /* indentation of wrapped usage lines */
98 int rmargin; /* right margin used for wrapping */
100 int valid; /* True when the values in here are valid. */
103 /* This is a global variable, as user options are only ever read once. */
104 static struct uparams uparams = {
105 DUP_ARGS, DUP_ARGS_NOTE,
106 SHORT_OPT_COL, LONG_OPT_COL, DOC_OPT_COL, OPT_DOC_COL, HEADER_COL,
107 USAGE_INDENT, RMARGIN,
111 /* A particular uparam, and what the user name is. */
112 struct uparam_name
114 const char *name; /* User name. */
115 int is_bool; /* Whether it's 'boolean'. */
116 size_t uparams_offs; /* Location of the (int) field in UPARAMS. */
119 /* The name-field mappings we know about. */
120 static const struct uparam_name uparam_names[] =
122 { "dup-args", 1, offsetof (struct uparams, dup_args) },
123 { "dup-args-note", 1, offsetof (struct uparams, dup_args_note) },
124 { "short-opt-col", 0, offsetof (struct uparams, short_opt_col) },
125 { "long-opt-col", 0, offsetof (struct uparams, long_opt_col) },
126 { "doc-opt-col", 0, offsetof (struct uparams, doc_opt_col) },
127 { "opt-doc-col", 0, offsetof (struct uparams, opt_doc_col) },
128 { "header-col", 0, offsetof (struct uparams, header_col) },
129 { "usage-indent", 0, offsetof (struct uparams, usage_indent) },
130 { "rmargin", 0, offsetof (struct uparams, rmargin) },
131 { 0 }
134 static void
135 validate_uparams (const struct argp_state *state, struct uparams *upptr)
137 const struct uparam_name *up;
139 for (up = uparam_names; up->name; up++)
141 if (up->is_bool
142 || up->uparams_offs == offsetof (struct uparams, rmargin))
143 continue;
144 if (*(int *)((char *)upptr + up->uparams_offs) >= upptr->rmargin)
146 __argp_failure (state, 0, 0,
147 dgettext (state->root_argp->argp_domain,
149 ARGP_HELP_FMT: %s value is less than or equal to %s"),
150 "rmargin", up->name);
151 return;
154 uparams = *upptr;
155 uparams.valid = 1;
158 /* Read user options from the environment, and fill in UPARAMS appropriately. */
159 static void
160 fill_in_uparams (const struct argp_state *state)
162 const char *var = getenv ("ARGP_HELP_FMT");
163 struct uparams new_params = uparams;
165 #define SKIPWS(p) do { while (isspace ((unsigned char) *p)) p++; } while (0);
167 if (var)
169 /* Parse var. */
170 while (*var)
172 SKIPWS (var);
174 if (isalpha ((unsigned char) *var))
176 size_t var_len;
177 const struct uparam_name *un;
178 int unspec = 0, val = 0;
179 const char *arg = var;
181 while (isalnum ((unsigned char) *arg) || *arg == '-' || *arg == '_')
182 arg++;
183 var_len = arg - var;
185 SKIPWS (arg);
187 if (*arg == '\0' || *arg == ',')
188 unspec = 1;
189 else if (*arg == '=')
191 arg++;
192 SKIPWS (arg);
195 if (unspec)
197 if (var[0] == 'n' && var[1] == 'o' && var[2] == '-')
199 val = 0;
200 var += 3;
201 var_len -= 3;
203 else
204 val = 1;
206 else if (isdigit ((unsigned char) *arg))
208 val = atoi (arg);
209 while (isdigit ((unsigned char) *arg))
210 arg++;
211 SKIPWS (arg);
214 for (un = uparam_names; un->name; un++)
215 if (strlen (un->name) == var_len
216 && strncmp (var, un->name, var_len) == 0)
218 if (unspec && !un->is_bool)
219 __argp_failure (state, 0, 0,
220 dgettext (state->root_argp->argp_domain,
222 %.*s: ARGP_HELP_FMT parameter requires a value"),
223 (int) var_len, var);
224 else if (val < 0)
225 __argp_failure (state, 0, 0,
226 dgettext (state->root_argp->argp_domain,
228 %.*s: ARGP_HELP_FMT parameter must be positive"),
229 (int) var_len, var);
230 else
231 *(int *)((char *)&new_params + un->uparams_offs) = val;
232 break;
234 if (! un->name)
235 __argp_failure (state, 0, 0,
236 dgettext (state->root_argp->argp_domain, "\
237 %.*s: Unknown ARGP_HELP_FMT parameter"),
238 (int) var_len, var);
240 var = arg;
241 if (*var == ',')
242 var++;
244 else if (*var)
246 __argp_failure (state, 0, 0,
247 dgettext (state->root_argp->argp_domain,
248 "Garbage in ARGP_HELP_FMT: %s"), var);
249 break;
252 validate_uparams (state, &new_params);
256 /* Returns true if OPT hasn't been marked invisible. Visibility only affects
257 whether OPT is displayed or used in sorting, not option shadowing. */
258 #define ovisible(opt) (! ((opt)->flags & OPTION_HIDDEN))
260 /* Returns true if OPT is an alias for an earlier option. */
261 #define oalias(opt) ((opt)->flags & OPTION_ALIAS)
263 /* Returns true if OPT is a documentation-only entry. */
264 #define odoc(opt) ((opt)->flags & OPTION_DOC)
266 /* Returns true if OPT should not be translated */
267 #define onotrans(opt) ((opt)->flags & OPTION_NO_TRANS)
269 /* Returns true if OPT is the end-of-list marker for a list of options. */
270 #define oend(opt) __option_is_end (opt)
272 /* Returns true if OPT has a short option. */
273 #define oshort(opt) __option_is_short (opt)
276 The help format for a particular option is like:
278 -xARG, -yARG, --long1=ARG, --long2=ARG Documentation...
280 Where ARG will be omitted if there's no argument, for this option, or
281 will be surrounded by "[" and "]" appropriately if the argument is
282 optional. The documentation string is word-wrapped appropriately, and if
283 the list of options is long enough, it will be started on a separate line.
284 If there are no short options for a given option, the first long option is
285 indented slightly in a way that's supposed to make most long options appear
286 to be in a separate column.
288 For example, the following output (from ps):
290 -p PID, --pid=PID List the process PID
291 --pgrp=PGRP List processes in the process group PGRP
292 -P, -x, --no-parent Include processes without parents
293 -Q, --all-fields Don't elide unusable fields (normally if there's
294 some reason ps can't print a field for any
295 process, it's removed from the output entirely)
296 -r, --reverse, --gratuitously-long-reverse-option
297 Reverse the order of any sort
298 --session[=SID] Add the processes from the session SID (which
299 defaults to the sid of the current process)
301 Here are some more options:
302 -f ZOT, --foonly=ZOT Glork a foonly
303 -z, --zaza Snit a zar
305 -?, --help Give this help list
306 --usage Give a short usage message
307 -V, --version Print program version
309 The struct argp_option array for the above could look like:
312 {"pid", 'p', "PID", 0, "List the process PID"},
313 {"pgrp", OPT_PGRP, "PGRP", 0, "List processes in the process group PGRP"},
314 {"no-parent", 'P', 0, 0, "Include processes without parents"},
315 {0, 'x', 0, OPTION_ALIAS},
316 {"all-fields",'Q', 0, 0, "Don't elide unusable fields (normally"
317 " if there's some reason ps can't"
318 " print a field for any process, it's"
319 " removed from the output entirely)" },
320 {"reverse", 'r', 0, 0, "Reverse the order of any sort"},
321 {"gratuitously-long-reverse-option", 0, 0, OPTION_ALIAS},
322 {"session", OPT_SESS, "SID", OPTION_ARG_OPTIONAL,
323 "Add the processes from the session"
324 " SID (which defaults to the sid of"
325 " the current process)" },
327 {0,0,0,0, "Here are some more options:"},
328 {"foonly", 'f', "ZOT", 0, "Glork a foonly"},
329 {"zaza", 'z', 0, 0, "Snit a zar"},
334 Note that the last three options are automatically supplied by argp_parse,
335 unless you tell it not to with ARGP_NO_HELP.
339 /* Returns true if CH occurs between BEG and END. */
340 static int
341 find_char (char ch, char *beg, char *end)
343 while (beg < end)
344 if (*beg == ch)
345 return 1;
346 else
347 beg++;
348 return 0;
351 struct hol_cluster; /* fwd decl */
353 struct hol_entry
355 /* First option. */
356 const struct argp_option *opt;
357 /* Number of options (including aliases). */
358 unsigned num;
360 /* A pointers into the HOL's short_options field, to the first short option
361 letter for this entry. The order of the characters following this point
362 corresponds to the order of options pointed to by OPT, and there are at
363 most NUM. A short option recorded in an option following OPT is only
364 valid if it occurs in the right place in SHORT_OPTIONS (otherwise it's
365 probably been shadowed by some other entry). */
366 char *short_options;
368 /* Entries are sorted by their group first, in the order:
369 1, 2, ..., n, 0, -m, ..., -2, -1
370 and then alphabetically within each group. The default is 0. */
371 int group;
373 /* The cluster of options this entry belongs to, or 0 if none. */
374 struct hol_cluster *cluster;
376 /* The argp from which this option came. */
377 const struct argp *argp;
379 /* Position in the array */
380 unsigned ord;
383 /* A cluster of entries to reflect the argp tree structure. */
384 struct hol_cluster
386 /* A descriptive header printed before options in this cluster. */
387 const char *header;
389 /* Used to order clusters within the same group with the same parent,
390 according to the order in which they occurred in the parent argp's child
391 list. */
392 int index;
394 /* How to sort this cluster with respect to options and other clusters at the
395 same depth (clusters always follow options in the same group). */
396 int group;
398 /* The cluster to which this cluster belongs, or 0 if it's at the base
399 level. */
400 struct hol_cluster *parent;
402 /* The argp from which this cluster is (eventually) derived. */
403 const struct argp *argp;
405 /* The distance this cluster is from the root. */
406 int depth;
408 /* Clusters in a given hol are kept in a linked list, to make freeing them
409 possible. */
410 struct hol_cluster *next;
413 /* A list of options for help. */
414 struct hol
416 /* An array of hol_entry's. */
417 struct hol_entry *entries;
418 /* The number of entries in this hol. If this field is zero, the others
419 are undefined. */
420 unsigned num_entries;
422 /* A string containing all short options in this HOL. Each entry contains
423 pointers into this string, so the order can't be messed with blindly. */
424 char *short_options;
426 /* Clusters of entries in this hol. */
427 struct hol_cluster *clusters;
430 /* Create a struct hol from the options in ARGP. CLUSTER is the
431 hol_cluster in which these entries occur, or 0, if at the root. */
432 static struct hol *
433 make_hol (const struct argp *argp, struct hol_cluster *cluster)
435 char *so;
436 const struct argp_option *o;
437 const struct argp_option *opts = argp->options;
438 struct hol_entry *entry;
439 unsigned num_short_options = 0;
440 struct hol *hol = malloc (sizeof (struct hol));
442 assert (hol);
444 hol->num_entries = 0;
445 hol->clusters = 0;
447 if (opts)
449 int cur_group = 0;
451 /* The first option must not be an alias. */
452 assert (! oalias (opts));
454 /* Calculate the space needed. */
455 for (o = opts; ! oend (o); o++)
457 if (! oalias (o))
458 hol->num_entries++;
459 if (oshort (o))
460 num_short_options++; /* This is an upper bound. */
463 hol->entries = malloc (sizeof (struct hol_entry) * hol->num_entries);
464 hol->short_options = malloc (num_short_options + 1);
466 assert (hol->entries && hol->short_options);
467 if (SIZE_MAX <= UINT_MAX)
468 assert (hol->num_entries <= SIZE_MAX / sizeof (struct hol_entry));
470 /* Fill in the entries. */
471 so = hol->short_options;
472 for (o = opts, entry = hol->entries; ! oend (o); entry++)
474 entry->opt = o;
475 entry->num = 0;
476 entry->short_options = so;
477 entry->group = cur_group =
478 o->group
479 ? o->group
480 : ((!o->name && !o->key)
481 ? cur_group + 1
482 : cur_group);
483 entry->cluster = cluster;
484 entry->argp = argp;
488 entry->num++;
489 if (oshort (o) && ! find_char (o->key, hol->short_options, so))
490 /* O has a valid short option which hasn't already been used.*/
491 *so++ = o->key;
492 o++;
494 while (! oend (o) && oalias (o));
496 *so = '\0'; /* null terminated so we can find the length */
499 return hol;
502 /* Add a new cluster to HOL, with the given GROUP and HEADER (taken from the
503 associated argp child list entry), INDEX, and PARENT, and return a pointer
504 to it. ARGP is the argp that this cluster results from. */
505 static struct hol_cluster *
506 hol_add_cluster (struct hol *hol, int group, const char *header, int index,
507 struct hol_cluster *parent, const struct argp *argp)
509 struct hol_cluster *cl = malloc (sizeof (struct hol_cluster));
510 if (cl)
512 cl->group = group;
513 cl->header = header;
515 cl->index = index;
516 cl->parent = parent;
517 cl->argp = argp;
518 cl->depth = parent ? parent->depth + 1 : 0;
520 cl->next = hol->clusters;
521 hol->clusters = cl;
523 return cl;
526 /* Free HOL and any resources it uses. */
527 static void
528 hol_free (struct hol *hol)
530 struct hol_cluster *cl = hol->clusters;
532 while (cl)
534 struct hol_cluster *next = cl->next;
535 free (cl);
536 cl = next;
539 if (hol->num_entries > 0)
541 free (hol->entries);
542 free (hol->short_options);
545 free (hol);
548 static int
549 hol_entry_short_iterate (const struct hol_entry *entry,
550 int (*func)(const struct argp_option *opt,
551 const struct argp_option *real,
552 const char *domain, void *cookie),
553 const char *domain, void *cookie)
555 unsigned nopts;
556 int val = 0;
557 const struct argp_option *opt, *real = entry->opt;
558 char *so = entry->short_options;
560 for (opt = real, nopts = entry->num; nopts > 0 && !val; opt++, nopts--)
561 if (oshort (opt) && *so == opt->key)
563 if (!oalias (opt))
564 real = opt;
565 if (ovisible (opt))
566 val = (*func)(opt, real, domain, cookie);
567 so++;
570 return val;
573 static inline int
574 #if __GNUC__ >= 3
575 __attribute__ ((always_inline))
576 #endif
577 hol_entry_long_iterate (const struct hol_entry *entry,
578 int (*func)(const struct argp_option *opt,
579 const struct argp_option *real,
580 const char *domain, void *cookie),
581 const char *domain, void *cookie)
583 unsigned nopts;
584 int val = 0;
585 const struct argp_option *opt, *real = entry->opt;
587 for (opt = real, nopts = entry->num; nopts > 0 && !val; opt++, nopts--)
588 if (opt->name)
590 if (!oalias (opt))
591 real = opt;
592 if (ovisible (opt))
593 val = (*func)(opt, real, domain, cookie);
596 return val;
599 /* Iterator that returns true for the first short option. */
600 static int
601 until_short (const struct argp_option *opt, const struct argp_option *real,
602 const char *domain, void *cookie)
604 return oshort (opt) ? opt->key : 0;
607 /* Returns the first valid short option in ENTRY, or 0 if there is none. */
608 static char
609 hol_entry_first_short (const struct hol_entry *entry)
611 return hol_entry_short_iterate (entry, until_short,
612 entry->argp->argp_domain, 0);
615 /* Returns the first valid long option in ENTRY, or 0 if there is none. */
616 static const char *
617 hol_entry_first_long (const struct hol_entry *entry)
619 const struct argp_option *opt;
620 unsigned num;
621 for (opt = entry->opt, num = entry->num; num > 0; opt++, num--)
622 if (opt->name && ovisible (opt))
623 return opt->name;
624 return 0;
627 /* Returns the entry in HOL with the long option name NAME, or 0 if there is
628 none. */
629 static struct hol_entry *
630 hol_find_entry (struct hol *hol, const char *name)
632 struct hol_entry *entry = hol->entries;
633 unsigned num_entries = hol->num_entries;
635 while (num_entries-- > 0)
637 const struct argp_option *opt = entry->opt;
638 unsigned num_opts = entry->num;
640 while (num_opts-- > 0)
641 if (opt->name && ovisible (opt) && strcmp (opt->name, name) == 0)
642 return entry;
643 else
644 opt++;
646 entry++;
649 return 0;
652 /* If an entry with the long option NAME occurs in HOL, set it's special
653 sort position to GROUP. */
654 static void
655 hol_set_group (struct hol *hol, const char *name, int group)
657 struct hol_entry *entry = hol_find_entry (hol, name);
658 if (entry)
659 entry->group = group;
662 /* Order by group: 0, 1, 2, ..., n, -m, ..., -2, -1.
663 EQ is what to return if GROUP1 and GROUP2 are the same. */
664 static int
665 group_cmp (int group1, int group2, int eq)
667 if (group1 == group2)
668 return eq;
669 else if ((group1 < 0 && group2 < 0) || (group1 >= 0 && group2 >= 0))
670 return group1 - group2;
671 else
672 return group2 - group1;
675 /* Compare clusters CL1 & CL2 by the order that they should appear in
676 output. */
677 static int
678 hol_cluster_cmp (const struct hol_cluster *cl1, const struct hol_cluster *cl2)
680 /* If one cluster is deeper than the other, use its ancestor at the same
681 level, so that finding the common ancestor is straightforward.
683 clN->depth > 0 means that clN->parent != NULL (see hol_add_cluster) */
684 while (cl1->depth > cl2->depth)
685 cl1 = cl1->parent;
686 while (cl2->depth > cl1->depth)
687 cl2 = cl2->parent;
689 /* Now reduce both clusters to their ancestors at the point where both have
690 a common parent; these can be directly compared. */
691 while (cl1->parent != cl2->parent)
692 cl1 = cl1->parent, cl2 = cl2->parent;
694 return group_cmp (cl1->group, cl2->group, cl2->index - cl1->index);
697 /* Return the ancestor of CL that's just below the root (i.e., has a parent
698 of 0). */
699 static struct hol_cluster *
700 hol_cluster_base (struct hol_cluster *cl)
702 while (cl->parent)
703 cl = cl->parent;
704 return cl;
707 /* Return true if CL1 is a child of CL2. */
708 static int
709 hol_cluster_is_child (const struct hol_cluster *cl1,
710 const struct hol_cluster *cl2)
712 while (cl1 && cl1 != cl2)
713 cl1 = cl1->parent;
714 return cl1 == cl2;
717 /* Given the name of an OPTION_DOC option, modifies NAME to start at the tail
718 that should be used for comparisons, and returns true iff it should be
719 treated as a non-option. */
720 static int
721 canon_doc_option (const char **name)
723 int non_opt;
725 if (!*name)
726 non_opt = 1;
727 else
729 /* Skip initial whitespace. */
730 while (isspace ((unsigned char) **name))
731 (*name)++;
732 /* Decide whether this looks like an option (leading '-') or not. */
733 non_opt = (**name != '-');
734 /* Skip until part of name used for sorting. */
735 while (**name && !isalnum ((unsigned char) **name))
736 (*name)++;
738 return non_opt;
741 #define HOL_ENTRY_PTRCMP(a,b) ((a)->ord < (b)->ord ? -1 : 1)
743 /* Order ENTRY1 & ENTRY2 by the order which they should appear in a help
744 listing. */
745 static int
746 hol_entry_cmp (const struct hol_entry *entry1,
747 const struct hol_entry *entry2)
749 /* The group numbers by which the entries should be ordered; if either is
750 in a cluster, then this is just the group within the cluster. */
751 int group1 = entry1->group, group2 = entry2->group;
752 int rc;
754 if (entry1->cluster != entry2->cluster)
756 /* The entries are not within the same cluster, so we can't compare them
757 directly, we have to use the appropriate clustering level too. */
758 if (! entry1->cluster)
759 /* ENTRY1 is at the "base level", not in a cluster, so we have to
760 compare it's group number with that of the base cluster in which
761 ENTRY2 resides. Note that if they're in the same group, the
762 clustered option always comes laster. */
763 return group_cmp (group1, hol_cluster_base (entry2->cluster)->group, -1);
764 else if (! entry2->cluster)
765 /* Likewise, but ENTRY2's not in a cluster. */
766 return group_cmp (hol_cluster_base (entry1->cluster)->group, group2, 1);
767 else
768 /* Both entries are in clusters, we can just compare the clusters. */
769 return (rc = hol_cluster_cmp (entry1->cluster, entry2->cluster)) ?
770 rc : HOL_ENTRY_PTRCMP (entry1, entry2);
772 else if (group1 == group2)
773 /* The entries are both in the same cluster and group, so compare them
774 alphabetically. */
776 int short1 = hol_entry_first_short (entry1);
777 int short2 = hol_entry_first_short (entry2);
778 int doc1 = odoc (entry1->opt);
779 int doc2 = odoc (entry2->opt);
780 const char *long1 = hol_entry_first_long (entry1);
781 const char *long2 = hol_entry_first_long (entry2);
783 if (doc1)
784 doc1 = canon_doc_option (&long1);
785 if (doc2)
786 doc2 = canon_doc_option (&long2);
788 if (doc1 != doc2)
789 /* "documentation" options always follow normal options (or
790 documentation options that *look* like normal options). */
791 return doc1 - doc2;
792 else if (!short1 && !short2 && long1 && long2)
793 /* Only long options. */
794 return (rc = __strcasecmp (long1, long2)) ?
795 rc : HOL_ENTRY_PTRCMP (entry1, entry2);
796 else
797 /* Compare short/short, long/short, short/long, using the first
798 character of long options. Entries without *any* valid
799 options (such as options with OPTION_HIDDEN set) will be put
800 first, but as they're not displayed, it doesn't matter where
801 they are. */
803 unsigned char first1 = short1 ? short1 : long1 ? *long1 : 0;
804 unsigned char first2 = short2 ? short2 : long2 ? *long2 : 0;
805 /* Use tolower, not _tolower, since only the former is
806 guaranteed to work on something already lower case. */
807 int lower_cmp = tolower (first1) - tolower (first2);
808 /* Compare ignoring case, except when the options are both the
809 same letter, in which case lower-case always comes first. */
810 return lower_cmp ? lower_cmp :
811 (rc = first2 - first1) ?
812 rc : HOL_ENTRY_PTRCMP (entry1, entry2);
815 else
816 /* Within the same cluster, but not the same group, so just compare
817 groups. */
818 return group_cmp (group1, group2, HOL_ENTRY_PTRCMP (entry1, entry2));
821 /* Version of hol_entry_cmp with correct signature for qsort. */
822 static int
823 hol_entry_qcmp (const void *entry1_v, const void *entry2_v)
825 return hol_entry_cmp (entry1_v, entry2_v);
828 /* Sort HOL by group and alphabetically by option name (with short options
829 taking precedence over long). Since the sorting is for display purposes
830 only, the shadowing of options isn't effected. */
831 static void
832 hol_sort (struct hol *hol)
834 if (hol->num_entries > 0)
836 unsigned i;
837 struct hol_entry *e;
838 for (i = 0, e = hol->entries; i < hol->num_entries; i++, e++)
839 e->ord = i;
840 qsort (hol->entries, hol->num_entries, sizeof (struct hol_entry),
841 hol_entry_qcmp);
845 /* Append MORE to HOL, destroying MORE in the process. Options in HOL shadow
846 any in MORE with the same name. */
847 static void
848 hol_append (struct hol *hol, struct hol *more)
850 struct hol_cluster **cl_end = &hol->clusters;
852 /* Steal MORE's cluster list, and add it to the end of HOL's. */
853 while (*cl_end)
854 cl_end = &(*cl_end)->next;
855 *cl_end = more->clusters;
856 more->clusters = 0;
858 /* Merge entries. */
859 if (more->num_entries > 0)
861 if (hol->num_entries == 0)
863 hol->num_entries = more->num_entries;
864 hol->entries = more->entries;
865 hol->short_options = more->short_options;
866 more->num_entries = 0; /* Mark MORE's fields as invalid. */
868 else
869 /* Append the entries in MORE to those in HOL, taking care to only add
870 non-shadowed SHORT_OPTIONS values. */
872 unsigned left;
873 char *so, *more_so;
874 struct hol_entry *e;
875 unsigned num_entries = hol->num_entries + more->num_entries;
876 struct hol_entry *entries =
877 malloc (num_entries * sizeof (struct hol_entry));
878 unsigned hol_so_len = strlen (hol->short_options);
879 char *short_options =
880 malloc (hol_so_len + strlen (more->short_options) + 1);
882 assert (entries && short_options);
883 if (SIZE_MAX <= UINT_MAX)
884 assert (num_entries <= SIZE_MAX / sizeof (struct hol_entry));
886 __mempcpy (__mempcpy (entries, hol->entries,
887 hol->num_entries * sizeof (struct hol_entry)),
888 more->entries,
889 more->num_entries * sizeof (struct hol_entry));
891 __mempcpy (short_options, hol->short_options, hol_so_len);
893 /* Fix up the short options pointers from HOL. */
894 for (e = entries, left = hol->num_entries; left > 0; e++, left--)
895 e->short_options =
896 short_options + (e->short_options - hol->short_options);
898 /* Now add the short options from MORE, fixing up its entries
899 too. */
900 so = short_options + hol_so_len;
901 more_so = more->short_options;
902 for (left = more->num_entries; left > 0; e++, left--)
904 int opts_left;
905 const struct argp_option *opt;
907 e->short_options = so;
909 for (opts_left = e->num, opt = e->opt; opts_left; opt++, opts_left--)
911 int ch = *more_so;
912 if (oshort (opt) && ch == opt->key)
913 /* The next short option in MORE_SO, CH, is from OPT. */
915 if (! find_char (ch, short_options,
916 short_options + hol_so_len))
917 /* The short option CH isn't shadowed by HOL's options,
918 so add it to the sum. */
919 *so++ = ch;
920 more_so++;
925 *so = '\0';
927 free (hol->entries);
928 free (hol->short_options);
930 hol->entries = entries;
931 hol->num_entries = num_entries;
932 hol->short_options = short_options;
936 hol_free (more);
939 /* Inserts enough spaces to make sure STREAM is at column COL. */
940 static void
941 indent_to (argp_fmtstream_t stream, unsigned col)
943 int needed = col - __argp_fmtstream_point (stream);
944 while (needed-- > 0)
945 __argp_fmtstream_putc (stream, ' ');
948 /* Output to STREAM either a space, or a newline if there isn't room for at
949 least ENSURE characters before the right margin. */
950 static void
951 space (argp_fmtstream_t stream, size_t ensure)
953 if (__argp_fmtstream_point (stream) + ensure
954 >= __argp_fmtstream_rmargin (stream))
955 __argp_fmtstream_putc (stream, '\n');
956 else
957 __argp_fmtstream_putc (stream, ' ');
960 /* If the option REAL has an argument, we print it in using the printf
961 format REQ_FMT or OPT_FMT depending on whether it's a required or
962 optional argument. */
963 static void
964 arg (const struct argp_option *real, const char *req_fmt, const char *opt_fmt,
965 const char *domain, argp_fmtstream_t stream)
967 if (real->arg)
969 if (real->flags & OPTION_ARG_OPTIONAL)
970 __argp_fmtstream_printf (stream, opt_fmt,
971 dgettext (domain, real->arg));
972 else
973 __argp_fmtstream_printf (stream, req_fmt,
974 dgettext (domain, real->arg));
978 /* Helper functions for hol_entry_help. */
980 /* State used during the execution of hol_help. */
981 struct hol_help_state
983 /* PREV_ENTRY should contain the previous entry printed, or 0. */
984 struct hol_entry *prev_entry;
986 /* If an entry is in a different group from the previous one, and SEP_GROUPS
987 is true, then a blank line will be printed before any output. */
988 int sep_groups;
990 /* True if a duplicate option argument was suppressed (only ever set if
991 UPARAMS.dup_args is false). */
992 int suppressed_dup_arg;
995 /* Some state used while printing a help entry (used to communicate with
996 helper functions). See the doc for hol_entry_help for more info, as most
997 of the fields are copied from its arguments. */
998 struct pentry_state
1000 const struct hol_entry *entry;
1001 argp_fmtstream_t stream;
1002 struct hol_help_state *hhstate;
1004 /* True if nothing's been printed so far. */
1005 int first;
1007 /* If non-zero, the state that was used to print this help. */
1008 const struct argp_state *state;
1011 /* If a user doc filter should be applied to DOC, do so. */
1012 static const char *
1013 filter_doc (const char *doc, int key, const struct argp *argp,
1014 const struct argp_state *state)
1016 if (argp->help_filter)
1017 /* We must apply a user filter to this output. */
1019 void *input = __argp_input (argp, state);
1020 return (*argp->help_filter) (key, doc, input);
1022 else
1023 /* No filter. */
1024 return doc;
1027 /* Prints STR as a header line, with the margin lines set appropriately, and
1028 notes the fact that groups should be separated with a blank line. ARGP is
1029 the argp that should dictate any user doc filtering to take place. Note
1030 that the previous wrap margin isn't restored, but the left margin is reset
1031 to 0. */
1032 static void
1033 print_header (const char *str, const struct argp *argp,
1034 struct pentry_state *pest)
1036 const char *tstr = dgettext (argp->argp_domain, str);
1037 const char *fstr = filter_doc (tstr, ARGP_KEY_HELP_HEADER, argp, pest->state);
1039 if (fstr)
1041 if (*fstr)
1043 if (pest->hhstate->prev_entry)
1044 /* Precede with a blank line. */
1045 __argp_fmtstream_putc (pest->stream, '\n');
1046 indent_to (pest->stream, uparams.header_col);
1047 __argp_fmtstream_set_lmargin (pest->stream, uparams.header_col);
1048 __argp_fmtstream_set_wmargin (pest->stream, uparams.header_col);
1049 __argp_fmtstream_puts (pest->stream, fstr);
1050 __argp_fmtstream_set_lmargin (pest->stream, 0);
1051 __argp_fmtstream_putc (pest->stream, '\n');
1054 pest->hhstate->sep_groups = 1; /* Separate subsequent groups. */
1057 if (fstr != tstr)
1058 free ((char *) fstr);
1061 /* Inserts a comma if this isn't the first item on the line, and then makes
1062 sure we're at least to column COL. If this *is* the first item on a line,
1063 prints any pending whitespace/headers that should precede this line. Also
1064 clears FIRST. */
1065 static void
1066 comma (unsigned col, struct pentry_state *pest)
1068 if (pest->first)
1070 const struct hol_entry *pe = pest->hhstate->prev_entry;
1071 const struct hol_cluster *cl = pest->entry->cluster;
1073 if (pest->hhstate->sep_groups && pe && pest->entry->group != pe->group)
1074 __argp_fmtstream_putc (pest->stream, '\n');
1076 if (cl && cl->header && *cl->header
1077 && (!pe
1078 || (pe->cluster != cl
1079 && !hol_cluster_is_child (pe->cluster, cl))))
1080 /* If we're changing clusters, then this must be the start of the
1081 ENTRY's cluster unless that is an ancestor of the previous one
1082 (in which case we had just popped into a sub-cluster for a bit).
1083 If so, then print the cluster's header line. */
1085 int old_wm = __argp_fmtstream_wmargin (pest->stream);
1086 print_header (cl->header, cl->argp, pest);
1087 __argp_fmtstream_set_wmargin (pest->stream, old_wm);
1090 pest->first = 0;
1092 else
1093 __argp_fmtstream_puts (pest->stream, ", ");
1095 indent_to (pest->stream, col);
1098 /* Print help for ENTRY to STREAM. */
1099 static void
1100 hol_entry_help (struct hol_entry *entry, const struct argp_state *state,
1101 argp_fmtstream_t stream, struct hol_help_state *hhstate)
1103 unsigned num;
1104 const struct argp_option *real = entry->opt, *opt;
1105 char *so = entry->short_options;
1106 int have_long_opt = 0; /* We have any long options. */
1107 /* Saved margins. */
1108 int old_lm = __argp_fmtstream_set_lmargin (stream, 0);
1109 int old_wm = __argp_fmtstream_wmargin (stream);
1110 /* PEST is a state block holding some of our variables that we'd like to
1111 share with helper functions. */
1112 struct pentry_state pest;
1114 pest.entry = entry;
1115 pest.stream = stream;
1116 pest.hhstate = hhstate;
1117 pest.first = 1;
1118 pest.state = state;
1120 if (! odoc (real))
1121 for (opt = real, num = entry->num; num > 0; opt++, num--)
1122 if (opt->name && ovisible (opt))
1124 have_long_opt = 1;
1125 break;
1128 /* First emit short options. */
1129 __argp_fmtstream_set_wmargin (stream, uparams.short_opt_col); /* For truly bizarre cases. */
1130 for (opt = real, num = entry->num; num > 0; opt++, num--)
1131 if (oshort (opt) && opt->key == *so)
1132 /* OPT has a valid (non shadowed) short option. */
1134 if (ovisible (opt))
1136 comma (uparams.short_opt_col, &pest);
1137 __argp_fmtstream_putc (stream, '-');
1138 __argp_fmtstream_putc (stream, *so);
1139 if (!have_long_opt || uparams.dup_args)
1140 arg (real, " %s", "[%s]", state->root_argp->argp_domain, stream);
1141 else if (real->arg)
1142 hhstate->suppressed_dup_arg = 1;
1144 so++;
1147 /* Now, long options. */
1148 if (odoc (real))
1149 /* A "documentation" option. */
1151 __argp_fmtstream_set_wmargin (stream, uparams.doc_opt_col);
1152 for (opt = real, num = entry->num; num > 0; opt++, num--)
1153 if (opt->name && *opt->name && ovisible (opt))
1155 comma (uparams.doc_opt_col, &pest);
1156 /* Calling dgettext here isn't quite right, since sorting will
1157 have been done on the original; but documentation options
1158 should be pretty rare anyway... */
1159 __argp_fmtstream_puts (stream,
1160 onotrans (opt) ?
1161 opt->name :
1162 dgettext (state->root_argp->argp_domain,
1163 opt->name));
1166 else
1167 /* A real long option. */
1169 int first_long_opt = 1;
1171 __argp_fmtstream_set_wmargin (stream, uparams.long_opt_col);
1172 for (opt = real, num = entry->num; num > 0; opt++, num--)
1173 if (opt->name && ovisible (opt))
1175 comma (uparams.long_opt_col, &pest);
1176 __argp_fmtstream_printf (stream, "--%s", opt->name);
1177 if (first_long_opt || uparams.dup_args)
1178 arg (real, "=%s", "[=%s]", state->root_argp->argp_domain,
1179 stream);
1180 else if (real->arg)
1181 hhstate->suppressed_dup_arg = 1;
1185 /* Next, documentation strings. */
1186 __argp_fmtstream_set_lmargin (stream, 0);
1188 if (pest.first)
1190 /* Didn't print any switches, what's up? */
1191 if (!oshort (real) && !real->name)
1192 /* This is a group header, print it nicely. */
1193 print_header (real->doc, entry->argp, &pest);
1194 else
1195 /* Just a totally shadowed option or null header; print nothing. */
1196 goto cleanup; /* Just return, after cleaning up. */
1198 else
1200 const char *tstr = real->doc ? dgettext (state->root_argp->argp_domain,
1201 real->doc) : 0;
1202 const char *fstr = filter_doc (tstr, real->key, entry->argp, state);
1203 if (fstr && *fstr)
1205 unsigned int col = __argp_fmtstream_point (stream);
1207 __argp_fmtstream_set_lmargin (stream, uparams.opt_doc_col);
1208 __argp_fmtstream_set_wmargin (stream, uparams.opt_doc_col);
1210 if (col > (unsigned int) (uparams.opt_doc_col + 3))
1211 __argp_fmtstream_putc (stream, '\n');
1212 else if (col >= (unsigned int) uparams.opt_doc_col)
1213 __argp_fmtstream_puts (stream, " ");
1214 else
1215 indent_to (stream, uparams.opt_doc_col);
1217 __argp_fmtstream_puts (stream, fstr);
1219 if (fstr && fstr != tstr)
1220 free ((char *) fstr);
1222 /* Reset the left margin. */
1223 __argp_fmtstream_set_lmargin (stream, 0);
1224 __argp_fmtstream_putc (stream, '\n');
1227 hhstate->prev_entry = entry;
1229 cleanup:
1230 __argp_fmtstream_set_lmargin (stream, old_lm);
1231 __argp_fmtstream_set_wmargin (stream, old_wm);
1234 /* Output a long help message about the options in HOL to STREAM. */
1235 static void
1236 hol_help (struct hol *hol, const struct argp_state *state,
1237 argp_fmtstream_t stream)
1239 unsigned num;
1240 struct hol_entry *entry;
1241 struct hol_help_state hhstate = { 0, 0, 0 };
1243 for (entry = hol->entries, num = hol->num_entries; num > 0; entry++, num--)
1244 hol_entry_help (entry, state, stream, &hhstate);
1246 if (hhstate.suppressed_dup_arg && uparams.dup_args_note)
1248 const char *tstr = dgettext (state->root_argp->argp_domain, "\
1249 Mandatory or optional arguments to long options are also mandatory or \
1250 optional for any corresponding short options.");
1251 const char *fstr = filter_doc (tstr, ARGP_KEY_HELP_DUP_ARGS_NOTE,
1252 state ? state->root_argp : 0, state);
1253 if (fstr && *fstr)
1255 __argp_fmtstream_putc (stream, '\n');
1256 __argp_fmtstream_puts (stream, fstr);
1257 __argp_fmtstream_putc (stream, '\n');
1259 if (fstr && fstr != tstr)
1260 free ((char *) fstr);
1264 /* Helper functions for hol_usage. */
1266 /* If OPT is a short option without an arg, append its key to the string
1267 pointer pointer to by COOKIE, and advance the pointer. */
1268 static int
1269 add_argless_short_opt (const struct argp_option *opt,
1270 const struct argp_option *real,
1271 const char *domain, void *cookie)
1273 char **snao_end = cookie;
1274 if (!(opt->arg || real->arg)
1275 && !((opt->flags | real->flags) & OPTION_NO_USAGE))
1276 *(*snao_end)++ = opt->key;
1277 return 0;
1280 /* If OPT is a short option with an arg, output a usage entry for it to the
1281 stream pointed at by COOKIE. */
1282 static int
1283 usage_argful_short_opt (const struct argp_option *opt,
1284 const struct argp_option *real,
1285 const char *domain, void *cookie)
1287 argp_fmtstream_t stream = cookie;
1288 const char *arg = opt->arg;
1289 int flags = opt->flags | real->flags;
1291 if (! arg)
1292 arg = real->arg;
1294 if (arg && !(flags & OPTION_NO_USAGE))
1296 arg = dgettext (domain, arg);
1298 if (flags & OPTION_ARG_OPTIONAL)
1299 __argp_fmtstream_printf (stream, " [-%c[%s]]", opt->key, arg);
1300 else
1302 /* Manually do line wrapping so that it (probably) won't
1303 get wrapped at the embedded space. */
1304 space (stream, 6 + strlen (arg));
1305 __argp_fmtstream_printf (stream, "[-%c %s]", opt->key, arg);
1309 return 0;
1312 /* Output a usage entry for the long option opt to the stream pointed at by
1313 COOKIE. */
1314 static int
1315 usage_long_opt (const struct argp_option *opt,
1316 const struct argp_option *real,
1317 const char *domain, void *cookie)
1319 argp_fmtstream_t stream = cookie;
1320 const char *arg = opt->arg;
1321 int flags = opt->flags | real->flags;
1323 if (! arg)
1324 arg = real->arg;
1326 if (! (flags & OPTION_NO_USAGE) && !odoc (opt))
1328 if (arg)
1330 arg = dgettext (domain, arg);
1331 if (flags & OPTION_ARG_OPTIONAL)
1332 __argp_fmtstream_printf (stream, " [--%s[=%s]]", opt->name, arg);
1333 else
1334 __argp_fmtstream_printf (stream, " [--%s=%s]", opt->name, arg);
1336 else
1337 __argp_fmtstream_printf (stream, " [--%s]", opt->name);
1340 return 0;
1343 /* Print a short usage description for the arguments in HOL to STREAM. */
1344 static void
1345 hol_usage (struct hol *hol, argp_fmtstream_t stream)
1347 if (hol->num_entries > 0)
1349 unsigned nentries;
1350 struct hol_entry *entry;
1351 char *short_no_arg_opts = alloca (strlen (hol->short_options) + 1);
1352 char *snao_end = short_no_arg_opts;
1354 /* First we put a list of short options without arguments. */
1355 for (entry = hol->entries, nentries = hol->num_entries
1356 ; nentries > 0
1357 ; entry++, nentries--)
1358 hol_entry_short_iterate (entry, add_argless_short_opt,
1359 entry->argp->argp_domain, &snao_end);
1360 if (snao_end > short_no_arg_opts)
1362 *snao_end++ = 0;
1363 __argp_fmtstream_printf (stream, " [-%s]", short_no_arg_opts);
1366 /* Now a list of short options *with* arguments. */
1367 for (entry = hol->entries, nentries = hol->num_entries
1368 ; nentries > 0
1369 ; entry++, nentries--)
1370 hol_entry_short_iterate (entry, usage_argful_short_opt,
1371 entry->argp->argp_domain, stream);
1373 /* Finally, a list of long options (whew!). */
1374 for (entry = hol->entries, nentries = hol->num_entries
1375 ; nentries > 0
1376 ; entry++, nentries--)
1377 hol_entry_long_iterate (entry, usage_long_opt,
1378 entry->argp->argp_domain, stream);
1382 /* Make a HOL containing all levels of options in ARGP. CLUSTER is the
1383 cluster in which ARGP's entries should be clustered, or 0. */
1384 static struct hol *
1385 argp_hol (const struct argp *argp, struct hol_cluster *cluster)
1387 const struct argp_child *child = argp->children;
1388 struct hol *hol = make_hol (argp, cluster);
1389 if (child)
1390 while (child->argp)
1392 struct hol_cluster *child_cluster =
1393 ((child->group || child->header)
1394 /* Put CHILD->argp within its own cluster. */
1395 ? hol_add_cluster (hol, child->group, child->header,
1396 child - argp->children, cluster, argp)
1397 /* Just merge it into the parent's cluster. */
1398 : cluster);
1399 hol_append (hol, argp_hol (child->argp, child_cluster)) ;
1400 child++;
1402 return hol;
1405 /* Calculate how many different levels with alternative args strings exist in
1406 ARGP. */
1407 static size_t
1408 argp_args_levels (const struct argp *argp)
1410 size_t levels = 0;
1411 const struct argp_child *child = argp->children;
1413 if (argp->args_doc && strchr (argp->args_doc, '\n'))
1414 levels++;
1416 if (child)
1417 while (child->argp)
1418 levels += argp_args_levels ((child++)->argp);
1420 return levels;
1423 /* Print all the non-option args documented in ARGP to STREAM. Any output is
1424 preceded by a space. LEVELS is a pointer to a byte vector the length
1425 returned by argp_args_levels; it should be initialized to zero, and
1426 updated by this routine for the next call if ADVANCE is true. True is
1427 returned as long as there are more patterns to output. */
1428 static int
1429 argp_args_usage (const struct argp *argp, const struct argp_state *state,
1430 char **levels, int advance, argp_fmtstream_t stream)
1432 char *our_level = *levels;
1433 int multiple = 0;
1434 const struct argp_child *child = argp->children;
1435 const char *tdoc = dgettext (argp->argp_domain, argp->args_doc), *nl = 0;
1436 const char *fdoc = filter_doc (tdoc, ARGP_KEY_HELP_ARGS_DOC, argp, state);
1438 if (fdoc)
1440 const char *cp = fdoc;
1441 nl = __strchrnul (cp, '\n');
1442 if (*nl != '\0')
1443 /* This is a "multi-level" args doc; advance to the correct position
1444 as determined by our state in LEVELS, and update LEVELS. */
1446 int i;
1447 multiple = 1;
1448 for (i = 0; i < *our_level; i++)
1449 cp = nl + 1, nl = __strchrnul (cp, '\n');
1450 (*levels)++;
1453 /* Manually do line wrapping so that it (probably) won't get wrapped at
1454 any embedded spaces. */
1455 space (stream, 1 + nl - cp);
1457 __argp_fmtstream_write (stream, cp, nl - cp);
1459 if (fdoc && fdoc != tdoc)
1460 free ((char *)fdoc); /* Free user's modified doc string. */
1462 if (child)
1463 while (child->argp)
1464 advance = !argp_args_usage ((child++)->argp, state, levels, advance, stream);
1466 if (advance && multiple)
1468 /* Need to increment our level. */
1469 if (*nl)
1470 /* There's more we can do here. */
1472 (*our_level)++;
1473 advance = 0; /* Our parent shouldn't advance also. */
1475 else if (*our_level > 0)
1476 /* We had multiple levels, but used them up; reset to zero. */
1477 *our_level = 0;
1480 return !advance;
1483 /* Print the documentation for ARGP to STREAM; if POST is false, then
1484 everything preceding a '\v' character in the documentation strings (or
1485 the whole string, for those with none) is printed, otherwise, everything
1486 following the '\v' character (nothing for strings without). Each separate
1487 bit of documentation is separated a blank line, and if PRE_BLANK is true,
1488 then the first is as well. If FIRST_ONLY is true, only the first
1489 occurrence is output. Returns true if anything was output. */
1490 static int
1491 argp_doc (const struct argp *argp, const struct argp_state *state,
1492 int post, int pre_blank, int first_only,
1493 argp_fmtstream_t stream)
1495 const char *text;
1496 const char *inp_text;
1497 size_t inp_text_len = 0;
1498 const char *trans_text;
1499 void *input = 0;
1500 int anything = 0;
1501 const struct argp_child *child = argp->children;
1503 if (argp->doc)
1505 char *vt = strchr (argp->doc, '\v');
1506 if (vt)
1508 if (post)
1509 inp_text = vt + 1;
1510 else
1512 inp_text_len = vt - argp->doc;
1513 inp_text = __strndup (argp->doc, inp_text_len);
1516 else
1517 inp_text = post ? 0 : argp->doc;
1518 trans_text = inp_text ? dgettext (argp->argp_domain, inp_text) : NULL;
1520 else
1521 trans_text = inp_text = 0;
1523 if (argp->help_filter)
1524 /* We have to filter the doc strings. */
1526 input = __argp_input (argp, state);
1527 text =
1528 (*argp->help_filter) (post
1529 ? ARGP_KEY_HELP_POST_DOC
1530 : ARGP_KEY_HELP_PRE_DOC,
1531 trans_text, input);
1533 else
1534 text = (const char *) trans_text;
1536 if (text)
1538 if (pre_blank)
1539 __argp_fmtstream_putc (stream, '\n');
1541 __argp_fmtstream_puts (stream, text);
1543 if (__argp_fmtstream_point (stream) > __argp_fmtstream_lmargin (stream))
1544 __argp_fmtstream_putc (stream, '\n');
1546 anything = 1;
1549 if (text && text != trans_text)
1550 free ((char *) text); /* Free TEXT returned from the help filter. */
1552 if (inp_text && inp_text_len)
1553 free ((char *) inp_text); /* We copied INP_TEXT, so free it now. */
1555 if (post && argp->help_filter)
1556 /* Now see if we have to output an ARGP_KEY_HELP_EXTRA text. */
1558 text = (*argp->help_filter) (ARGP_KEY_HELP_EXTRA, 0, input);
1559 if (text)
1561 if (anything || pre_blank)
1562 __argp_fmtstream_putc (stream, '\n');
1563 __argp_fmtstream_puts (stream, text);
1564 free ((char *) text);
1565 if (__argp_fmtstream_point (stream)
1566 > __argp_fmtstream_lmargin (stream))
1567 __argp_fmtstream_putc (stream, '\n');
1568 anything = 1;
1572 if (child)
1573 while (child->argp && !(first_only && anything))
1574 anything |=
1575 argp_doc ((child++)->argp, state,
1576 post, anything || pre_blank, first_only,
1577 stream);
1579 return anything;
1582 /* Output a usage message for ARGP to STREAM. If called from
1583 argp_state_help, STATE is the relevant parsing state. FLAGS are from the
1584 set ARGP_HELP_*. NAME is what to use wherever a "program name" is
1585 needed. */
1586 static void
1587 _help (const struct argp *argp, const struct argp_state *state, FILE *stream,
1588 unsigned flags, char *name)
1590 int anything = 0; /* Whether we've output anything. */
1591 struct hol *hol = 0;
1592 argp_fmtstream_t fs;
1594 if (! stream)
1595 return;
1597 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1598 __flockfile (stream);
1599 #endif
1601 if (! uparams.valid)
1602 fill_in_uparams (state);
1604 fs = __argp_make_fmtstream (stream, 0, uparams.rmargin, 0);
1605 if (! fs)
1607 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1608 __funlockfile (stream);
1609 #endif
1610 return;
1613 if (flags & (ARGP_HELP_USAGE | ARGP_HELP_SHORT_USAGE | ARGP_HELP_LONG))
1615 hol = argp_hol (argp, 0);
1617 /* If present, these options always come last. */
1618 hol_set_group (hol, "help", -1);
1619 hol_set_group (hol, "version", -1);
1621 hol_sort (hol);
1624 if (flags & (ARGP_HELP_USAGE | ARGP_HELP_SHORT_USAGE))
1625 /* Print a short "Usage:" message. */
1627 int first_pattern = 1, more_patterns;
1628 size_t num_pattern_levels = argp_args_levels (argp);
1629 char *pattern_levels = alloca (num_pattern_levels);
1631 memset (pattern_levels, 0, num_pattern_levels);
1635 int old_lm;
1636 int old_wm = __argp_fmtstream_set_wmargin (fs, uparams.usage_indent);
1637 char *levels = pattern_levels;
1639 if (first_pattern)
1640 __argp_fmtstream_printf (fs, "%s %s",
1641 dgettext (argp->argp_domain, "Usage:"),
1642 name);
1643 else
1644 __argp_fmtstream_printf (fs, "%s %s",
1645 dgettext (argp->argp_domain, " or: "),
1646 name);
1648 /* We set the lmargin as well as the wmargin, because hol_usage
1649 manually wraps options with newline to avoid annoying breaks. */
1650 old_lm = __argp_fmtstream_set_lmargin (fs, uparams.usage_indent);
1652 if (flags & ARGP_HELP_SHORT_USAGE)
1653 /* Just show where the options go. */
1655 if (hol->num_entries > 0)
1656 __argp_fmtstream_puts (fs, dgettext (argp->argp_domain,
1657 " [OPTION...]"));
1659 else
1660 /* Actually print the options. */
1662 hol_usage (hol, fs);
1663 flags |= ARGP_HELP_SHORT_USAGE; /* But only do so once. */
1666 more_patterns = argp_args_usage (argp, state, &levels, 1, fs);
1668 __argp_fmtstream_set_wmargin (fs, old_wm);
1669 __argp_fmtstream_set_lmargin (fs, old_lm);
1671 __argp_fmtstream_putc (fs, '\n');
1672 anything = 1;
1674 first_pattern = 0;
1676 while (more_patterns);
1679 if (flags & ARGP_HELP_PRE_DOC)
1680 anything |= argp_doc (argp, state, 0, 0, 1, fs);
1682 if (flags & ARGP_HELP_SEE)
1684 __argp_fmtstream_printf (fs, dgettext (argp->argp_domain, "\
1685 Try '%s --help' or '%s --usage' for more information.\n"),
1686 name, name);
1687 anything = 1;
1690 if (flags & ARGP_HELP_LONG)
1691 /* Print a long, detailed help message. */
1693 /* Print info about all the options. */
1694 if (hol->num_entries > 0)
1696 if (anything)
1697 __argp_fmtstream_putc (fs, '\n');
1698 hol_help (hol, state, fs);
1699 anything = 1;
1703 if (flags & ARGP_HELP_POST_DOC)
1704 /* Print any documentation strings at the end. */
1705 anything |= argp_doc (argp, state, 1, anything, 0, fs);
1707 if ((flags & ARGP_HELP_BUG_ADDR) && argp_program_bug_address)
1709 if (anything)
1710 __argp_fmtstream_putc (fs, '\n');
1711 __argp_fmtstream_printf (fs, dgettext (argp->argp_domain,
1712 "Report bugs to %s.\n"),
1713 argp_program_bug_address);
1714 anything = 1;
1717 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1718 __funlockfile (stream);
1719 #endif
1721 if (hol)
1722 hol_free (hol);
1724 __argp_fmtstream_free (fs);
1727 /* Output a usage message for ARGP to STREAM. FLAGS are from the set
1728 ARGP_HELP_*. NAME is what to use wherever a "program name" is needed. */
1729 void __argp_help (const struct argp *argp, FILE *stream,
1730 unsigned flags, char *name)
1732 struct argp_state state;
1733 memset (&state, 0, sizeof state);
1734 state.root_argp = argp;
1735 _help (argp, &state, stream, flags, name);
1737 #ifdef weak_alias
1738 weak_alias (__argp_help, argp_help)
1739 #endif
1741 #if ! (defined _LIBC || HAVE_DECL_PROGRAM_INVOCATION_SHORT_NAME)
1742 char *
1743 __argp_short_program_name (void)
1745 # if HAVE_DECL_PROGRAM_INVOCATION_NAME
1746 return __argp_base_name (program_invocation_name);
1747 # else
1748 /* FIXME: What now? Miles suggests that it is better to use NULL,
1749 but currently the value is passed on directly to fputs_unlocked,
1750 so that requires more changes. */
1751 # if __GNUC__
1752 # warning No reasonable value to return
1753 # endif /* __GNUC__ */
1754 return "";
1755 # endif
1757 #endif
1759 /* Output, if appropriate, a usage message for STATE to STREAM. FLAGS are
1760 from the set ARGP_HELP_*. */
1761 void
1762 __argp_state_help (const struct argp_state *state, FILE *stream, unsigned flags)
1764 if ((!state || ! (state->flags & ARGP_NO_ERRS)) && stream)
1766 if (state && (state->flags & ARGP_LONG_ONLY))
1767 flags |= ARGP_HELP_LONG_ONLY;
1769 _help (state ? state->root_argp : 0, state, stream, flags,
1770 state ? state->name : __argp_short_program_name ());
1772 if (!state || ! (state->flags & ARGP_NO_EXIT))
1774 if (flags & ARGP_HELP_EXIT_ERR)
1775 exit (argp_err_exit_status);
1776 if (flags & ARGP_HELP_EXIT_OK)
1777 exit (0);
1781 #ifdef weak_alias
1782 weak_alias (__argp_state_help, argp_state_help)
1783 #endif
1785 /* If appropriate, print the printf string FMT and following args, preceded
1786 by the program name and ':', to stderr, and followed by a "Try ... --help"
1787 message, then exit (1). */
1788 void
1789 __argp_error (const struct argp_state *state, const char *fmt, ...)
1791 if (!state || !(state->flags & ARGP_NO_ERRS))
1793 FILE *stream = state ? state->err_stream : stderr;
1795 if (stream)
1797 va_list ap;
1799 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1800 __flockfile (stream);
1801 #endif
1803 va_start (ap, fmt);
1805 #ifdef USE_IN_LIBIO
1806 if (_IO_fwide (stream, 0) > 0)
1808 char *buf;
1810 if (__asprintf (&buf, fmt, ap) < 0)
1811 buf = NULL;
1813 __fwprintf (stream, L"%s: %s\n",
1814 state ? state->name : __argp_short_program_name (),
1815 buf);
1817 free (buf);
1819 else
1820 #endif
1822 fputs_unlocked (state
1823 ? state->name : __argp_short_program_name (),
1824 stream);
1825 putc_unlocked (':', stream);
1826 putc_unlocked (' ', stream);
1828 vfprintf (stream, fmt, ap);
1830 putc_unlocked ('\n', stream);
1833 __argp_state_help (state, stream, ARGP_HELP_STD_ERR);
1835 va_end (ap);
1837 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1838 __funlockfile (stream);
1839 #endif
1843 #ifdef weak_alias
1844 weak_alias (__argp_error, argp_error)
1845 #endif
1847 /* Similar to the standard gnu error-reporting function error(), but will
1848 respect the ARGP_NO_EXIT and ARGP_NO_ERRS flags in STATE, and will print
1849 to STATE->err_stream. This is useful for argument parsing code that is
1850 shared between program startup (when exiting is desired) and runtime
1851 option parsing (when typically an error code is returned instead). The
1852 difference between this function and argp_error is that the latter is for
1853 *parsing errors*, and the former is for other problems that occur during
1854 parsing but don't reflect a (syntactic) problem with the input. */
1855 void
1856 __argp_failure (const struct argp_state *state, int status, int errnum,
1857 const char *fmt, ...)
1859 if (!state || !(state->flags & ARGP_NO_ERRS))
1861 FILE *stream = state ? state->err_stream : stderr;
1863 if (stream)
1865 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1866 __flockfile (stream);
1867 #endif
1869 #ifdef USE_IN_LIBIO
1870 if (_IO_fwide (stream, 0) > 0)
1871 __fwprintf (stream, L"%s",
1872 state ? state->name : __argp_short_program_name ());
1873 else
1874 #endif
1875 fputs_unlocked (state
1876 ? state->name : __argp_short_program_name (),
1877 stream);
1879 if (fmt)
1881 va_list ap;
1883 va_start (ap, fmt);
1884 #ifdef USE_IN_LIBIO
1885 if (_IO_fwide (stream, 0) > 0)
1887 char *buf;
1889 if (__asprintf (&buf, fmt, ap) < 0)
1890 buf = NULL;
1892 __fwprintf (stream, L": %s", buf);
1894 free (buf);
1896 else
1897 #endif
1899 putc_unlocked (':', stream);
1900 putc_unlocked (' ', stream);
1902 vfprintf (stream, fmt, ap);
1905 va_end (ap);
1908 if (errnum)
1910 char buf[200];
1912 #ifdef USE_IN_LIBIO
1913 if (_IO_fwide (stream, 0) > 0)
1914 __fwprintf (stream, L": %s",
1915 __strerror_r (errnum, buf, sizeof (buf)));
1916 else
1917 #endif
1919 char const *s = NULL;
1920 putc_unlocked (':', stream);
1921 putc_unlocked (' ', stream);
1922 #if _LIBC || (HAVE_DECL_STRERROR_R && STRERROR_R_CHAR_P && !defined strerror_r)
1923 s = __strerror_r (errnum, buf, sizeof buf);
1924 #elif HAVE_DECL_STRERROR_R
1925 if (__strerror_r (errnum, buf, sizeof buf) == 0)
1926 s = buf;
1927 #endif
1928 #if !_LIBC
1929 if (! s && ! (s = strerror (errnum)))
1930 s = dgettext (state->root_argp->argp_domain,
1931 "Unknown system error");
1932 #endif
1933 fputs (s, stream);
1937 #ifdef USE_IN_LIBIO
1938 if (_IO_fwide (stream, 0) > 0)
1939 putwc_unlocked (L'\n', stream);
1940 else
1941 #endif
1942 putc_unlocked ('\n', stream);
1944 #if _LIBC || (HAVE_FLOCKFILE && HAVE_FUNLOCKFILE)
1945 __funlockfile (stream);
1946 #endif
1948 if (status && (!state || !(state->flags & ARGP_NO_EXIT)))
1949 exit (status);
1953 #ifdef weak_alias
1954 weak_alias (__argp_failure, argp_failure)
1955 #endif