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