parseopt: document KEEP_ARGV0, KEEP_UNKNOWN, NO_INTERNAL_HELP
Signed-off-by: Rene Scharfe <rene.scharfe@lsrfire.ath.cx> Signed-off-by: Junio C Hamano <gitster@pobox.com>
René Scharfe committed
Mar 9, 2009 at 21:26 UTC
9ad7e6ea24739c298d0a9660121de6df0502915a
1 file changed
+27
Documentation/technical/api-parse-options.txt
+27
@@ -66,6 +66,12 @@ Steps to parse options
66
non-option arguments in `argv[]`.
67
`argc` is updated appropriately because of the assignment.
68
+
69
+You can also pass NULL instead of a usage array as fourth parameter of
70
+parse_options(), to avoid displaying a help screen with usage info and
71
+option list. This should only be done if necessary, e.g. to implement
72
+a limited parser for only a subset of the options that needs to be run
73
+before the full parser, which in turn shows the full help message.
74
++
75
Flags are the bitwise-or of:
76
77
`PARSE_OPT_KEEP_DASHDASH`::
@@ -77,6 +83,27 @@ Flags are the bitwise-or of:
83
Using this flag, processing is stopped at the first non-option
84
argument.
85
86
+`PARSE_OPT_KEEP_ARGV0`::
87
+ Keep the first argument, which contains the program name. It's
88
+ removed from argv[] by default.
89
+
90
+`PARSE_OPT_KEEP_UNKNOWN`::
91
+ Keep unknown arguments instead of erroring out. This doesn't
92
+ work for all combinations of arguments as users might expect
93
+ it to do. E.g. if the first argument in `--unknown --known`
94
+ takes a value (which we can't know), the second one is
95
+ mistakenly interpreted as a known option. Similarly, if
96
+ `PARSE_OPT_STOP_AT_NON_OPTION` is set, the second argument in
97
+ `--unknown value` will be mistakenly interpreted as a
98
+ non-option, not as a value belonging to the unknown option,
99
+ stopping the parser early.
100
+
101
+`PARSE_OPT_NO_INTERNAL_HELP`::
102
+ By default, parse_options() handles `-h`, `--help` and
103
+ `--help-all` internally, by showing a help screen. This option
104
+ turns it off and allows one to add custom handlers for these
105
+ options, or to just leave them unknown.
106
+
107
Data Structure
108
--------------
109