Debian Codegraph @

lib/argp-help.c

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