]>
git.ipfire.org Git - thirdparty/glibc.git/blob - argp/argp-help.c
1 /* Hierarchial argument parsing help output
2 Copyright (C) 1995, 1996, 1997 Free Software Foundation, Inc.
3 This file is part of the GNU C Library.
4 Written by Miles Bader <miles@gnu.ai.mit.edu>.
6 The GNU C Library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public License as
8 published by the Free Software Foundation; either version 2 of the
9 License, or (at your option) any later version.
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 Library General Public License for more details.
16 You should have received a copy of the GNU Library General Public
17 License along with the GNU C Library; see the file COPYING.LIB. If not,
18 write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19 Boston, MA 02111-1307, USA. */
33 /* This is for other GNU distributions with internationalized messages.
34 When compiling libc, the _ macro is predefined. */
37 # define _(msgid) gettext (msgid)
39 # define _(msgid) (msgid)
40 # define gettext(msgid) (msgid)
45 #include "argp-fmtstream.h"
46 #include "argp-namefrob.h"
48 #define SHORT_OPT_COL 2 /* column in which short options start */
49 #define LONG_OPT_COL 6 /* column in which long options start */
50 #define DOC_OPT_COL 2 /* column in which doc options start */
51 #define OPT_DOC_COL 29 /* column in which option text starts */
52 #define HEADER_COL 1 /* column in which group headers are printed */
53 #define USAGE_INDENT 12 /* indentation of wrapped usage lines */
54 #define RMARGIN 79 /* right margin used for wrapping */
56 /* Returns true if OPT hasn't been marked invisible. Visibility only affects
57 whether OPT is displayed or used in sorting, not option shadowing. */
58 #define ovisible(opt) (! ((opt)->flags & OPTION_HIDDEN))
60 /* Returns true if OPT is an alias for an earlier option. */
61 #define oalias(opt) ((opt)->flags & OPTION_ALIAS)
63 /* Returns true if OPT is an documentation-only entry. */
64 #define odoc(opt) ((opt)->flags & OPTION_DOC)
66 /* Returns true if OPT is the end-of-list marker for a list of options. */
67 #define oend(opt) __option_is_end (opt)
69 /* Returns true if OPT has a short option. */
70 #define oshort(opt) __option_is_short (opt)
73 The help format for a particular option is like:
75 -xARG, -yARG, --long1=ARG, --long2=ARG Documentation...
77 Where ARG will be omitted if there's no argument, for this option, or
78 will be surrounded by "[" and "]" appropiately if the argument is
79 optional. The documentation string is word-wrapped appropiately, and if
80 the list of options is long enough, it will be started on a separate line.
81 If there are no short options for a given option, the first long option is
82 indented slighly in a way that's supposed to make most long options appear
83 to be in a separate column.
85 For example, the following output (from ps):
87 -p PID, --pid=PID List the process PID
88 --pgrp=PGRP List processes in the process group PGRP
89 -P, -x, --no-parent Include processes without parents
90 -Q, --all-fields Don't elide unusable fields (normally if there's
91 some reason ps can't print a field for any
92 process, it's removed from the output entirely)
93 -r, --reverse, --gratuitously-long-reverse-option
94 Reverse the order of any sort
95 --session[=SID] Add the processes from the session SID (which
96 defaults to the sid of the current process)
98 Here are some more options:
99 -f ZOT, --foonly=ZOT Glork a foonly
100 -z, --zaza Snit a zar
102 -?, --help Give this help list
103 --usage Give a short usage message
104 -V, --version Print program version
106 The struct argp_option array for the above could look like:
109 {"pid", 'p', "PID", 0, "List the process PID"},
110 {"pgrp", OPT_PGRP, "PGRP", 0, "List processes in the process group PGRP"},
111 {"no-parent", 'P', 0, 0, "Include processes without parents"},
112 {0, 'x', 0, OPTION_ALIAS},
113 {"all-fields",'Q', 0, 0, "Don't elide unusable fields (normally"
114 " if there's some reason ps can't"
115 " print a field for any process, it's"
116 " removed from the output entirely)" },
117 {"reverse", 'r', 0, 0, "Reverse the order of any sort"},
118 {"gratuitously-long-reverse-option", 0, 0, OPTION_ALIAS},
119 {"session", OPT_SESS, "SID", OPTION_ARG_OPTIONAL,
120 "Add the processes from the session"
121 " SID (which defaults to the sid of"
122 " the current process)" },
124 {0,0,0,0, "Here are some more options:"},
125 {"foonly", 'f', "ZOT", 0, "Glork a foonly"},
126 {"zaza", 'z', 0, 0, "Snit a zar"},
131 Note that the last three options are automatically supplied by argp_parse,
132 unless you tell it not to with ARGP_NO_HELP.
136 /* Returns true if CH occurs between BEG and END. */
138 find_char (char ch
, char *beg
, char *end
)
148 struct hol_cluster
; /* fwd decl */
153 const struct argp_option
*opt
;
154 /* Number of options (including aliases). */
157 /* A pointers into the HOL's short_options field, to the first short option
158 letter for this entry. The order of the characters following this point
159 corresponds to the order of options pointed to by OPT, and there are at
160 most NUM. A short option recorded in a option following OPT is only
161 valid if it occurs in the right place in SHORT_OPTIONS (otherwise it's
162 probably been shadowed by some other entry). */
165 /* Entries are sorted by their group first, in the order:
166 1, 2, ..., n, 0, -m, ..., -2, -1
167 and then alphabetically within each group. The default is 0. */
170 /* The cluster of options this entry belongs to, or 0 if none. */
171 struct hol_cluster
*cluster
;
174 /* A cluster of entries to reflect the argp tree structure. */
177 /* A descriptive header printed before options in this cluster. */
180 /* Used to order clusters within the same group with the same parent,
181 according to the order in which they occured in the parent argp's child
185 /* How to sort this cluster with respect to options and other clusters at the
186 same depth (clusters always follow options in the same group). */
189 /* The cluster to which this cluster belongs, or 0 if it's at the base
191 struct hol_cluster
*parent
;
193 /* The distance this cluster is from the root. */
196 /* Clusters in a given hol are kept in a linked list, to make freeing them
198 struct hol_cluster
*next
;
201 /* A list of options for help. */
204 /* An array of hol_entry's. */
205 struct hol_entry
*entries
;
206 /* The number of entries in this hol. If this field is zero, the others
208 unsigned num_entries
;
210 /* A string containing all short options in this HOL. Each entry contains
211 pointers into this string, so the order can't be messed with blindly. */
214 /* Clusters of entries in this hol. */
215 struct hol_cluster
*clusters
;
218 /* Create a struct hol from an array of struct argp_option. CLUSTER is the
219 hol_cluster in which these entries occur, or 0, if at the root. */
221 make_hol (const struct argp_option
*opt
, struct hol_cluster
*cluster
)
224 const struct argp_option
*o
;
225 struct hol_entry
*entry
;
226 unsigned num_short_options
= 0;
227 struct hol
*hol
= malloc (sizeof (struct hol
));
231 hol
->num_entries
= 0;
238 /* The first option must not be an alias. */
239 assert (! oalias (opt
));
241 /* Calculate the space needed. */
242 for (o
= opt
; ! oend (o
); o
++)
247 num_short_options
++; /* This is an upper bound. */
250 hol
->entries
= malloc (sizeof (struct hol_entry
) * hol
->num_entries
);
251 hol
->short_options
= malloc (num_short_options
+ 1);
253 assert (hol
->entries
&& hol
->short_options
);
255 /* Fill in the entries. */
256 so
= hol
->short_options
;
257 for (o
= opt
, entry
= hol
->entries
; ! oend (o
); entry
++)
261 entry
->short_options
= so
;
262 entry
->group
= cur_group
=
265 : ((!o
->name
&& !o
->key
)
268 entry
->cluster
= cluster
;
273 if (oshort (o
) && ! find_char (o
->key
, hol
->short_options
, so
))
274 /* O has a valid short option which hasn't already been used.*/
278 while (! oend (o
) && oalias (o
));
280 *so
= '\0'; /* null terminated so we can find the length */
286 /* Add a new cluster to HOL, with the given GROUP and HEADER (taken from the
287 associated argp child list entry), INDEX, and PARENT, and return a pointer
289 static struct hol_cluster
*
290 hol_add_cluster (struct hol
*hol
, int group
, const char *header
, int index
,
291 struct hol_cluster
*parent
)
293 struct hol_cluster
*cl
= malloc (sizeof (struct hol_cluster
));
302 cl
->next
= hol
->clusters
;
308 /* Free HOL and any resources it uses. */
310 hol_free (struct hol
*hol
)
312 struct hol_cluster
*cl
= hol
->clusters
;
316 struct hol_cluster
*next
= cl
->next
;
321 if (hol
->num_entries
> 0)
324 free (hol
->short_options
);
331 hol_entry_short_iterate (const struct hol_entry
*entry
,
332 int (*func
)(const struct argp_option
*opt
,
333 const struct argp_option
*real
,
339 const struct argp_option
*opt
, *real
= entry
->opt
;
340 char *so
= entry
->short_options
;
342 for (opt
= real
, nopts
= entry
->num
; nopts
> 0 && !val
; opt
++, nopts
--)
343 if (oshort (opt
) && *so
== opt
->key
)
348 val
= (*func
)(opt
, real
, cookie
);
356 hol_entry_long_iterate (const struct hol_entry
*entry
,
357 int (*func
)(const struct argp_option
*opt
,
358 const struct argp_option
*real
,
364 const struct argp_option
*opt
, *real
= entry
->opt
;
366 for (opt
= real
, nopts
= entry
->num
; nopts
> 0 && !val
; opt
++, nopts
--)
372 val
= (*func
)(opt
, real
, cookie
);
378 /* Iterator that returns true for the first short option. */
380 until_short (const struct argp_option
*opt
, const struct argp_option
*real
,
383 return oshort (opt
) ? opt
->key
: 0;
386 /* Returns the first valid short option in ENTRY, or 0 if there is none. */
388 hol_entry_first_short (const struct hol_entry
*entry
)
390 return hol_entry_short_iterate (entry
, until_short
, 0);
393 /* Returns the first valid long option in ENTRY, or 0 if there is none. */
395 hol_entry_first_long (const struct hol_entry
*entry
)
397 const struct argp_option
*opt
;
399 for (opt
= entry
->opt
, num
= entry
->num
; num
> 0; opt
++, num
--)
400 if (opt
->name
&& ovisible (opt
))
405 /* Returns the entry in HOL with the long option name NAME, or 0 if there is
407 static struct hol_entry
*
408 hol_find_entry (struct hol
*hol
, const char *name
)
410 struct hol_entry
*entry
= hol
->entries
;
411 unsigned num_entries
= hol
->num_entries
;
413 while (num_entries
-- > 0)
415 const struct argp_option
*opt
= entry
->opt
;
416 unsigned num_opts
= entry
->num
;
418 while (num_opts
-- > 0)
419 if (opt
->name
&& ovisible (opt
) && strcmp (opt
->name
, name
) == 0)
430 /* If an entry with the long option NAME occurs in HOL, set it's special
431 sort position to GROUP. */
433 hol_set_group (struct hol
*hol
, const char *name
, int group
)
435 struct hol_entry
*entry
= hol_find_entry (hol
, name
);
437 entry
->group
= group
;
440 /* Order by group: 0, 1, 2, ..., n, -m, ..., -2, -1.
441 EQ is what to return if GROUP1 and GROUP2 are the same. */
443 group_cmp (int group1
, int group2
, int eq
)
445 if (group1
== group2
)
447 else if ((group1
< 0 && group2
< 0) || (group1
>= 0 && group2
>= 0))
448 return group1
- group2
;
450 return group2
- group1
;
453 /* Compare clusters CL1 & CL2 by the order that they should appear in
456 hol_cluster_cmp (const struct hol_cluster
*cl1
, const struct hol_cluster
*cl2
)
458 /* If one cluster is deeper than the other, use its ancestor at the same
459 level, so that finding the common ancestor is straightforward. */
460 while (cl1
->depth
< cl2
->depth
)
462 while (cl2
->depth
< cl1
->depth
)
465 /* Now reduce both clusters to their ancestors at the point where both have
466 a common parent; these can be directly compared. */
467 while (cl1
->parent
!= cl2
->parent
)
468 cl1
= cl1
->parent
, cl2
= cl2
->parent
;
470 return group_cmp (cl1
->group
, cl2
->group
, cl2
->index
- cl1
->index
);
473 /* Return the ancestor of CL that's just below the root (i.e., has a parent
475 static struct hol_cluster
*
476 hol_cluster_base (struct hol_cluster
*cl
)
483 /* Return true if CL1 is a child of CL2. */
485 hol_cluster_is_child (const struct hol_cluster
*cl1
,
486 const struct hol_cluster
*cl2
)
488 while (cl1
&& cl1
!= cl2
)
493 /* Given the name of a OPTION_DOC option, modifies NAME to start at the tail
494 that should be used for comparisons, and returns true iff it should be
495 treated as a non-option. */
497 canon_doc_option (const char **name
)
500 /* Skip initial whitespace. */
501 while (isspace (*name
))
503 /* Decide whether this looks like an option (leading `-') or not. */
504 non_opt
= (**name
!= '-');
505 /* Skip until part of name used for sorting. */
506 while (**name
&& !isalnum (*name
))
511 /* Order ENTRY1 & ENTRY2 by the order which they should appear in a help
514 hol_entry_cmp (const struct hol_entry
*entry1
, const struct hol_entry
*entry2
)
516 /* The group numbers by which the entries should be ordered; if either is
517 in a cluster, then this is just the group within the cluster. */
518 int group1
= entry1
->group
, group2
= entry2
->group
;
520 if (entry1
->cluster
!= entry2
->cluster
)
521 /* The entries are not within the same cluster, so we can't compare them
522 directly, we have to use the appropiate clustering level too. */
523 if (! entry1
->cluster
)
524 /* ENTRY1 is at the `base level', not in a cluster, so we have to
525 compare it's group number with that of the base cluster in which
526 ENTRY2 resides. Note that if they're in the same group, the
527 clustered option always comes laster. */
528 return group_cmp (group1
, hol_cluster_base (entry2
->cluster
)->group
, -1);
529 else if (! entry2
->cluster
)
530 /* Likewise, but ENTRY2's not in a cluster. */
531 return group_cmp (hol_cluster_base (entry1
->cluster
)->group
, group2
, 1);
533 /* Both entries are in clusters, we can just compare the clusters. */
534 return hol_cluster_cmp (entry1
->cluster
, entry2
->cluster
);
535 else if (group1
== group2
)
536 /* The entries are both in the same cluster and group, so compare them
539 int short1
= hol_entry_first_short (entry1
);
540 int short2
= hol_entry_first_short (entry2
);
541 int doc1
= odoc (entry1
->opt
);
542 int doc2
= odoc (entry2
->opt
);
543 const char *long1
= hol_entry_first_long (entry1
);
544 const char *long2
= hol_entry_first_long (entry2
);
547 doc1
= canon_doc_option (&long1
);
549 doc2
= canon_doc_option (&long2
);
552 /* `documentation' options always follow normal options (or
553 documentation options that *look* like normal options). */
555 else if (!short1
&& !short2
&& long1
&& long2
)
556 /* Only long options. */
557 return __strcasecmp (long1
, long2
);
559 /* Compare short/short, long/short, short/long, using the first
560 character of long options. Entries without *any* valid
561 options (such as options with OPTION_HIDDEN set) will be put
562 first, but as they're not displayed, it doesn't matter where
565 char first1
= short1
? short1
: long1
? *long1
: 0;
566 char first2
= short2
? short2
: long2
? *long2
: 0;
567 int lower_cmp
= tolower (first1
) - tolower (first2
);
568 /* Compare ignoring case, except when the options are both the
569 same letter, in which case lower-case always comes first. */
570 return lower_cmp
? lower_cmp
: first2
- first1
;
574 /* Within the same cluster, but not the same group, so just compare
576 return group_cmp (group1
, group2
, 0);
579 /* Version of hol_entry_cmp with correct signature for qsort. */
581 hol_entry_qcmp (const void *entry1_v
, const void *entry2_v
)
583 return hol_entry_cmp (entry1_v
, entry2_v
);
586 /* Sort HOL by group and alphabetically by option name (with short options
587 taking precedence over long). Since the sorting is for display purposes
588 only, the shadowing of options isn't effected. */
590 hol_sort (struct hol
*hol
)
592 if (hol
->num_entries
> 0)
593 qsort (hol
->entries
, hol
->num_entries
, sizeof (struct hol_entry
),
597 /* Append MORE to HOL, destroying MORE in the process. Options in HOL shadow
598 any in MORE with the same name. */
600 hol_append (struct hol
*hol
, struct hol
*more
)
602 struct hol_cluster
**cl_end
= &hol
->clusters
;
604 /* Steal MORE's cluster list, and add it to the end of HOL's. */
606 cl_end
= &(*cl_end
)->next
;
607 *cl_end
= more
->clusters
;
611 if (more
->num_entries
> 0)
612 if (hol
->num_entries
== 0)
614 hol
->num_entries
= more
->num_entries
;
615 hol
->entries
= more
->entries
;
616 hol
->short_options
= more
->short_options
;
617 more
->num_entries
= 0; /* Mark MORE's fields as invalid. */
620 /* append the entries in MORE to those in HOL, taking care to only add
621 non-shadowed SHORT_OPTIONS values. */
626 unsigned num_entries
= hol
->num_entries
+ more
->num_entries
;
627 struct hol_entry
*entries
=
628 malloc (num_entries
* sizeof (struct hol_entry
));
629 unsigned hol_so_len
= strlen (hol
->short_options
);
630 char *short_options
=
631 malloc (hol_so_len
+ strlen (more
->short_options
) + 1);
633 memcpy (entries
, hol
->entries
,
634 hol
->num_entries
* sizeof (struct hol_entry
));
635 memcpy (entries
+ hol
->num_entries
, more
->entries
,
636 more
->num_entries
* sizeof (struct hol_entry
));
638 memcpy (short_options
, hol
->short_options
, hol_so_len
);
640 /* Fix up the short options pointers from HOL. */
641 for (e
= entries
, left
= hol
->num_entries
; left
> 0; e
++, left
--)
642 e
->short_options
+= (short_options
- hol
->short_options
);
644 /* Now add the short options from MORE, fixing up its entries too. */
645 so
= short_options
+ hol_so_len
;
646 more_so
= more
->short_options
;
647 for (left
= more
->num_entries
; left
> 0; e
++, left
--)
650 const struct argp_option
*opt
;
652 e
->short_options
= so
;
654 for (opts_left
= e
->num
, opt
= e
->opt
; opts_left
; opt
++, opts_left
--)
657 if (oshort (opt
) && ch
== opt
->key
)
658 /* The next short option in MORE_SO, CH, is from OPT. */
661 short_options
, short_options
+ hol_so_len
))
662 /* The short option CH isn't shadowed by HOL's options,
663 so add it to the sum. */
673 free (hol
->short_options
);
675 hol
->entries
= entries
;
676 hol
->num_entries
= num_entries
;
677 hol
->short_options
= short_options
;
683 /* Inserts enough spaces to make sure STREAM is at column COL. */
685 indent_to (argp_fmtstream_t stream
, unsigned col
)
687 int needed
= col
- __argp_fmtstream_point (stream
);
689 __argp_fmtstream_putc (stream
, ' ');
692 /* If the option REAL has an argument, we print it in using the printf
693 format REQ_FMT or OPT_FMT depending on whether it's a required or
694 optional argument. */
696 arg (const struct argp_option
*real
, const char *req_fmt
, const char *opt_fmt
,
697 argp_fmtstream_t stream
)
700 if (real
->flags
& OPTION_ARG_OPTIONAL
)
701 __argp_fmtstream_printf (stream
, opt_fmt
, _(real
->arg
));
703 __argp_fmtstream_printf (stream
, req_fmt
, _(real
->arg
));
706 /* Helper functions for hol_entry_help. */
708 /* Some state used while printing a help entry (used to communicate with
709 helper functions). See the doc for hol_entry_help for more info, as most
710 of the fields are copied from its arguments. */
713 const struct hol_entry
*entry
;
714 argp_fmtstream_t stream
;
715 struct hol_entry
**prev_entry
;
718 int first
; /* True if nothing's been printed so far. */
721 /* Prints STR as a header line, with the margin lines set appropiately, and
722 notes the fact that groups should be separated with a blank line. Note
723 that the previous wrap margin isn't restored, but the left margin is reset
726 print_header (const char *str
, struct pentry_state
*st
)
730 if (st
->prev_entry
&& *st
->prev_entry
)
731 __argp_fmtstream_putc (st
->stream
, '\n'); /* Precede with a blank line. */
732 indent_to (st
->stream
, HEADER_COL
);
733 __argp_fmtstream_set_lmargin (st
->stream
, HEADER_COL
);
734 __argp_fmtstream_set_wmargin (st
->stream
, HEADER_COL
);
735 __argp_fmtstream_puts (st
->stream
, str
);
736 __argp_fmtstream_set_lmargin (st
->stream
, 0);
740 *st
->sep_groups
= 1; /* Separate subsequent groups. */
743 /* Inserts a comma if this isn't the first item on the line, and then makes
744 sure we're at least to column COL. Also clears FIRST. */
746 comma (unsigned col
, struct pentry_state
*st
)
750 const struct hol_entry
*pe
= st
->prev_entry
? *st
->prev_entry
: 0;
751 const struct hol_cluster
*cl
= st
->entry
->cluster
;
753 if (st
->sep_groups
&& *st
->sep_groups
754 && pe
&& st
->entry
->group
!= pe
->group
)
755 __argp_fmtstream_putc (st
->stream
, '\n');
757 if (pe
&& cl
&& pe
->cluster
!= cl
&& cl
->header
&& *cl
->header
758 && !hol_cluster_is_child (pe
->cluster
, cl
))
759 /* If we're changing clusters, then this must be the start of the
760 ENTRY's cluster unless that is an ancestor of the previous one
761 (in which case we had just popped into a sub-cluster for a bit).
762 If so, then print the cluster's header line. */
764 int old_wm
= __argp_fmtstream_wmargin (st
->stream
);
765 print_header (cl
->header
, st
);
766 __argp_fmtstream_putc (st
->stream
, '\n');
767 __argp_fmtstream_set_wmargin (st
->stream
, old_wm
);
773 __argp_fmtstream_puts (st
->stream
, ", ");
775 indent_to (st
->stream
, col
);
778 /* Print help for ENTRY to STREAM. *PREV_ENTRY should contain the last entry
779 printed before this, or null if it's the first, and if ENTRY is in a
780 different group, and *SEP_GROUPS is true, then a blank line will be
781 printed before any output. *SEP_GROUPS is also set to true if a
782 user-specified group header is printed. */
784 hol_entry_help (struct hol_entry
*entry
, argp_fmtstream_t stream
,
785 struct hol_entry
**prev_entry
, int *sep_groups
)
788 const struct argp_option
*real
= entry
->opt
, *opt
;
789 char *so
= entry
->short_options
;
790 int old_lm
= __argp_fmtstream_set_lmargin (stream
, 0);
791 int old_wm
= __argp_fmtstream_wmargin (stream
);
792 struct pentry_state pest
= { entry
, stream
, prev_entry
, sep_groups
, 1 };
794 /* First emit short options. */
795 __argp_fmtstream_set_wmargin (stream
, SHORT_OPT_COL
); /* For truly bizarre cases. */
796 for (opt
= real
, num
= entry
->num
; num
> 0; opt
++, num
--)
797 if (oshort (opt
) && opt
->key
== *so
)
798 /* OPT has a valid (non shadowed) short option. */
802 comma (SHORT_OPT_COL
, &pest
);
803 __argp_fmtstream_putc (stream
, '-');
804 __argp_fmtstream_putc (stream
, *so
);
805 arg (real
, " %s", "[%s]", stream
);
810 /* Now, long options. */
812 /* Really a `documentation' option. */
814 __argp_fmtstream_set_wmargin (stream
, DOC_OPT_COL
);
815 for (opt
= real
, num
= entry
->num
; num
> 0; opt
++, num
--)
816 if (opt
->name
&& ovisible (opt
))
818 comma (DOC_OPT_COL
, &pest
);
819 /* Calling gettext here isn't quite right, since sorting will
820 have been done on the original; but documentation options
821 should be pretty rare anyway... */
822 __argp_fmtstream_puts (stream
, _(opt
->name
));
826 /* A realy long option. */
828 __argp_fmtstream_set_wmargin (stream
, LONG_OPT_COL
);
829 for (opt
= real
, num
= entry
->num
; num
> 0; opt
++, num
--)
830 if (opt
->name
&& ovisible (opt
))
832 comma (LONG_OPT_COL
, &pest
);
833 __argp_fmtstream_printf (stream
, "--%s", opt
->name
);
834 arg (real
, "=%s", "[=%s]", stream
);
838 __argp_fmtstream_set_lmargin (stream
, 0);
840 /* Didn't print any switches, what's up? */
841 if (!oshort (real
) && !real
->name
&& real
->doc
)
842 /* This is a group header, print it nicely. */
843 print_header (real
->doc
, &pest
);
845 /* Just a totally shadowed option or null header; print nothing. */
846 goto cleanup
; /* Just return, after cleaning up. */
848 /* Now the option documentation. */
850 unsigned col
= __argp_fmtstream_point (stream
);
851 const char *doc
= real
->doc
;
853 __argp_fmtstream_set_lmargin (stream
, OPT_DOC_COL
);
854 __argp_fmtstream_set_wmargin (stream
, OPT_DOC_COL
);
856 if (col
> OPT_DOC_COL
+ 3)
857 __argp_fmtstream_putc (stream
, '\n');
858 else if (col
>= OPT_DOC_COL
)
859 __argp_fmtstream_puts (stream
, " ");
861 indent_to (stream
, OPT_DOC_COL
);
863 __argp_fmtstream_puts (stream
, doc
);
865 /* Reset the left margin. */
866 __argp_fmtstream_set_lmargin (stream
, 0);
869 __argp_fmtstream_putc (stream
, '\n');
875 __argp_fmtstream_set_lmargin (stream
, old_lm
);
876 __argp_fmtstream_set_wmargin (stream
, old_wm
);
879 /* Output a long help message about the options in HOL to STREAM. */
881 hol_help (struct hol
*hol
, argp_fmtstream_t stream
)
884 struct hol_entry
*entry
;
885 struct hol_entry
*last_entry
= 0;
886 int sep_groups
= 0; /* True if we should separate different
887 sections with blank lines. */
888 for (entry
= hol
->entries
, num
= hol
->num_entries
; num
> 0; entry
++, num
--)
889 hol_entry_help (entry
, stream
, &last_entry
, &sep_groups
);
892 /* Helper functions for hol_usage. */
894 /* If OPT is a short option without an arg, append its key to the string
895 pointer pointer to by COOKIE, and advance the pointer. */
897 add_argless_short_opt (const struct argp_option
*opt
,
898 const struct argp_option
*real
,
901 char **snao_end
= cookie
;
902 if (! (opt
->arg
|| real
->arg
))
903 *(*snao_end
)++ = opt
->key
;
907 /* If OPT is a short option with an arg, output a usage entry for it to the
908 stream pointed at by COOKIE. */
910 usage_argful_short_opt (const struct argp_option
*opt
,
911 const struct argp_option
*real
,
914 argp_fmtstream_t stream
= cookie
;
915 const char *arg
= opt
->arg
;
924 if ((opt
->flags
| real
->flags
) & OPTION_ARG_OPTIONAL
)
925 __argp_fmtstream_printf (stream
, " [-%c[%s]]", opt
->key
, arg
);
928 /* Manually do line wrapping so that it (probably) won't
929 get wrapped at the embedded space. */
930 if (__argp_fmtstream_point (stream
) + 6 + strlen (arg
)
931 >= __argp_fmtstream_rmargin (stream
))
932 __argp_fmtstream_putc (stream
, '\n');
934 __argp_fmtstream_putc (stream
, ' ');
935 __argp_fmtstream_printf (stream
, "[-%c %s]", opt
->key
, arg
);
942 /* Output a usage entry for the long option opt to the stream pointed at by
945 usage_long_opt (const struct argp_option
*opt
,
946 const struct argp_option
*real
,
949 argp_fmtstream_t stream
= cookie
;
950 const char *arg
= opt
->arg
;
958 if ((opt
->flags
| real
->flags
) & OPTION_ARG_OPTIONAL
)
959 __argp_fmtstream_printf (stream
, " [--%s[=%s]]", opt
->name
, arg
);
961 __argp_fmtstream_printf (stream
, " [--%s=%s]", opt
->name
, arg
);
964 __argp_fmtstream_printf (stream
, " [--%s]", opt
->name
);
969 /* Print a short usage description for the arguments in HOL to STREAM. */
971 hol_usage (struct hol
*hol
, argp_fmtstream_t stream
)
973 if (hol
->num_entries
> 0)
976 struct hol_entry
*entry
;
977 char *short_no_arg_opts
= alloca (strlen (hol
->short_options
) + 1);
978 char *snao_end
= short_no_arg_opts
;
980 /* First we put a list of short options without arguments. */
981 for (entry
= hol
->entries
, nentries
= hol
->num_entries
983 ; entry
++, nentries
--)
984 hol_entry_short_iterate (entry
, add_argless_short_opt
, &snao_end
);
985 if (snao_end
> short_no_arg_opts
)
988 __argp_fmtstream_printf (stream
, " [-%s]", short_no_arg_opts
);
991 /* Now a list of short options *with* arguments. */
992 for (entry
= hol
->entries
, nentries
= hol
->num_entries
994 ; entry
++, nentries
--)
995 hol_entry_short_iterate (entry
, usage_argful_short_opt
, stream
);
997 /* Finally, a list of long options (whew!). */
998 for (entry
= hol
->entries
, nentries
= hol
->num_entries
1000 ; entry
++, nentries
--)
1001 hol_entry_long_iterate (entry
, usage_long_opt
, stream
);
1005 /* Make a HOL containing all levels of options in ARGP. CLUSTER is the
1006 cluster in which ARGP's entries should be clustered, or 0. */
1008 argp_hol (const struct argp
*argp
, struct hol_cluster
*cluster
)
1010 const struct argp_child
*child
= argp
->children
;
1011 struct hol
*hol
= make_hol (argp
->options
, cluster
);
1015 struct hol_cluster
*child_cluster
=
1016 ((child
->group
|| child
->header
)
1017 /* Put CHILD->argp within its own cluster. */
1018 ? hol_add_cluster (hol
, child
->group
, child
->header
,
1019 child
- argp
->children
, cluster
)
1020 /* Just merge it into the parent's cluster. */
1022 hol_append (hol
, argp_hol (child
->argp
, child_cluster
)) ;
1028 /* Calculate how many different levels with alternative args strings exist in
1031 argp_args_levels (const struct argp
*argp
)
1034 const struct argp_child
*child
= argp
->children
;
1036 if (argp
->args_doc
&& strchr (argp
->args_doc
, '\n'))
1041 levels
+= argp_args_levels ((child
++)->argp
);
1046 /* Print all the non-option args documented in ARGP to STREAM. Any output is
1047 preceded by a space. LEVELS is a pointer to a byte vector the length
1048 returned by argp_args_levels; it should be initialized to zero, and
1049 updated by this routine for the next call if ADVANCE is true. True is
1050 returned as long as there are more patterns to output. */
1052 argp_args_usage (const struct argp
*argp
, char **levels
, int advance
,
1053 argp_fmtstream_t stream
)
1055 char *our_level
= *levels
;
1057 const struct argp_child
*child
= argp
->children
;
1058 const char *doc
= _(argp
->args_doc
), *nl
= 0;
1062 nl
= strchr (doc
, '\n');
1064 /* This is a `multi-level' args doc; advance to the correct position
1065 as determined by our state in LEVELS, and update LEVELS. */
1069 for (i
= 0; i
< *our_level
; i
++)
1070 doc
= nl
+ 1, nl
= strchr (doc
, '\n');
1074 nl
= doc
+ strlen (doc
);
1076 /* Manually do line wrapping so that it (probably) won't get wrapped at
1077 any embedded spaces. */
1078 if (__argp_fmtstream_point (stream
) + 1 + nl
- doc
1079 >= __argp_fmtstream_rmargin (stream
))
1080 __argp_fmtstream_putc (stream
, '\n');
1082 __argp_fmtstream_putc (stream
, ' ');
1084 __argp_fmtstream_write (stream
, doc
, nl
- doc
);
1089 advance
= !argp_args_usage ((child
++)->argp
, levels
, advance
, stream
);
1091 if (advance
&& multiple
)
1092 /* Need to increment our level. */
1094 /* There's more we can do here. */
1097 advance
= 0; /* Our parent shouldn't advance also. */
1099 else if (*our_level
> 0)
1100 /* We had multiple levels, but used them up; reset to zero. */
1106 /* Print the documentation for ARGP to STREAM; if POST is false, then
1107 everything preceeding a `\v' character in the documentation strings (or
1108 the whole string, for those with none) is printed, otherwise, everything
1109 following the `\v' character (nothing for strings without). Each separate
1110 bit of documentation is separated a blank line, and if PRE_BLANK is true,
1111 then the first is as well. If FIRST_ONLY is true, only the first
1112 occurance is output. Returns true if anything was output. */
1114 argp_doc (const struct argp
*argp
, int post
, int pre_blank
, int first_only
,
1115 argp_fmtstream_t stream
)
1117 const struct argp_child
*child
= argp
->children
;
1118 const char *doc
= argp
->doc
;
1123 char *vt
= strchr (doc
, '\v');
1125 if (pre_blank
&& (vt
|| !post
))
1126 __argp_fmtstream_putc (stream
, '\n');
1130 __argp_fmtstream_puts (stream
, vt
+ 1);
1132 __argp_fmtstream_write (stream
, doc
, vt
- doc
);
1135 __argp_fmtstream_puts (stream
, doc
);
1136 if (__argp_fmtstream_point (stream
) > __argp_fmtstream_lmargin (stream
))
1137 __argp_fmtstream_putc (stream
, '\n');
1142 while (child
->argp
&& !(first_only
&& anything
))
1144 argp_doc ((child
++)->argp
, post
, anything
|| pre_blank
, first_only
,
1150 /* Output a usage message for ARGP to STREAM. FLAGS are from the set
1151 ARGP_HELP_*. NAME is what to use wherever a `program name' is needed. */
1152 void __argp_help (const struct argp
*argp
, FILE *stream
,
1153 unsigned flags
, char *name
)
1155 int anything
= 0; /* Whether we've output anything. */
1156 struct hol
*hol
= 0;
1157 argp_fmtstream_t fs
;
1162 fs
= __argp_make_fmtstream (stream
, 0, RMARGIN
, 0);
1166 if (flags
& (ARGP_HELP_USAGE
| ARGP_HELP_SHORT_USAGE
| ARGP_HELP_LONG
))
1168 hol
= argp_hol (argp
, 0);
1170 /* If present, these options always come last. */
1171 hol_set_group (hol
, "help", -1);
1172 hol_set_group (hol
, "version", -1);
1177 if (flags
& (ARGP_HELP_USAGE
| ARGP_HELP_SHORT_USAGE
))
1178 /* Print a short `Usage:' message. */
1180 int first_pattern
= 1, more_patterns
;
1181 size_t num_pattern_levels
= argp_args_levels (argp
);
1182 char *pattern_levels
= alloca (num_pattern_levels
);
1184 memset (pattern_levels
, 0, num_pattern_levels
);
1189 int old_wm
= __argp_fmtstream_set_wmargin (fs
, USAGE_INDENT
);
1190 char *levels
= pattern_levels
;
1192 __argp_fmtstream_printf (fs
, "%s %s",
1193 first_pattern
? "Usage:" : " or: ", name
);
1195 /* We set the lmargin as well as the wmargin, because hol_usage
1196 manually wraps options with newline to avoid annoying breaks. */
1197 old_lm
= __argp_fmtstream_set_lmargin (fs
, USAGE_INDENT
);
1199 if (flags
& ARGP_HELP_SHORT_USAGE
)
1200 /* Just show where the options go. */
1202 if (hol
->num_entries
> 0)
1203 __argp_fmtstream_puts (fs
, " [OPTION...]");
1206 /* Actually print the options. */
1208 hol_usage (hol
, fs
);
1209 flags
|= ARGP_HELP_SHORT_USAGE
; /* But only do so once. */
1212 more_patterns
= argp_args_usage (argp
, &levels
, 1, fs
);
1214 __argp_fmtstream_set_wmargin (fs
, old_wm
);
1215 __argp_fmtstream_set_lmargin (fs
, old_lm
);
1217 __argp_fmtstream_putc (fs
, '\n');
1222 while (more_patterns
);
1225 if (flags
& ARGP_HELP_PRE_DOC
)
1226 anything
|= argp_doc (argp
, 0, 0, 1, fs
);
1228 if (flags
& ARGP_HELP_SEE
)
1230 __argp_fmtstream_printf (fs
,
1231 "Try `%s --help' or `%s --usage' for more information.\n",
1236 if (flags
& ARGP_HELP_LONG
)
1237 /* Print a long, detailed help message. */
1239 /* Print info about all the options. */
1240 if (hol
->num_entries
> 0)
1243 __argp_fmtstream_putc (fs
, '\n');
1249 if (flags
& ARGP_HELP_POST_DOC
)
1250 /* Print any documentation strings at the end. */
1251 anything
|= argp_doc (argp
, 1, anything
, 0, fs
);
1253 if ((flags
& ARGP_HELP_BUG_ADDR
) && argp_program_bug_address
)
1256 __argp_fmtstream_putc (fs
, '\n');
1257 __argp_fmtstream_printf (fs
, "Report bugs to %s.\n", argp_program_bug_address
);
1264 __argp_fmtstream_free (fs
);
1267 weak_alias (__argp_help
, argp_help
)
1270 /* Output, if appropriate, a usage message for STATE to STREAM. FLAGS are
1271 from the set ARGP_HELP_*. */
1273 __argp_state_help (struct argp_state
*state
, FILE *stream
, unsigned flags
)
1275 if ((!state
|| ! (state
->flags
& ARGP_NO_ERRS
)) && stream
)
1277 if (state
&& (state
->flags
& ARGP_LONG_ONLY
))
1278 flags
|= ARGP_HELP_LONG_ONLY
;
1280 __argp_help (state
? state
->argp
: 0, stream
, flags
,
1281 state
? state
->name
: program_invocation_name
);
1283 if (!state
|| ! (state
->flags
& ARGP_NO_EXIT
))
1285 if (flags
& ARGP_HELP_EXIT_ERR
)
1287 if (flags
& ARGP_HELP_EXIT_OK
)
1293 weak_alias (__argp_state_help
, argp_state_help
)
1296 /* If appropriate, print the printf string FMT and following args, preceded
1297 by the program name and `:', to stderr, and followed by a `Try ... --help'
1298 message, then exit (1). */
1300 __argp_error (struct argp_state
*state
, const char *fmt
, ...)
1302 if (!state
|| !(state
->flags
& ARGP_NO_ERRS
))
1304 FILE *stream
= state
? state
->err_stream
: stderr
;
1310 fputs (state
? state
->name
: program_invocation_name
, stream
);
1315 vfprintf (stream
, fmt
, ap
);
1318 putc ('\n', stream
);
1320 __argp_state_help (state
, stream
, ARGP_HELP_STD_ERR
);
1325 weak_alias (__argp_error
, argp_error
)
1328 /* Similar to the standard gnu error-reporting function error(), but will
1329 respect the ARGP_NO_EXIT and ARGP_NO_ERRS flags in STATE, and will print
1330 to STATE->err_stream. This is useful for argument parsing code that is
1331 shared between program startup (when exiting is desired) and runtime
1332 option parsing (when typically an error code is returned instead). The
1333 difference between this function and argp_error is that the latter is for
1334 *parsing errors*, and the former is for other problems that occur during
1335 parsing but don't reflect a (syntactic) problem with the input. */
1337 __argp_failure (struct argp_state
*state
, int status
, int errnum
,
1338 const char *fmt
, ...)
1340 if (!state
|| !(state
->flags
& ARGP_NO_ERRS
))
1342 FILE *stream
= state
? state
->err_stream
: stderr
;
1346 fputs (state
? state
->name
: program_invocation_name
, stream
);
1356 vfprintf (stream
, fmt
, ap
);
1364 fputs (strerror (errnum
), stream
);
1367 putc ('\n', stream
);
1375 weak_alias (__argp_failure
, argp_failure
)