Mercurial > hg-old > index.cgi

comparison lib/argp-help.c @ 265:68fbca173508 2.6

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