]>
Commit | Line | Data |
---|---|---|
b0de3e9e UD |
1 | @node Argp, Suboptions, Getopt, Parsing Program Arguments |
2 | @need 5000 | |
3 | @section Parsing Program Options with Argp | |
4 | @cindex argp (program argument parser) | |
5 | @cindex argument parsing with argp | |
6 | @cindex option parsing with argp | |
7 | ||
f7364247 UD |
8 | @dfn{Argp} is an interface for parsing unix-style argument vectors. |
9 | @xref{Program Arguments}. | |
b0de3e9e | 10 | |
f7364247 UD |
11 | Argp provides features unavailable in the more commonly used |
12 | @code{getopt} interface. These features include automatically producing | |
13 | output in response to the @samp{--help} and @samp{--version} options, as | |
14 | described in the GNU coding standards. Using argp makes it less likely | |
15 | that programmers will neglect to implement these additional options or | |
16 | keep them up to date. | |
b0de3e9e UD |
17 | |
18 | Argp also provides the ability to merge several independently defined | |
f7364247 UD |
19 | option parsers into one, mediating conflicts between them and making the |
20 | result appear seamless. A library can export an argp option parser that | |
21 | user programs might employ in conjunction with their own option parsers, | |
22 | resulting in less work for the user programs. Some programs may use only | |
23 | argument parsers exported by libraries, thereby achieving consistent and | |
24 | efficient option-parsing for abstractions implemented by the libraries. | |
b0de3e9e UD |
25 | |
26 | @pindex argp.h | |
27 | The header file @file{<argp.h>} should be included to use argp. | |
28 | ||
29 | @subsection The @code{argp_parse} Function | |
30 | ||
f7364247 UD |
31 | The main interface to argp is the @code{argp_parse} function. In many |
32 | cases, calling @code{argp_parse} is the only argument-parsing code | |
33 | needed in @code{main}. | |
34 | @xref{Program Arguments}. | |
b0de3e9e | 35 | |
29fe4d0d | 36 | @deftypefun {error_t} argp_parse (const struct argp *@var{argp}, int @var{argc}, char **@var{argv}, unsigned @var{flags}, int *@var{arg_index}, void *@var{input}) |
d08a7e4c | 37 | @standards{GNU, argp.h} |
4a16c662 AO |
38 | @safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtslocale{} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} |
39 | @c Optionally alloca()tes standard help options, initializes the parser, | |
40 | @c then parses individual args in a loop, and then finalizes. | |
41 | @c parser_init | |
42 | @c calc_sizes ok | |
43 | @c option_is_end ok | |
44 | @c malloc @ascuheap @acsmem | |
45 | @c parser_convert @mtslocale | |
46 | @c convert_options @mtslocale | |
47 | @c option_is_end ok | |
48 | @c option_is_short ok | |
49 | @c isprint, but locale may change within the loop | |
50 | @c find_long_option ok | |
51 | @c group_parse | |
52 | @c group->parser (from argp->parser) | |
53 | @c parser_parse_next | |
54 | @c getopt_long(_only)_r many issues, same as non_r minus @mtasurace | |
55 | @c parser_parse_arg | |
56 | @c group_parse dup | |
57 | @c parser_parse_opt | |
58 | @c group_parse dup | |
59 | @c argp_error dup @mtasurace:argpbuf @mtsenv @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock | |
60 | @c dgettext (bad key error) dup @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem | |
61 | @c parser_finalize | |
62 | @c group_parse | |
63 | @c fprintf dup @mtslocale @asucorrupt @aculock @acucorrupt [no @ascuheap @acsmem] | |
64 | @c dgettext dup @mtsenv @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsfd @acsmem | |
65 | @c arg_state_help | |
66 | @c free dup @ascuhelp @acsmem | |
fed8f7f7 | 67 | The @code{argp_parse} function parses the arguments in @var{argv}, of |
f7364247 | 68 | length @var{argc}, using the argp parser @var{argp}. @xref{Argp |
eb55f5c2 RM |
69 | Parsers}. Passing a null pointer for @var{argp} is the same as using |
70 | a @code{struct argp} containing all zeros. | |
f7364247 | 71 | |
eb55f5c2 RM |
72 | @var{flags} is a set of flag bits that modify the parsing behavior. |
73 | @xref{Argp Flags}. @var{input} is passed through to the argp parser | |
74 | @var{argp}, and has meaning defined by @var{argp}. A typical usage is | |
75 | to pass a pointer to a structure which is used for specifying | |
f7364247 | 76 | parameters to the parser and passing back the results. |
b0de3e9e UD |
77 | |
78 | Unless the @code{ARGP_NO_EXIT} or @code{ARGP_NO_HELP} flags are included | |
79 | in @var{flags}, calling @code{argp_parse} may result in the program | |
f7364247 UD |
80 | exiting. This behavior is true if an error is detected, or when an |
81 | unknown option is encountered. @xref{Program Termination}. | |
b0de3e9e | 82 | |
faf2289f | 83 | If @var{arg_index} is non-null, the index of the first unparsed option |
f7364247 | 84 | in @var{argv} is returned as a value. |
29094e48 | 85 | |
faf2289f | 86 | The return value is zero for successful parsing, or an error code |
f7364247 UD |
87 | (@pxref{Error Codes}) if an error is detected. Different argp parsers |
88 | may return arbitrary error codes, but the standard error codes are: | |
89 | @code{ENOMEM} if a memory allocation error occurred, or @code{EINVAL} if | |
90 | an unknown option or option argument is encountered. | |
b0de3e9e UD |
91 | @end deftypefun |
92 | ||
93 | @menu | |
94 | * Globals: Argp Global Variables. Global argp parameters. | |
95 | * Parsers: Argp Parsers. Defining parsers for use with @code{argp_parse}. | |
96 | * Flags: Argp Flags. Flags that modify the behavior of @code{argp_parse}. | |
97 | * Help: Argp Help. Printing help messages when not parsing. | |
98 | * Examples: Argp Examples. Simple examples of programs using argp. | |
99 | * Customization: Argp User Customization. | |
100 | Users may control the @samp{--help} output format. | |
101 | @end menu | |
102 | ||
103 | @node Argp Global Variables, Argp Parsers, , Argp | |
104 | @subsection Argp Global Variables | |
105 | ||
f7364247 UD |
106 | These variables make it easy for user programs to implement the |
107 | @samp{--version} option and provide a bug-reporting address in the | |
108 | @samp{--help} output. These are implemented in argp by default. | |
b0de3e9e | 109 | |
b0de3e9e | 110 | @deftypevar {const char *} argp_program_version |
d08a7e4c | 111 | @standards{GNU, argp.h} |
b0de3e9e | 112 | If defined or set by the user program to a non-zero value, then a |
f7364247 UD |
113 | @samp{--version} option is added when parsing with @code{argp_parse}, |
114 | which will print the @samp{--version} string followed by a newline and | |
115 | exit. The exception to this is if the @code{ARGP_NO_EXIT} flag is used. | |
b0de3e9e UD |
116 | @end deftypevar |
117 | ||
b0de3e9e | 118 | @deftypevar {const char *} argp_program_bug_address |
d08a7e4c | 119 | @standards{GNU, argp.h} |
b0de3e9e | 120 | If defined or set by the user program to a non-zero value, |
f7364247 UD |
121 | @code{argp_program_bug_address} should point to a string that will be |
122 | printed at the end of the standard output for the @samp{--help} option, | |
123 | embedded in a sentence that says @samp{Report bugs to @var{address}.}. | |
b0de3e9e UD |
124 | @end deftypevar |
125 | ||
126 | @need 1500 | |
b0de3e9e | 127 | @defvar argp_program_version_hook |
d08a7e4c | 128 | @standards{GNU, argp.h} |
f7364247 UD |
129 | If defined or set by the user program to a non-zero value, a |
130 | @samp{--version} option is added when parsing with @code{arg_parse}, | |
131 | which prints the program version and exits with a status of zero. This | |
132 | is not the case if the @code{ARGP_NO_HELP} flag is used. If the | |
133 | @code{ARGP_NO_EXIT} flag is set, the exit behavior of the program is | |
134 | suppressed or modified, as when the argp parser is going to be used by | |
135 | other programs. | |
136 | ||
137 | It should point to a function with this type of signature: | |
b0de3e9e UD |
138 | |
139 | @smallexample | |
140 | void @var{print-version} (FILE *@var{stream}, struct argp_state *@var{state}) | |
141 | @end smallexample | |
142 | ||
143 | @noindent | |
144 | @xref{Argp Parsing State}, for an explanation of @var{state}. | |
145 | ||
f7364247 UD |
146 | This variable takes precedence over @code{argp_program_version}, and is |
147 | useful if a program has version information not easily expressed in a | |
148 | simple string. | |
b0de3e9e UD |
149 | @end defvar |
150 | ||
b0de3e9e | 151 | @deftypevar error_t argp_err_exit_status |
d08a7e4c | 152 | @standards{GNU, argp.h} |
f7364247 UD |
153 | This is the exit status used when argp exits due to a parsing error. If |
154 | not defined or set by the user program, this defaults to: | |
b0de3e9e UD |
155 | @code{EX_USAGE} from @file{<sysexits.h>}. |
156 | @end deftypevar | |
157 | ||
158 | @node Argp Parsers, Argp Flags, Argp Global Variables, Argp | |
159 | @subsection Specifying Argp Parsers | |
160 | ||
161 | The first argument to the @code{argp_parse} function is a pointer to a | |
f7364247 | 162 | @code{struct argp}, which is known as an @dfn{argp parser}: |
b0de3e9e | 163 | |
b0de3e9e | 164 | @deftp {Data Type} {struct argp} |
d08a7e4c | 165 | @standards{GNU, argp.h} |
b0de3e9e UD |
166 | This structure specifies how to parse a given set of options and |
167 | arguments, perhaps in conjunction with other argp parsers. It has the | |
168 | following fields: | |
169 | ||
170 | @table @code | |
171 | @item const struct argp_option *options | |
172 | A pointer to a vector of @code{argp_option} structures specifying which | |
173 | options this argp parser understands; it may be zero if there are no | |
174 | options at all. @xref{Argp Option Vectors}. | |
175 | ||
176 | @item argp_parser_t parser | |
177 | A pointer to a function that defines actions for this parser; it is | |
178 | called for each option parsed, and at other well-defined points in the | |
f7364247 UD |
179 | parsing process. A value of zero is the same as a pointer to a function |
180 | that always returns @code{ARGP_ERR_UNKNOWN}. @xref{Argp Parser | |
181 | Functions}. | |
b0de3e9e UD |
182 | |
183 | @item const char *args_doc | |
f7364247 UD |
184 | If non-zero, a string describing what non-option arguments are called by |
185 | this parser. This is only used to print the @samp{Usage:} message. If | |
186 | it contains newlines, the strings separated by them are considered | |
187 | alternative usage patterns and printed on separate lines. Lines after | |
188 | the first are prefixed by @samp{ or: } instead of @samp{Usage:}. | |
b0de3e9e UD |
189 | |
190 | @item const char *doc | |
191 | If non-zero, a string containing extra text to be printed before and | |
192 | after the options in a long help message, with the two sections | |
193 | separated by a vertical tab (@code{'\v'}, @code{'\013'}) character. By | |
194 | convention, the documentation before the options is just a short string | |
f7364247 UD |
195 | explaining what the program does. Documentation printed after the |
196 | options describe behavior in more detail. | |
b0de3e9e UD |
197 | |
198 | @item const struct argp_child *children | |
f45e45a3 | 199 | A pointer to a vector of @code{argp_child} structures. This pointer |
f7364247 UD |
200 | specifies which additional argp parsers should be combined with this |
201 | one. @xref{Argp Children}. | |
b0de3e9e UD |
202 | |
203 | @item char *(*help_filter)(int @var{key}, const char *@var{text}, void *@var{input}) | |
f7364247 | 204 | If non-zero, a pointer to a function that filters the output of help |
b0de3e9e | 205 | messages. @xref{Argp Help Filtering}. |
01f8c9f2 AJ |
206 | |
207 | @item const char *argp_domain | |
208 | If non-zero, the strings used in the argp library are translated using | |
f7364247 UD |
209 | the domain described by this string. If zero, the current default domain |
210 | is used. | |
01f8c9f2 | 211 | |
b0de3e9e UD |
212 | @end table |
213 | @end deftp | |
214 | ||
f7364247 UD |
215 | Of the above group, @code{options}, @code{parser}, @code{args_doc}, and |
216 | the @code{doc} fields are usually all that are needed. If an argp | |
217 | parser is defined as an initialized C variable, only the fields used | |
218 | need be specified in the initializer. The rest will default to zero due | |
219 | to the way C structure initialization works. This design is exploited in | |
220 | most argp structures; the most-used fields are grouped near the | |
221 | beginning, the unused fields left unspecified. | |
b0de3e9e UD |
222 | |
223 | @menu | |
224 | * Options: Argp Option Vectors. Specifying options in an argp parser. | |
225 | * Argp Parser Functions:: Defining actions for an argp parser. | |
226 | * Children: Argp Children. Combining multiple argp parsers. | |
227 | * Help Filtering: Argp Help Filtering. Customizing help output for an argp parser. | |
228 | @end menu | |
229 | ||
230 | @node Argp Option Vectors, Argp Parser Functions, Argp Parsers, Argp Parsers | |
231 | @subsection Specifying Options in an Argp Parser | |
232 | ||
233 | The @code{options} field in a @code{struct argp} points to a vector of | |
234 | @code{struct argp_option} structures, each of which specifies an option | |
f7364247 UD |
235 | that the argp parser supports. Multiple entries may be used for a single |
236 | option provided it has multiple names. This should be terminated by an | |
237 | entry with zero in all fields. Note that when using an initialized C | |
238 | array for options, writing @code{@{ 0 @}} is enough to achieve this. | |
b0de3e9e | 239 | |
b0de3e9e | 240 | @deftp {Data Type} {struct argp_option} |
d08a7e4c | 241 | @standards{GNU, argp.h} |
b0de3e9e | 242 | This structure specifies a single option that an argp parser |
f7364247 UD |
243 | understands, as well as how to parse and document that option. It has |
244 | the following fields: | |
b0de3e9e UD |
245 | |
246 | @table @code | |
247 | @item const char *name | |
248 | The long name for this option, corresponding to the long option | |
f7364247 UD |
249 | @samp{--@var{name}}; this field may be zero if this option @emph{only} |
250 | has a short name. To specify multiple names for an option, additional | |
251 | entries may follow this one, with the @code{OPTION_ALIAS} flag | |
252 | set. @xref{Argp Option Flags}. | |
b0de3e9e UD |
253 | |
254 | @item int key | |
f7364247 UD |
255 | The integer key provided by the current option to the option parser. If |
256 | @var{key} has a value that is a printable @sc{ascii} character (i.e., | |
257 | @code{isascii (@var{key})} is true), it @emph{also} specifies a short | |
258 | option @samp{-@var{char}}, where @var{char} is the @sc{ascii} character | |
259 | with the code @var{key}. | |
b0de3e9e UD |
260 | |
261 | @item const char *arg | |
262 | If non-zero, this is the name of an argument associated with this | |
263 | option, which must be provided (e.g., with the | |
264 | @samp{--@var{name}=@var{value}} or @samp{-@var{char} @var{value}} | |
f7364247 UD |
265 | syntaxes), unless the @code{OPTION_ARG_OPTIONAL} flag (@pxref{Argp |
266 | Option Flags}) is set, in which case it @emph{may} be provided. | |
b0de3e9e UD |
267 | |
268 | @item int flags | |
f7364247 | 269 | Flags associated with this option, some of which are referred to above. |
b0de3e9e UD |
270 | @xref{Argp Option Flags}. |
271 | ||
272 | @item const char *doc | |
273 | A documentation string for this option, for printing in help messages. | |
274 | ||
275 | If both the @code{name} and @code{key} fields are zero, this string | |
f7364247 UD |
276 | will be printed tabbed left from the normal option column, making it |
277 | useful as a group header. This will be the first thing printed in its | |
278 | group. In this usage, it's conventional to end the string with a | |
b0de3e9e UD |
279 | @samp{:} character. |
280 | ||
281 | @item int group | |
f7364247 | 282 | Group identity for this option. |
b0de3e9e UD |
283 | |
284 | In a long help message, options are sorted alphabetically within each | |
1522c368 | 285 | group, and the groups presented in the order 0, 1, 2, @dots{}, @var{n}, |
f7364247 UD |
286 | @minus{}@var{m}, @dots{}, @minus{}2, @minus{}1. |
287 | ||
288 | Every entry in an options array with this field 0 will inherit the group | |
289 | number of the previous entry, or zero if it's the first one. If it's a | |
290 | group header with @code{name} and @code{key} fields both zero, the | |
291 | previous entry + 1 is the default. Automagic options such as | |
292 | @samp{--help} are put into group @minus{}1. | |
293 | ||
294 | Note that because of C structure initialization rules, this field often | |
295 | need not be specified, because 0 is the correct value. | |
b0de3e9e UD |
296 | @end table |
297 | @end deftp | |
298 | ||
f7364247 | 299 | |
b0de3e9e UD |
300 | @menu |
301 | * Flags: Argp Option Flags. Flags for options. | |
302 | @end menu | |
303 | ||
304 | @node Argp Option Flags, , , Argp Option Vectors | |
305 | @subsubsection Flags for Argp Options | |
306 | ||
307 | The following flags may be or'd together in the @code{flags} field of a | |
f7364247 UD |
308 | @code{struct argp_option}. These flags control various aspects of how |
309 | that option is parsed or displayed in help messages: | |
310 | ||
b0de3e9e UD |
311 | |
312 | @vtable @code | |
b0de3e9e | 313 | @item OPTION_ARG_OPTIONAL |
d08a7e4c | 314 | @standards{GNU, argp.h} |
b0de3e9e UD |
315 | The argument associated with this option is optional. |
316 | ||
b0de3e9e | 317 | @item OPTION_HIDDEN |
d08a7e4c | 318 | @standards{GNU, argp.h} |
b0de3e9e UD |
319 | This option isn't displayed in any help messages. |
320 | ||
b0de3e9e | 321 | @item OPTION_ALIAS |
d08a7e4c | 322 | @standards{GNU, argp.h} |
b0de3e9e UD |
323 | This option is an alias for the closest previous non-alias option. This |
324 | means that it will be displayed in the same help entry, and will inherit | |
f7364247 UD |
325 | fields other than @code{name} and @code{key} from the option being |
326 | aliased. | |
327 | ||
b0de3e9e | 328 | |
b0de3e9e | 329 | @item OPTION_DOC |
d08a7e4c | 330 | @standards{GNU, argp.h} |
f7364247 UD |
331 | This option isn't actually an option and should be ignored by the actual |
332 | option parser. It is an arbitrary section of documentation that should | |
333 | be displayed in much the same manner as the options. This is known as a | |
334 | @dfn{documentation option}. | |
b0de3e9e UD |
335 | |
336 | If this flag is set, then the option @code{name} field is displayed | |
f7364247 UD |
337 | unmodified (e.g., no @samp{--} prefix is added) at the left-margin where |
338 | a @emph{short} option would normally be displayed, and this | |
954cbda0 | 339 | documentation string is left in its usual place. For purposes of |
f7364247 UD |
340 | sorting, any leading whitespace and punctuation is ignored, unless the |
341 | first non-whitespace character is @samp{-}. This entry is displayed | |
342 | after all options, after @code{OPTION_DOC} entries with a leading | |
343 | @samp{-}, in the same group. | |
b0de3e9e | 344 | |
b0de3e9e | 345 | @item OPTION_NO_USAGE |
d08a7e4c | 346 | @standards{GNU, argp.h} |
f7364247 UD |
347 | This option shouldn't be included in `long' usage messages, but should |
348 | still be included in other help messages. This is intended for options | |
349 | that are completely documented in an argp's @code{args_doc} | |
350 | field. @xref{Argp Parsers}. Including this option in the generic usage | |
351 | list would be redundant, and should be avoided. | |
b0de3e9e UD |
352 | |
353 | For instance, if @code{args_doc} is @code{"FOO BAR\n-x BLAH"}, and the | |
354 | @samp{-x} option's purpose is to distinguish these two cases, @samp{-x} | |
355 | should probably be marked @code{OPTION_NO_USAGE}. | |
356 | @end vtable | |
357 | ||
358 | @node Argp Parser Functions, Argp Children, Argp Option Vectors, Argp Parsers | |
359 | @subsection Argp Parser Functions | |
360 | ||
361 | The function pointed to by the @code{parser} field in a @code{struct | |
362 | argp} (@pxref{Argp Parsers}) defines what actions take place in response | |
f7364247 UD |
363 | to each option or argument parsed. It is also used as a hook, allowing a |
364 | parser to perform tasks at certain other points during parsing. | |
b0de3e9e UD |
365 | |
366 | @need 2000 | |
367 | Argp parser functions have the following type signature: | |
368 | ||
369 | @cindex argp parser functions | |
370 | @smallexample | |
371 | error_t @var{parser} (int @var{key}, char *@var{arg}, struct argp_state *@var{state}) | |
372 | @end smallexample | |
373 | ||
374 | @noindent | |
375 | where the arguments are as follows: | |
376 | ||
377 | @table @var | |
378 | @item key | |
379 | For each option that is parsed, @var{parser} is called with a value of | |
f7364247 UD |
380 | @var{key} from that option's @code{key} field in the option |
381 | vector. @xref{Argp Option Vectors}. @var{parser} is also called at | |
382 | other times with special reserved keys, such as @code{ARGP_KEY_ARG} for | |
b0de3e9e UD |
383 | non-option arguments. @xref{Argp Special Keys}. |
384 | ||
385 | @item arg | |
f7364247 UD |
386 | If @var{key} is an option, @var{arg} is its given value. This defaults |
387 | to zero if no value is specified. Only options that have a non-zero | |
388 | @code{arg} field can ever have a value. These must @emph{always} have a | |
389 | value unless the @code{OPTION_ARG_OPTIONAL} flag is specified. If the | |
390 | input being parsed specifies a value for an option that doesn't allow | |
391 | one, an error results before @var{parser} ever gets called. | |
b0de3e9e | 392 | |
f7364247 UD |
393 | If @var{key} is @code{ARGP_KEY_ARG}, @var{arg} is a non-option |
394 | argument. Other special keys always have a zero @var{arg}. | |
b0de3e9e UD |
395 | |
396 | @item state | |
397 | @var{state} points to a @code{struct argp_state}, containing useful | |
f7364247 UD |
398 | information about the current parsing state for use by |
399 | @var{parser}. @xref{Argp Parsing State}. | |
b0de3e9e UD |
400 | @end table |
401 | ||
402 | When @var{parser} is called, it should perform whatever action is | |
f7364247 UD |
403 | appropriate for @var{key}, and return @code{0} for success, |
404 | @code{ARGP_ERR_UNKNOWN} if the value of @var{key} is not handled by this | |
405 | parser function, or a unix error code if a real error | |
406 | occurred. @xref{Error Codes}. | |
b0de3e9e | 407 | |
b0de3e9e | 408 | @deftypevr Macro int ARGP_ERR_UNKNOWN |
d08a7e4c | 409 | @standards{GNU, argp.h} |
b0de3e9e UD |
410 | Argp parser functions should return @code{ARGP_ERR_UNKNOWN} for any |
411 | @var{key} value they do not recognize, or for non-option arguments | |
f7364247 | 412 | (@code{@var{key} == ARGP_KEY_ARG}) that they are not equipped to handle. |
b0de3e9e UD |
413 | @end deftypevr |
414 | ||
415 | @need 3000 | |
416 | A typical parser function uses a switch statement on @var{key}: | |
417 | ||
418 | @smallexample | |
419 | error_t | |
420 | parse_opt (int key, char *arg, struct argp_state *state) | |
421 | @{ | |
422 | switch (key) | |
423 | @{ | |
424 | case @var{option_key}: | |
425 | @var{action} | |
426 | break; | |
427 | @dots{} | |
428 | default: | |
429 | return ARGP_ERR_UNKNOWN; | |
430 | @} | |
431 | return 0; | |
432 | @} | |
433 | @end smallexample | |
434 | ||
435 | @menu | |
436 | * Keys: Argp Special Keys. Special values for the @var{key} argument. | |
437 | * State: Argp Parsing State. What the @var{state} argument refers to. | |
438 | * Functions: Argp Helper Functions. Functions to help during argp parsing. | |
439 | @end menu | |
440 | ||
441 | @node Argp Special Keys, Argp Parsing State, , Argp Parser Functions | |
442 | @subsubsection Special Keys for Argp Parser Functions | |
443 | ||
444 | In addition to key values corresponding to user options, the @var{key} | |
445 | argument to argp parser functions may have a number of other special | |
f7364247 UD |
446 | values. In the following example @var{arg} and @var{state} refer to |
447 | parser function arguments. @xref{Argp Parser Functions}. | |
b0de3e9e UD |
448 | |
449 | @vtable @code | |
b0de3e9e | 450 | @item ARGP_KEY_ARG |
d08a7e4c | 451 | @standards{GNU, argp.h} |
b0de3e9e UD |
452 | This is not an option at all, but rather a command line argument, whose |
453 | value is pointed to by @var{arg}. | |
454 | ||
f7364247 UD |
455 | When there are multiple parser functions in play due to argp parsers |
456 | being combined, it's impossible to know which one will handle a specific | |
457 | argument. Each is called until one returns 0 or an error other than | |
458 | @code{ARGP_ERR_UNKNOWN}; if an argument is not handled, | |
b0de3e9e UD |
459 | @code{argp_parse} immediately returns success, without parsing any more |
460 | arguments. | |
461 | ||
462 | Once a parser function returns success for this key, that fact is | |
f7364247 UD |
463 | recorded, and the @code{ARGP_KEY_NO_ARGS} case won't be |
464 | used. @emph{However}, if while processing the argument a parser function | |
b0de3e9e UD |
465 | decrements the @code{next} field of its @var{state} argument, the option |
466 | won't be considered processed; this is to allow you to actually modify | |
f7364247 | 467 | the argument, perhaps into an option, and have it processed again. |
b0de3e9e | 468 | |
d705269e | 469 | @item ARGP_KEY_ARGS |
d08a7e4c | 470 | @standards{GNU, argp.h} |
d705269e UD |
471 | If a parser function returns @code{ARGP_ERR_UNKNOWN} for |
472 | @code{ARGP_KEY_ARG}, it is immediately called again with the key | |
473 | @code{ARGP_KEY_ARGS}, which has a similar meaning, but is slightly more | |
474 | convenient for consuming all remaining arguments. @var{arg} is 0, and | |
475 | the tail of the argument vector may be found at @code{@var{state}->argv | |
476 | + @var{state}->next}. If success is returned for this key, and | |
f7364247 UD |
477 | @code{@var{state}->next} is unchanged, all remaining arguments are |
478 | considered to have been consumed. Otherwise, the amount by which | |
479 | @code{@var{state}->next} has been adjusted indicates how many were used. | |
480 | Here's an example that uses both, for different args: | |
481 | ||
d705269e UD |
482 | |
483 | @smallexample | |
95fdc6a0 | 484 | @dots{} |
d705269e UD |
485 | case ARGP_KEY_ARG: |
486 | if (@var{state}->arg_num == 0) | |
487 | /* First argument */ | |
488 | first_arg = @var{arg}; | |
489 | else | |
838e5ffe UD |
490 | /* Let the next case parse it. */ |
491 | return ARGP_KEY_UNKNOWN; | |
d705269e UD |
492 | break; |
493 | case ARGP_KEY_ARGS: | |
494 | remaining_args = @var{state}->argv + @var{state}->next; | |
495 | num_remaining_args = @var{state}->argc - @var{state}->next; | |
496 | break; | |
497 | @end smallexample | |
498 | ||
b0de3e9e | 499 | @item ARGP_KEY_END |
d08a7e4c | 500 | @standards{GNU, argp.h} |
f7364247 UD |
501 | This indicates that there are no more command line arguments. Parser |
502 | functions are called in a different order, children first. This allows | |
503 | each parser to clean up its state for the parent. | |
b0de3e9e | 504 | |
b0de3e9e | 505 | @item ARGP_KEY_NO_ARGS |
d08a7e4c | 506 | @standards{GNU, argp.h} |
f7364247 UD |
507 | Because it's common to do some special processing if there aren't any |
508 | non-option args, parser functions are called with this key if they | |
509 | didn't successfully process any non-option arguments. This is called | |
510 | just before @code{ARGP_KEY_END}, where more general validity checks on | |
511 | previously parsed arguments take place. | |
b0de3e9e | 512 | |
b0de3e9e | 513 | @item ARGP_KEY_INIT |
d08a7e4c | 514 | @standards{GNU, argp.h} |
f7364247 UD |
515 | This is passed in before any parsing is done. Afterwards, the values of |
516 | each element of the @code{child_input} field of @var{state}, if any, are | |
b0de3e9e UD |
517 | copied to each child's state to be the initial value of the @code{input} |
518 | when @emph{their} parsers are called. | |
519 | ||
b0de3e9e | 520 | @item ARGP_KEY_SUCCESS |
d08a7e4c | 521 | @standards{GNU, argp.h} |
f7364247 UD |
522 | Passed in when parsing has successfully been completed, even if |
523 | arguments remain. | |
b0de3e9e | 524 | |
b0de3e9e | 525 | @item ARGP_KEY_ERROR |
d08a7e4c | 526 | @standards{GNU, argp.h} |
f7364247 UD |
527 | Passed in if an error has occurred and parsing is terminated. In this |
528 | case a call with a key of @code{ARGP_KEY_SUCCESS} is never made. | |
b0de3e9e | 529 | |
b0de3e9e | 530 | @item ARGP_KEY_FINI |
d08a7e4c | 531 | @standards{GNU, argp.h} |
f7364247 UD |
532 | The final key ever seen by any parser, even after |
533 | @code{ARGP_KEY_SUCCESS} and @code{ARGP_KEY_ERROR}. Any resources | |
534 | allocated by @code{ARGP_KEY_INIT} may be freed here. At times, certain | |
535 | resources allocated are to be returned to the caller after a successful | |
536 | parse. In that case, those particular resources can be freed in the | |
537 | @code{ARGP_KEY_ERROR} case. | |
b0de3e9e UD |
538 | @end vtable |
539 | ||
540 | In all cases, @code{ARGP_KEY_INIT} is the first key seen by parser | |
f7364247 UD |
541 | functions, and @code{ARGP_KEY_FINI} the last, unless an error was |
542 | returned by the parser for @code{ARGP_KEY_INIT}. Other keys can occur | |
543 | in one the following orders. @var{opt} refers to an arbitrary option | |
544 | key: | |
b0de3e9e UD |
545 | |
546 | @table @asis | |
547 | @item @var{opt}@dots{} @code{ARGP_KEY_NO_ARGS} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS} | |
f7364247 | 548 | The arguments being parsed did not contain any non-option arguments. |
b0de3e9e UD |
549 | |
550 | @item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS} | |
f7364247 UD |
551 | All non-option arguments were successfully handled by a parser |
552 | function. There may be multiple parser functions if multiple argp | |
553 | parsers were combined. | |
b0de3e9e UD |
554 | |
555 | @item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_SUCCESS} | |
f7364247 | 556 | Some non-option argument went unrecognized. |
b0de3e9e UD |
557 | |
558 | This occurs when every parser function returns @code{ARGP_KEY_UNKNOWN} | |
f7364247 UD |
559 | for an argument, in which case parsing stops at that argument if |
560 | @var{arg_index} is a null pointer. Otherwise an error occurs. | |
b0de3e9e UD |
561 | @end table |
562 | ||
f7364247 | 563 | In all cases, if a non-null value for @var{arg_index} gets passed to |
faf2289f | 564 | @code{argp_parse}, the index of the first unparsed command-line argument |
f7364247 | 565 | is passed back in that value. |
faf2289f | 566 | |
f7364247 UD |
567 | If an error occurs and is either detected by argp or because a parser |
568 | function returned an error value, each parser is called with | |
569 | @code{ARGP_KEY_ERROR}. No further calls are made, except the final call | |
570 | with @code{ARGP_KEY_FINI}. | |
b0de3e9e | 571 | |
b0de3e9e UD |
572 | @node Argp Parsing State, Argp Helper Functions, Argp Special Keys, Argp Parser Functions |
573 | @subsubsection Argp Parsing State | |
574 | ||
575 | The third argument to argp parser functions (@pxref{Argp Parser | |
576 | Functions}) is a pointer to a @code{struct argp_state}, which contains | |
577 | information about the state of the option parsing. | |
578 | ||
b0de3e9e | 579 | @deftp {Data Type} {struct argp_state} |
d08a7e4c | 580 | @standards{GNU, argp.h} |
b0de3e9e UD |
581 | This structure has the following fields, which may be modified as noted: |
582 | ||
583 | @table @code | |
584 | @item const struct argp *const root_argp | |
585 | The top level argp parser being parsed. Note that this is often | |
586 | @emph{not} the same @code{struct argp} passed into @code{argp_parse} by | |
f7364247 UD |
587 | the invoking program. @xref{Argp}. It is an internal argp parser that |
588 | contains options implemented by @code{argp_parse} itself, such as | |
589 | @samp{--help}. | |
b0de3e9e UD |
590 | |
591 | @item int argc | |
592 | @itemx char **argv | |
f7364247 | 593 | The argument vector being parsed. This may be modified. |
b0de3e9e UD |
594 | |
595 | @item int next | |
f7364247 UD |
596 | The index in @code{argv} of the next argument to be parsed. This may be |
597 | modified. | |
b0de3e9e UD |
598 | |
599 | One way to consume all remaining arguments in the input is to set | |
f7364247 UD |
600 | @code{@var{state}->next = @var{state}->argc}, perhaps after recording |
601 | the value of the @code{next} field to find the consumed arguments. The | |
602 | current option can be re-parsed immediately by decrementing this field, | |
603 | then modifying @code{@var{state}->argv[@var{state}->next]} to reflect | |
604 | the option that should be reexamined. | |
b0de3e9e UD |
605 | |
606 | @item unsigned flags | |
f7364247 UD |
607 | The flags supplied to @code{argp_parse}. These may be modified, although |
608 | some flags may only take effect when @code{argp_parse} is first | |
609 | invoked. @xref{Argp Flags}. | |
b0de3e9e UD |
610 | |
611 | @item unsigned arg_num | |
612 | While calling a parsing function with the @var{key} argument | |
f7364247 UD |
613 | @code{ARGP_KEY_ARG}, this represents the number of the current arg, |
614 | starting at 0. It is incremented after each @code{ARGP_KEY_ARG} call | |
615 | returns. At all other times, this is the number of @code{ARGP_KEY_ARG} | |
616 | arguments that have been processed. | |
b0de3e9e UD |
617 | |
618 | @item int quoted | |
619 | If non-zero, the index in @code{argv} of the first argument following a | |
f7364247 UD |
620 | special @samp{--} argument. This prevents anything that follows from |
621 | being interpreted as an option. It is only set after argument parsing | |
622 | has proceeded past this point. | |
b0de3e9e UD |
623 | |
624 | @item void *input | |
625 | An arbitrary pointer passed in from the caller of @code{argp_parse}, in | |
626 | the @var{input} argument. | |
627 | ||
628 | @item void **child_inputs | |
f7364247 UD |
629 | These are values that will be passed to child parsers. This vector will |
630 | be the same length as the number of children in the current parser. Each | |
631 | child parser will be given the value of | |
632 | @code{@var{state}->child_inputs[@var{i}]} as @emph{its} | |
633 | @code{@var{state}->input} field, where @var{i} is the index of the child | |
634 | in the this parser's @code{children} field. @xref{Argp Children}. | |
b0de3e9e UD |
635 | |
636 | @item void *hook | |
637 | For the parser function's use. Initialized to 0, but otherwise ignored | |
638 | by argp. | |
639 | ||
640 | @item char *name | |
641 | The name used when printing messages. This is initialized to | |
f7364247 | 642 | @code{argv[0]}, or @code{program_invocation_name} if @code{argv[0]} is |
b0de3e9e UD |
643 | unavailable. |
644 | ||
645 | @item FILE *err_stream | |
646 | @itemx FILE *out_stream | |
f7364247 UD |
647 | The stdio streams used when argp prints. Error messages are printed to |
648 | @code{err_stream}, all other output, such as @samp{--help} output) to | |
649 | @code{out_stream}. These are initialized to @code{stderr} and | |
650 | @code{stdout} respectively. @xref{Standard Streams}. | |
b0de3e9e UD |
651 | |
652 | @item void *pstate | |
653 | Private, for use by the argp implementation. | |
654 | @end table | |
655 | @end deftp | |
656 | ||
3c8b4190 SP |
657 | @node Argp Helper Functions, , Argp Parsing State, Argp Parser Functions |
658 | @subsubsection Functions For Use in Argp Parsers | |
659 | ||
660 | Argp provides a number of functions available to the user of argp | |
661 | (@pxref{Argp Parser Functions}), mostly for producing error messages. | |
662 | These take as their first argument the @var{state} argument to the | |
663 | parser function. @xref{Argp Parsing State}. | |
664 | ||
665 | ||
666 | @cindex usage messages, in argp | |
3c8b4190 | 667 | @deftypefun void argp_usage (const struct argp_state *@var{state}) |
d08a7e4c | 668 | @standards{GNU, argp.h} |
4a16c662 AO |
669 | @safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}} |
670 | @c Just calls argp_state_help with stderr and ARGP_HELP_STD_USAGE. | |
3c8b4190 | 671 | Outputs the standard usage message for the argp parser referred to by |
954cbda0 | 672 | @var{state} to @code{@var{state}->err_stream} and terminates the program |
3c8b4190 SP |
673 | with @code{exit (argp_err_exit_status)}. @xref{Argp Global Variables}. |
674 | @end deftypefun | |
675 | ||
676 | @cindex syntax error messages, in argp | |
3c8b4190 | 677 | @deftypefun void argp_error (const struct argp_state *@var{state}, const char *@var{fmt}, @dots{}) |
d08a7e4c | 678 | @standards{GNU, argp.h} |
4a16c662 AO |
679 | @safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}} |
680 | @c Lock stream, vasprintf the formatted message into a buffer, print the | |
681 | @c buffer prefixed by the short program name (in libc, | |
682 | @c argp_short_program_name is a macro that expands to | |
683 | @c program_invocation_short_name), releases the buffer, then call | |
684 | @c argp_state_help with stream and ARGP_HELP_STD_ERR, unlocking the | |
685 | @c stream at the end. | |
3c8b4190 SP |
686 | Prints the printf format string @var{fmt} and following args, preceded |
687 | by the program name and @samp{:}, and followed by a @w{@samp{Try @dots{} | |
688 | --help}} message, and terminates the program with an exit status of | |
689 | @code{argp_err_exit_status}. @xref{Argp Global Variables}. | |
690 | @end deftypefun | |
691 | ||
692 | @cindex error messages, in argp | |
3c8b4190 | 693 | @deftypefun void argp_failure (const struct argp_state *@var{state}, int @var{status}, int @var{errnum}, const char *@var{fmt}, @dots{}) |
d08a7e4c | 694 | @standards{GNU, argp.h} |
4a16c662 AO |
695 | @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsmem{}}} |
696 | @c Lock stream, write out the short program name, vasprintf the optional | |
697 | @c formatted message to a buffer, print the buffer prefixed by colon and | |
698 | @c blank, release the buffer, call strerror_r with an automatic buffer, | |
699 | @c print it out after colon and blank, put[w]c a line break, unlock the | |
700 | @c stream, then exit unless ARGP_NO_EXIT. | |
954cbda0 | 701 | Similar to the standard GNU error-reporting function @code{error}, this |
3c8b4190 SP |
702 | prints the program name and @samp{:}, the printf format string |
703 | @var{fmt}, and the appropriate following args. If it is non-zero, the | |
704 | standard unix error text for @var{errnum} is printed. If @var{status} is | |
705 | non-zero, it terminates the program with that value as its exit status. | |
706 | ||
707 | The difference between @code{argp_failure} and @code{argp_error} is that | |
708 | @code{argp_error} is for @emph{parsing errors}, whereas | |
709 | @code{argp_failure} is for other problems that occur during parsing but | |
710 | don't reflect a syntactic problem with the input, such as illegal values | |
711 | for options, bad phase of the moon, etc. | |
712 | @end deftypefun | |
713 | ||
3c8b4190 | 714 | @deftypefun void argp_state_help (const struct argp_state *@var{state}, FILE *@var{stream}, unsigned @var{flags}) |
d08a7e4c | 715 | @standards{GNU, argp.h} |
4a16c662 AO |
716 | @safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}} |
717 | @c Just calls _help with the short program name and optionally exit. | |
718 | @c The main problems in _help, besides the usual issues with stream I/O | |
719 | @c and translation, are the use of a static buffer (uparams, thus | |
720 | @c @mtasurace:argpbuf) that makes the whole thing thread-unsafe, reading | |
721 | @c from the environment for ARGP_HELP_FMT, accessing the locale object | |
722 | @c multiple times. | |
723 | ||
724 | @c _help @mtsenv @mtasurace:argpbuf @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock | |
725 | @c dgettext @ascuintl | |
726 | @c flockfile @aculock | |
727 | @c funlockfile @aculock | |
728 | @c fill_in_uparams @mtsenv @mtasurace:argpbuf @mtslocale @asucorrupt @ascuheap @aculock @acucorrupt @acsmem | |
729 | @c argp_failure dup (status = errnum = 0) | |
730 | @c atoi dup @mtslocale | |
731 | @c argp_hol @ascuheap @acsmem | |
732 | @c make_hol @ascuheap @acsmem | |
733 | @c hol_add_cluster @ascuheap @acsmem | |
734 | @c hol_append @ascuheap @acsmem | |
735 | @c hol_set_group ok | |
736 | @c hol_find_entry ok | |
737 | @c hol_sort @mtslocale @acucorrupt | |
738 | @c qsort dup @acucorrupt | |
739 | @c hol_entry_qcmp @mtslocale | |
740 | @c hol_entry_cmp @mtslocale | |
741 | @c group_cmp ok | |
742 | @c hol_cluster_cmp ok | |
743 | @c group_cmp ok | |
744 | @c hol_entry_first_short @mtslocale | |
745 | @c hol_entry_short_iterate [@mtslocale] | |
746 | @c until_short ok | |
747 | @c oshort ok | |
748 | @c isprint ok | |
749 | @c odoc ok | |
750 | @c hol_entry_first_long ok | |
751 | @c canon_doc_option @mtslocale | |
752 | @c tolower dup | |
753 | @c hol_usage @mtslocale @ascuintl @ascuheap @acsmem | |
754 | @c hol_entry_short_iterate ok | |
755 | @c add_argless_short_opt ok | |
756 | @c argp_fmtstream_printf dup | |
757 | @c hol_entry_short_iterate @mtslocale @ascuintl @ascuheap @acsmem | |
758 | @c usage_argful_short_opt @mtslocale @ascuintl @ascuheap @acsmem | |
759 | @c dgettext dup | |
760 | @c argp_fmtstream_printf dup | |
761 | @c hol_entry_long_iterate @mtslocale @ascuintl @ascuheap @acsmem | |
762 | @c usage_long_opt @mtslocale @ascuintl @ascuheap @acsmem | |
763 | @c dgettext dup | |
764 | @c argp_fmtstream_printf dup | |
765 | @c hol_help @mtslocale @mtasurace:argpbuf @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock | |
766 | @c hol_entry_help @mtslocale @mtasurace:argpbuf @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock | |
767 | @c argp_fmtstream_set_lmargin dup | |
768 | @c argp_fmtstream_wmargin dup | |
769 | @c argp_fmtstream_set_wmargin dup | |
770 | @c comma @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock | |
771 | @c argp_fmtstream_putc dup | |
772 | @c hol_cluster_is_child ok | |
773 | @c argp_fmtstream_wmargin dup | |
774 | @c print_header dup | |
775 | @c argp_fmtstream_set_wmargin dup | |
776 | @c argp_fmtstream_puts dup | |
777 | @c indent_to dup | |
778 | @c argp_fmtstream_putc dup | |
779 | @c arg @mtslocale @ascuheap @acsmem | |
780 | @c argp_fmtstream_printf dup | |
781 | @c odoc dup | |
782 | @c argp_fmtstream_puts dup | |
783 | @c argp_fmtstream_printf dup | |
784 | @c print_header @mtslocale @mtasurace:argpbuf @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock | |
785 | @c dgettext dup | |
786 | @c filter_doc dup | |
787 | @c argp_fmtstream_putc dup | |
788 | @c indent_to dup | |
789 | @c argp_fmtstream_set_lmargin dup | |
790 | @c argp_fmtstream_set_wmargin dup | |
791 | @c argp_fmtstream_puts dup | |
792 | @c free dup | |
793 | @c filter_doc dup | |
794 | @c argp_fmtstream_point dup | |
795 | @c indent_to @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock | |
796 | @c argp_fmtstream_point dup | |
797 | @c argp_fmtstream_putc dup | |
798 | @c dgettext dup | |
799 | @c filter_doc dup | |
800 | @c argp_fmtstream_putc dup | |
801 | @c argp_fmtstream_puts dup | |
802 | @c free dup | |
803 | @c hol_free @ascuheap @acsmem | |
804 | @c free dup | |
805 | @c argp_args_levels ok | |
806 | @c argp_args_usage @mtslocale @ascuintl @ascuheap @asucorrupt @acsmem @acucorrupt @aculock | |
807 | @c dgettext dup | |
808 | @c filter_doc ok | |
809 | @c argp_input ok | |
810 | @c argp->help_filter | |
811 | @c space @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock | |
812 | @c argp_fmtstream_point dup | |
813 | @c argp_fmtstream_rmargin @mtslocale @asucorrupt @acucorrupt @aculock | |
814 | @c argp_fmtstream_update dup | |
815 | @c argp_fmtstream_putc dup | |
816 | @c argp_fmtstream_write dup | |
817 | @c free dup | |
818 | @c argp_doc @mtslocale @ascuheap @ascuintl @asucorrupt @acsmem @acucorrupt @aculock | |
819 | @c dgettext @ascuintl | |
820 | @c strndup @ascuheap @acsmem | |
821 | @c argp_input dup | |
822 | @c argp->help_filter | |
823 | @c argp_fmtstream_putc @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock | |
824 | @c argp_fmtstream_ensure dup | |
825 | @c argp_fmtstream_write dup | |
826 | @c argp_fmtstream_puts dup | |
827 | @c argp_fmtstream_point @mtslocale @asucorrupt @acucorrupt @aculock | |
828 | @c argp_fmtstream_update dup | |
829 | @c argp_fmtstream_lmargin dup | |
830 | @c free dup | |
831 | @c argp_make_fmtstream @ascuheap @acsmem | |
832 | @c argp_fmtstream_free @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock | |
833 | @c argp_fmtstream_update @mtslocale @asucorrupt @acucorrupt @aculock | |
834 | @c put[w]c_unlocked dup | |
835 | @c isblank in loop @mtslocale | |
836 | @c fxprintf @aculock | |
837 | @c fxprintf @aculock | |
838 | @c free dup | |
839 | @c argp_fmtstream_set_wmargin @mtslocale @asucorrupt @acucorrupt @aculock | |
840 | @c argp_fmtstream_update dup | |
841 | @c argp_fmtstream_printf @mtslocale @ascuheap @acsmem | |
842 | @c argp_fmtstream_ensure dup | |
843 | @c vsnprintf dup | |
844 | @c argp_fmtstream_set_lmargin @mtslocale @asucorrupt @acucorrupt @aculock | |
845 | @c argp_fmtstream_update dup | |
846 | @c argp_fmtstream_puts @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock | |
847 | @c argp_fmtstream_write @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock | |
848 | @c argp_fmtstream_ensure @mtslocale @ascuheap @asucorrupt @acsmem @acucorrupt @aculock | |
849 | @c argp_fmtstream_update dup | |
850 | @c fxprintf @aculock | |
851 | @c realloc @ascuheap @acsmem | |
3c8b4190 SP |
852 | Outputs a help message for the argp parser referred to by @var{state}, |
853 | to @var{stream}. The @var{flags} argument determines what sort of help | |
854 | message is produced. @xref{Argp Help Flags}. | |
855 | @end deftypefun | |
856 | ||
857 | Error output is sent to @code{@var{state}->err_stream}, and the program | |
858 | name printed is @code{@var{state}->name}. | |
859 | ||
860 | The output or program termination behavior of these functions may be | |
861 | suppressed if the @code{ARGP_NO_EXIT} or @code{ARGP_NO_ERRS} flags are | |
862 | passed to @code{argp_parse}. @xref{Argp Flags}. | |
863 | ||
864 | This behavior is useful if an argp parser is exported for use by other | |
865 | programs (e.g., by a library), and may be used in a context where it is | |
866 | not desirable to terminate the program in response to parsing errors. In | |
867 | argp parsers intended for such general use, and for the case where the | |
868 | program @emph{doesn't} terminate, calls to any of these functions should | |
869 | be followed by code that returns the appropriate error code: | |
870 | ||
871 | @smallexample | |
872 | if (@var{bad argument syntax}) | |
873 | @{ | |
874 | argp_usage (@var{state}); | |
875 | return EINVAL; | |
876 | @} | |
877 | @end smallexample | |
878 | ||
879 | @noindent | |
880 | If a parser function will @emph{only} be used when @code{ARGP_NO_EXIT} | |
881 | is not set, the return may be omitted. | |
882 | ||
b0de3e9e UD |
883 | @node Argp Children, Argp Help Filtering, Argp Parser Functions, Argp Parsers |
884 | @subsection Combining Multiple Argp Parsers | |
885 | ||
f7364247 UD |
886 | The @code{children} field in a @code{struct argp} enables other argp |
887 | parsers to be combined with the referencing one for the parsing of a | |
888 | single set of arguments. This field should point to a vector of | |
889 | @code{struct argp_child}, which is terminated by an entry having a value | |
890 | of zero in the @code{argp} field. | |
b0de3e9e | 891 | |
f7364247 UD |
892 | Where conflicts between combined parsers arise, as when two specify an |
893 | option with the same name, the parser conflicts are resolved in favor of | |
894 | the parent argp parser(s), or the earlier of the argp parsers in the | |
895 | list of children. | |
b0de3e9e | 896 | |
b0de3e9e | 897 | @deftp {Data Type} {struct argp_child} |
d08a7e4c | 898 | @standards{GNU, argp.h} |
b0de3e9e | 899 | An entry in the list of subsidiary argp parsers pointed to by the |
f7364247 UD |
900 | @code{children} field in a @code{struct argp}. The fields are as |
901 | follows: | |
b0de3e9e UD |
902 | |
903 | @table @code | |
904 | @item const struct argp *argp | |
f7364247 | 905 | The child argp parser, or zero to end of the list. |
b0de3e9e UD |
906 | |
907 | @item int flags | |
908 | Flags for this child. | |
909 | ||
910 | @item const char *header | |
f7364247 UD |
911 | If non-zero, this is an optional header to be printed within help output |
912 | before the child options. As a side-effect, a non-zero value forces the | |
913 | child options to be grouped together. To achieve this effect without | |
914 | actually printing a header string, use a value of @code{""}. As with | |
915 | header strings specified in an option entry, the conventional value of | |
916 | the last character is @samp{:}. @xref{Argp Option Vectors}. | |
b0de3e9e UD |
917 | |
918 | @item int group | |
f7364247 UD |
919 | This is where the child options are grouped relative to the other |
920 | `consolidated' options in the parent argp parser. The values are the | |
921 | same as the @code{group} field in @code{struct argp_option}. @xref{Argp | |
922 | Option Vectors}. All child-groupings follow parent options at a | |
923 | particular group level. If both this field and @code{header} are zero, | |
924 | then the child's options aren't grouped together, they are merged with | |
925 | parent options at the parent option group level. | |
926 | ||
b0de3e9e UD |
927 | @end table |
928 | @end deftp | |
929 | ||
930 | @node Argp Flags, Argp Help, Argp Parsers, Argp | |
931 | @subsection Flags for @code{argp_parse} | |
932 | ||
933 | The default behavior of @code{argp_parse} is designed to be convenient | |
934 | for the most common case of parsing program command line argument. To | |
935 | modify these defaults, the following flags may be or'd together in the | |
936 | @var{flags} argument to @code{argp_parse}: | |
937 | ||
938 | @vtable @code | |
b0de3e9e | 939 | @item ARGP_PARSE_ARGV0 |
d08a7e4c | 940 | @standards{GNU, argp.h} |
b0de3e9e | 941 | Don't ignore the first element of the @var{argv} argument to |
f7364247 UD |
942 | @code{argp_parse}. Unless @code{ARGP_NO_ERRS} is set, the first element |
943 | of the argument vector is skipped for option parsing purposes, as it | |
944 | corresponds to the program name in a command line. | |
b0de3e9e | 945 | |
b0de3e9e | 946 | @item ARGP_NO_ERRS |
d08a7e4c | 947 | @standards{GNU, argp.h} |
b0de3e9e UD |
948 | Don't print error messages for unknown options to @code{stderr}; unless |
949 | this flag is set, @code{ARGP_PARSE_ARGV0} is ignored, as @code{argv[0]} | |
950 | is used as the program name in the error messages. This flag implies | |
f7364247 UD |
951 | @code{ARGP_NO_EXIT}. This is based on the assumption that silent exiting |
952 | upon errors is bad behavior. | |
b0de3e9e | 953 | |
b0de3e9e | 954 | @item ARGP_NO_ARGS |
d08a7e4c | 955 | @standards{GNU, argp.h} |
f7364247 UD |
956 | Don't parse any non-option args. Normally these are parsed by calling |
957 | the parse functions with a key of @code{ARGP_KEY_ARG}, the actual | |
958 | argument being the value. This flag needn't normally be set, as the | |
959 | default behavior is to stop parsing as soon as an argument fails to be | |
960 | parsed. @xref{Argp Parser Functions}. | |
b0de3e9e | 961 | |
b0de3e9e | 962 | @item ARGP_IN_ORDER |
d08a7e4c | 963 | @standards{GNU, argp.h} |
b0de3e9e | 964 | Parse options and arguments in the same order they occur on the command |
f7364247 | 965 | line. Normally they're rearranged so that all options come first. |
b0de3e9e | 966 | |
b0de3e9e | 967 | @item ARGP_NO_HELP |
d08a7e4c | 968 | @standards{GNU, argp.h} |
b0de3e9e | 969 | Don't provide the standard long option @samp{--help}, which ordinarily |
f7364247 UD |
970 | causes usage and option help information to be output to @code{stdout} |
971 | and @code{exit (0)}. | |
b0de3e9e | 972 | |
b0de3e9e | 973 | @item ARGP_NO_EXIT |
d08a7e4c | 974 | @standards{GNU, argp.h} |
f7364247 | 975 | Don't exit on errors, although they may still result in error messages. |
b0de3e9e | 976 | |
b0de3e9e | 977 | @item ARGP_LONG_ONLY |
d08a7e4c | 978 | @standards{GNU, argp.h} |
954cbda0 | 979 | Use the GNU getopt `long-only' rules for parsing arguments. This allows |
f7364247 | 980 | long-options to be recognized with only a single @samp{-} |
11bf311e | 981 | (i.e., @samp{-help}). This results in a less useful interface, and its |
f7364247 UD |
982 | use is discouraged as it conflicts with the way most GNU programs work |
983 | as well as the GNU coding standards. | |
b0de3e9e | 984 | |
b0de3e9e | 985 | @item ARGP_SILENT |
d08a7e4c | 986 | @standards{GNU, argp.h} |
b0de3e9e UD |
987 | Turns off any message-printing/exiting options, specifically |
988 | @code{ARGP_NO_EXIT}, @code{ARGP_NO_ERRS}, and @code{ARGP_NO_HELP}. | |
989 | @end vtable | |
990 | ||
991 | @node Argp Help Filtering, , Argp Children, Argp Parsers | |
992 | @need 2000 | |
993 | @subsection Customizing Argp Help Output | |
994 | ||
fed8f7f7 | 995 | The @code{help_filter} field in a @code{struct argp} is a pointer to a |
f7364247 UD |
996 | function that filters the text of help messages before displaying |
997 | them. They have a function signature like: | |
b0de3e9e UD |
998 | |
999 | @smallexample | |
1000 | char *@var{help-filter} (int @var{key}, const char *@var{text}, void *@var{input}) | |
1001 | @end smallexample | |
1002 | ||
f7364247 | 1003 | |
b0de3e9e | 1004 | @noindent |
f7364247 UD |
1005 | Where @var{key} is either a key from an option, in which case @var{text} |
1006 | is that option's help text. @xref{Argp Option Vectors}. Alternately, one | |
1007 | of the special keys with names beginning with @samp{ARGP_KEY_HELP_} | |
1008 | might be used, describing which other help text @var{text} will contain. | |
1009 | @xref{Argp Help Filter Keys}. | |
1010 | ||
1011 | The function should return either @var{text} if it remains as-is, or a | |
1012 | replacement string allocated using @code{malloc}. This will be either be | |
1013 | freed by argp or zero, which prints nothing. The value of @var{text} is | |
1014 | supplied @emph{after} any translation has been done, so if any of the | |
1015 | replacement text needs translation, it will be done by the filter | |
1016 | function. @var{input} is either the input supplied to @code{argp_parse} | |
1017 | or it is zero, if @code{argp_help} was called directly by the user. | |
b0de3e9e UD |
1018 | |
1019 | @menu | |
1020 | * Keys: Argp Help Filter Keys. Special @var{key} values for help filter functions. | |
1021 | @end menu | |
1022 | ||
1023 | @node Argp Help Filter Keys, , , Argp Help Filtering | |
1024 | @subsubsection Special Keys for Argp Help Filter Functions | |
1025 | ||
1026 | The following special values may be passed to an argp help filter | |
f7364247 UD |
1027 | function as the first argument in addition to key values for user |
1028 | options. They specify which help text the @var{text} argument contains: | |
b0de3e9e UD |
1029 | |
1030 | @vtable @code | |
b0de3e9e | 1031 | @item ARGP_KEY_HELP_PRE_DOC |
d08a7e4c | 1032 | @standards{GNU, argp.h} |
f7364247 | 1033 | The help text preceding options. |
b0de3e9e | 1034 | |
b0de3e9e | 1035 | @item ARGP_KEY_HELP_POST_DOC |
d08a7e4c | 1036 | @standards{GNU, argp.h} |
f7364247 | 1037 | The help text following options. |
b0de3e9e | 1038 | |
b0de3e9e | 1039 | @item ARGP_KEY_HELP_HEADER |
d08a7e4c | 1040 | @standards{GNU, argp.h} |
f7364247 | 1041 | The option header string. |
b0de3e9e | 1042 | |
b0de3e9e | 1043 | @item ARGP_KEY_HELP_EXTRA |
d08a7e4c | 1044 | @standards{GNU, argp.h} |
f7364247 | 1045 | This is used after all other documentation; @var{text} is zero for this key. |
b0de3e9e | 1046 | |
b0de3e9e | 1047 | @item ARGP_KEY_HELP_DUP_ARGS_NOTE |
d08a7e4c | 1048 | @standards{GNU, argp.h} |
f7364247 | 1049 | The explanatory note printed when duplicate option arguments have been suppressed. |
b0de3e9e | 1050 | |
b0de3e9e | 1051 | @item ARGP_KEY_HELP_ARGS_DOC |
d08a7e4c | 1052 | @standards{GNU, argp.h} |
f7364247 | 1053 | The argument doc string; formally the @code{args_doc} field from the argp parser. @xref{Argp Parsers}. |
b0de3e9e UD |
1054 | @end vtable |
1055 | ||
1056 | @node Argp Help, Argp Examples, Argp Flags, Argp | |
1057 | @subsection The @code{argp_help} Function | |
1058 | ||
f7364247 UD |
1059 | Normally programs using argp need not be written with particular |
1060 | printing argument-usage-type help messages in mind as the standard | |
1061 | @samp{--help} option is handled automatically by argp. Typical error | |
1062 | cases can be handled using @code{argp_usage} and | |
1063 | @code{argp_error}. @xref{Argp Helper Functions}. However, if it's | |
1064 | desirable to print a help message in some context other than parsing the | |
1065 | program options, argp offers the @code{argp_help} interface. | |
b0de3e9e | 1066 | |
29fe4d0d | 1067 | @deftypefun void argp_help (const struct argp *@var{argp}, FILE *@var{stream}, unsigned @var{flags}, char *@var{name}) |
d08a7e4c | 1068 | @standards{GNU, argp.h} |
4a16c662 AO |
1069 | @safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtsenv{} @mtslocale{}}@asunsafe{@ascuheap{} @ascuintl{} @asucorrupt{}}@acunsafe{@acsmem{} @acucorrupt{} @aculock{}}} |
1070 | @c Just calls _help. | |
f7364247 UD |
1071 | This outputs a help message for the argp parser @var{argp} to |
1072 | @var{stream}. The type of messages printed will be determined by | |
1073 | @var{flags}. | |
b0de3e9e UD |
1074 | |
1075 | Any options such as @samp{--help} that are implemented automatically by | |
1076 | argp itself will @emph{not} be present in the help output; for this | |
f7364247 UD |
1077 | reason it is best to use @code{argp_state_help} if calling from within |
1078 | an argp parser function. @xref{Argp Helper Functions}. | |
b0de3e9e UD |
1079 | @end deftypefun |
1080 | ||
1081 | @menu | |
1082 | * Flags: Argp Help Flags. Specifying what sort of help message to print. | |
1083 | @end menu | |
1084 | ||
1085 | @node Argp Help Flags, , , Argp Help | |
1086 | @subsection Flags for the @code{argp_help} Function | |
1087 | ||
f7364247 UD |
1088 | When calling @code{argp_help} (@pxref{Argp Help}) or |
1089 | @code{argp_state_help} (@pxref{Argp Helper Functions}) the exact output | |
1090 | is determined by the @var{flags} argument. This should consist of any of | |
1091 | the following flags, or'd together: | |
b0de3e9e UD |
1092 | |
1093 | @vtable @code | |
1094 | @item ARGP_HELP_USAGE | |
76b9ffef | 1095 | @standards{GNU, argp.h} |
b0de3e9e UD |
1096 | A unix @samp{Usage:} message that explicitly lists all options. |
1097 | ||
1098 | @item ARGP_HELP_SHORT_USAGE | |
76b9ffef | 1099 | @standards{GNU, argp.h} |
f7364247 UD |
1100 | A unix @samp{Usage:} message that displays an appropriate placeholder to |
1101 | indicate where the options go; useful for showing the non-option | |
1102 | argument syntax. | |
b0de3e9e UD |
1103 | |
1104 | @item ARGP_HELP_SEE | |
76b9ffef | 1105 | @standards{GNU, argp.h} |
b0de3e9e UD |
1106 | A @samp{Try @dots{} for more help} message; @samp{@dots{}} contains the |
1107 | program name and @samp{--help}. | |
1108 | ||
1109 | @item ARGP_HELP_LONG | |
76b9ffef | 1110 | @standards{GNU, argp.h} |
f7364247 | 1111 | A verbose option help message that gives each option available along |
b0de3e9e UD |
1112 | with its documentation string. |
1113 | ||
1114 | @item ARGP_HELP_PRE_DOC | |
76b9ffef | 1115 | @standards{GNU, argp.h} |
f7364247 | 1116 | The part of the argp parser doc string preceding the verbose option help. |
b0de3e9e UD |
1117 | |
1118 | @item ARGP_HELP_POST_DOC | |
76b9ffef | 1119 | @standards{GNU, argp.h} |
f7364247 | 1120 | The part of the argp parser doc string that following the verbose option help. |
b0de3e9e UD |
1121 | |
1122 | @item ARGP_HELP_DOC | |
76b9ffef | 1123 | @standards{GNU, argp.h} |
b0de3e9e UD |
1124 | @code{(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)} |
1125 | ||
1126 | @item ARGP_HELP_BUG_ADDR | |
76b9ffef | 1127 | @standards{GNU, argp.h} |
f7364247 UD |
1128 | A message that prints where to report bugs for this program, if the |
1129 | @code{argp_program_bug_address} variable contains this information. | |
b0de3e9e UD |
1130 | |
1131 | @item ARGP_HELP_LONG_ONLY | |
76b9ffef | 1132 | @standards{GNU, argp.h} |
f7364247 | 1133 | This will modify any output to reflect the @code{ARGP_LONG_ONLY} mode. |
b0de3e9e UD |
1134 | @end vtable |
1135 | ||
1136 | The following flags are only understood when used with | |
f7364247 | 1137 | @code{argp_state_help}. They control whether the function returns after |
b0de3e9e UD |
1138 | printing its output, or terminates the program: |
1139 | ||
1140 | @vtable @code | |
1141 | @item ARGP_HELP_EXIT_ERR | |
76b9ffef | 1142 | @standards{GNU, argp.h} |
f7364247 | 1143 | This will terminate the program with @code{exit (argp_err_exit_status)}. |
b0de3e9e UD |
1144 | |
1145 | @item ARGP_HELP_EXIT_OK | |
76b9ffef | 1146 | @standards{GNU, argp.h} |
f7364247 | 1147 | This will terminate the program with @code{exit (0)}. |
b0de3e9e UD |
1148 | @end vtable |
1149 | ||
f7364247 | 1150 | The following flags are combinations of the basic flags for printing |
b0de3e9e UD |
1151 | standard messages: |
1152 | ||
1153 | @vtable @code | |
1154 | @item ARGP_HELP_STD_ERR | |
76b9ffef | 1155 | @standards{GNU, argp.h} |
f7364247 UD |
1156 | Assuming that an error message for a parsing error has printed, this |
1157 | prints a message on how to get help, and terminates the program with an | |
b0de3e9e UD |
1158 | error. |
1159 | ||
1160 | @item ARGP_HELP_STD_USAGE | |
76b9ffef | 1161 | @standards{GNU, argp.h} |
f7364247 UD |
1162 | This prints a standard usage message and terminates the program with an |
1163 | error. This is used when no other specific error messages are | |
1164 | appropriate or available. | |
b0de3e9e UD |
1165 | |
1166 | @item ARGP_HELP_STD_HELP | |
76b9ffef | 1167 | @standards{GNU, argp.h} |
f7364247 UD |
1168 | This prints the standard response for a @samp{--help} option, and |
1169 | terminates the program successfully. | |
b0de3e9e UD |
1170 | @end vtable |
1171 | ||
1172 | @node Argp Examples, Argp User Customization, Argp Help, Argp | |
1173 | @subsection Argp Examples | |
1174 | ||
1175 | These example programs demonstrate the basic usage of argp. | |
1176 | ||
1177 | @menu | |
1178 | * 1: Argp Example 1. A minimal program using argp. | |
1179 | * 2: Argp Example 2. A program using only default options. | |
1180 | * 3: Argp Example 3. A simple program with user options. | |
1181 | * 4: Argp Example 4. Combining multiple argp parsers. | |
1182 | @end menu | |
1183 | ||
1184 | @node Argp Example 1, Argp Example 2, , Argp Examples | |
1185 | @subsubsection A Minimal Program Using Argp | |
1186 | ||
f7364247 | 1187 | This is perhaps the smallest program possible that uses argp. It won't |
954cbda0 | 1188 | do much except give an error message and exit when there are any |
f7364247 | 1189 | arguments, and prints a rather pointless message for @samp{--help}. |
b0de3e9e UD |
1190 | |
1191 | @smallexample | |
1192 | @include argp-ex1.c.texi | |
1193 | @end smallexample | |
1194 | ||
1195 | @node Argp Example 2, Argp Example 3, Argp Example 1, Argp Examples | |
1196 | @subsubsection A Program Using Argp with Only Default Options | |
1197 | ||
f7364247 | 1198 | This program doesn't use any options or arguments, it uses argp to be |
b0de3e9e UD |
1199 | compliant with the GNU standard command line format. |
1200 | ||
f7364247 UD |
1201 | In addition to giving no arguments and implementing a @samp{--help} |
1202 | option, this example has a @samp{--version} option, which will put the | |
1203 | given documentation string and bug address in the @samp{--help} output, | |
1204 | as per GNU standards. | |
1205 | ||
1206 | The variable @code{argp} contains the argument parser | |
1207 | specification. Adding fields to this structure is the way most | |
1208 | parameters are passed to @code{argp_parse}. The first three fields are | |
1209 | normally used, but they are not in this small program. There are also | |
1210 | two global variables that argp can use defined here, | |
1211 | @code{argp_program_version} and @code{argp_program_bug_address}. They | |
1212 | are considered global variables because they will almost always be | |
1213 | constant for a given program, even if they use different argument | |
1214 | parsers for various tasks. | |
b0de3e9e UD |
1215 | |
1216 | @smallexample | |
1217 | @include argp-ex2.c.texi | |
1218 | @end smallexample | |
1219 | ||
1220 | @node Argp Example 3, Argp Example 4, Argp Example 2, Argp Examples | |
1221 | @subsubsection A Program Using Argp with User Options | |
1222 | ||
f7364247 | 1223 | This program uses the same features as example 2, adding user options |
b0de3e9e UD |
1224 | and arguments. |
1225 | ||
f7364247 UD |
1226 | We now use the first four fields in @code{argp} (@pxref{Argp Parsers}) |
1227 | and specify @code{parse_opt} as the parser function. @xref{Argp Parser | |
1228 | Functions}. | |
b0de3e9e UD |
1229 | |
1230 | Note that in this example, @code{main} uses a structure to communicate | |
1231 | with the @code{parse_opt} function, a pointer to which it passes in the | |
f7364247 UD |
1232 | @code{input} argument to @code{argp_parse}. @xref{Argp}. It is retrieved |
1233 | by @code{parse_opt} through the @code{input} field in its @code{state} | |
1234 | argument. @xref{Argp Parsing State}. Of course, it's also possible to | |
1235 | use global variables instead, but using a structure like this is | |
1236 | somewhat more flexible and clean. | |
b0de3e9e UD |
1237 | |
1238 | @smallexample | |
1239 | @include argp-ex3.c.texi | |
1240 | @end smallexample | |
1241 | ||
1242 | @node Argp Example 4, , Argp Example 3, Argp Examples | |
1243 | @subsubsection A Program Using Multiple Combined Argp Parsers | |
1244 | ||
1245 | This program uses the same features as example 3, but has more options, | |
f7364247 UD |
1246 | and presents more structure in the @samp{--help} output. It also |
1247 | illustrates how you can `steal' the remainder of the input arguments | |
1248 | past a certain point for programs that accept a list of items. It also | |
1249 | illustrates the @var{key} value @code{ARGP_KEY_NO_ARGS}, which is only | |
1250 | given if no non-option arguments were supplied to the | |
1251 | program. @xref{Argp Special Keys}. | |
1252 | ||
1253 | For structuring help output, two features are used: @emph{headers} and a | |
1254 | two part option string. The @emph{headers} are entries in the options | |
1255 | vector. @xref{Argp Option Vectors}. The first four fields are zero. The | |
1256 | two part documentation string are in the variable @code{doc}, which | |
1257 | allows documentation both before and after the options. @xref{Argp | |
7f2826c8 | 1258 | Parsers}, the two parts of @code{doc} are separated by a vertical-tab |
f7364247 UD |
1259 | character (@code{'\v'}, or @code{'\013'}). By convention, the |
1260 | documentation before the options is a short string stating what the | |
1261 | program does, and after any options it is longer, describing the | |
1262 | behavior in more detail. All documentation strings are automatically | |
1263 | filled for output, although newlines may be included to force a line | |
1264 | break at a particular point. In addition, documentation strings are | |
1265 | passed to the @code{gettext} function, for possible translation into the | |
1266 | current locale. | |
b0de3e9e UD |
1267 | |
1268 | @smallexample | |
1269 | @include argp-ex4.c.texi | |
1270 | @end smallexample | |
1271 | ||
1272 | @node Argp User Customization, , Argp Examples, Argp | |
1273 | @subsection Argp User Customization | |
1274 | ||
1275 | @cindex ARGP_HELP_FMT environment variable | |
f7364247 UD |
1276 | The formatting of argp @samp{--help} output may be controlled to some |
1277 | extent by a program's users, by setting the @code{ARGP_HELP_FMT} | |
1278 | environment variable to a comma-separated list of tokens. Whitespace is | |
1279 | ignored: | |
b0de3e9e UD |
1280 | |
1281 | @table @samp | |
1282 | @item dup-args | |
1283 | @itemx no-dup-args | |
f7364247 UD |
1284 | These turn @dfn{duplicate-argument-mode} on or off. In duplicate |
1285 | argument mode, if an option that accepts an argument has multiple names, | |
1286 | the argument is shown for each name. Otherwise, it is only shown for the | |
1287 | first long option. A note is subsequently printed so the user knows that | |
1288 | it applies to other names as well. The default is @samp{no-dup-args}, | |
b0de3e9e UD |
1289 | which is less consistent, but prettier. |
1290 | ||
1291 | @item dup-args-note | |
1292 | @item no-dup-args-note | |
f7364247 UD |
1293 | These will enable or disable the note informing the user of suppressed |
1294 | option argument duplication. The default is @samp{dup-args-note}. | |
b0de3e9e UD |
1295 | |
1296 | @item short-opt-col=@var{n} | |
f7364247 | 1297 | This prints the first short option in column @var{n}. The default is 2. |
b0de3e9e UD |
1298 | |
1299 | @item long-opt-col=@var{n} | |
f7364247 | 1300 | This prints the first long option in column @var{n}. The default is 6. |
b0de3e9e UD |
1301 | |
1302 | @item doc-opt-col=@var{n} | |
f7364247 UD |
1303 | This prints `documentation options' (@pxref{Argp Option Flags}) in |
1304 | column @var{n}. The default is 2. | |
b0de3e9e UD |
1305 | |
1306 | @item opt-doc-col=@var{n} | |
f7364247 UD |
1307 | This prints the documentation for options starting in column |
1308 | @var{n}. The default is 29. | |
b0de3e9e UD |
1309 | |
1310 | @item header-col=@var{n} | |
f7364247 UD |
1311 | This will indent the group headers that document groups of options to |
1312 | column @var{n}. The default is 1. | |
b0de3e9e UD |
1313 | |
1314 | @item usage-indent=@var{n} | |
f7364247 UD |
1315 | This will indent continuation lines in @samp{Usage:} messages to column |
1316 | @var{n}. The default is 12. | |
b0de3e9e UD |
1317 | |
1318 | @item rmargin=@var{n} | |
f7364247 UD |
1319 | This will word wrap help output at or before column @var{n}. The default |
1320 | is 79. | |
b0de3e9e | 1321 | @end table |