Merge branch 'maint-1.7.6' into maint-1.7.7
[gitweb.git] / Documentation / technical / api-parse-options.txt
index 539863b1f920f8f34ad9272907cbacbd35a7fcbd..f6a4a361bd56e1cc0f4645e09898e6852bfb8a8b 100644 (file)
@@ -60,12 +60,18 @@ Steps to parse options
 . in `cmd_foo(int argc, const char **argv, const char *prefix)`
   call
 
-       argc = parse_options(argc, argv, builtin_foo_options, builtin_foo_usage, flags);
+       argc = parse_options(argc, argv, prefix, builtin_foo_options, builtin_foo_usage, flags);
 +
 `parse_options()` will filter out the processed options of `argv[]` and leave the
 non-option arguments in `argv[]`.
 `argc` is updated appropriately because of the assignment.
 +
+You can also pass NULL instead of a usage array as the fifth parameter of
+parse_options(), to avoid displaying a help screen with usage info and
+option list.  This should only be done if necessary, e.g. to implement
+a limited parser for only a subset of the options that needs to be run
+before the full parser, which in turn shows the full help message.
++
 Flags are the bitwise-or of:
 
 `PARSE_OPT_KEEP_DASHDASH`::
@@ -77,6 +83,28 @@ Flags are the bitwise-or of:
        Using this flag, processing is stopped at the first non-option
        argument.
 
+`PARSE_OPT_KEEP_ARGV0`::
+       Keep the first argument, which contains the program name.  It's
+       removed from argv[] by default.
+
+`PARSE_OPT_KEEP_UNKNOWN`::
+       Keep unknown arguments instead of erroring out.  This doesn't
+       work for all combinations of arguments as users might expect
+       it to do.  E.g. if the first argument in `--unknown --known`
+       takes a value (which we can't know), the second one is
+       mistakenly interpreted as a known option.  Similarly, if
+       `PARSE_OPT_STOP_AT_NON_OPTION` is set, the second argument in
+       `--unknown value` will be mistakenly interpreted as a
+       non-option, not as a value belonging to the unknown option,
+       the parser early.  That's why parse_options() errors out if
+       both options are set.
+
+`PARSE_OPT_NO_INTERNAL_HELP`::
+       By default, parse_options() handles `-h`, `--help` and
+       `--help-all` internally, by showing a help screen.  This option
+       turns it off and allows one to add custom handlers for these
+       options, or to just leave them unknown.
+
 Data Structure
 --------------
 
@@ -87,13 +115,19 @@ There are some macros to easily define options:
 `OPT__ABBREV(&int_var)`::
        Add `\--abbrev[=<n>]`.
 
-`OPT__DRY_RUN(&int_var)`::
+`OPT__COLOR(&int_var, description)`::
+       Add `\--color[=<when>]` and `--no-color`.
+
+`OPT__DRY_RUN(&int_var, description)`::
        Add `-n, \--dry-run`.
 
-`OPT__QUIET(&int_var)`::
+`OPT__FORCE(&int_var, description)`::
+       Add `-f, \--force`.
+
+`OPT__QUIET(&int_var, description)`::
        Add `-q, \--quiet`.
 
-`OPT__VERBOSE(&int_var)`::
+`OPT__VERBOSE(&int_var, description)`::
        Add `-v, \--verbose`.
 
 `OPT_GROUP(description)`::
@@ -109,6 +143,10 @@ There are some macros to easily define options:
        Introduce a boolean option.
        If used, `int_var` is bitwise-ored with `mask`.
 
+`OPT_NEGBIT(short, long, &int_var, description, mask)`::
+       Introduce a boolean option.
+       If used, `int_var` is bitwise-anded with the inverted `mask`.
+
 `OPT_SET_INT(short, long, &int_var, description, integer)`::
        Introduce a boolean option.
        If used, set `int_var` to `integer`.
@@ -135,16 +173,38 @@ There are some macros to easily define options:
        and the result will be put into `var`.
        See 'Option Callbacks' below for a more elaborate description.
 
+`OPT_FILENAME(short, long, &var, description)`::
+       Introduce an option with a filename argument.
+       The filename will be prefixed by passing the filename along with
+       the prefix argument of `parse_options()` to `prefix_filename()`.
+
 `OPT_ARGUMENT(long, description)`::
        Introduce a long-option argument that will be kept in `argv[]`.
 
+`OPT_NUMBER_CALLBACK(&var, description, func_ptr)`::
+       Recognize numerical options like -123 and feed the integer as
+       if it was an argument to the function given by `func_ptr`.
+       The result will be put into `var`.  There can be only one such
+       option definition.  It cannot be negated and it takes no
+       arguments.  Short options that happen to be digits take
+       precedence over it.
+
+`OPT_COLOR_FLAG(short, long, &int_var, description)`::
+       Introduce an option that takes an optional argument that can
+       have one of three values: "always", "never", or "auto".  If the
+       argument is not given, it defaults to "always".  The `--no-` form
+       works like `--long=never`; it cannot take an argument.  If
+       "always", set `int_var` to 1; if "never", set `int_var` to 0; if
+       "auto", set `int_var` to 1 if stdout is a tty or a pager,
+       0 otherwise.
+
 
 The last element of the array must be `OPT_END()`.
 
 If not stated otherwise, interpret the arguments as follows:
 
 * `short` is a character for the short option
-  (e.g. `\'e\'` for `-e`, use `0` to omit),
+  (e.g. `{apostrophe}e{apostrophe}` for `-e`, use `0` to omit),
 
 * `long` is a string for the long option
   (e.g. `"example"` for `\--example`, use `NULL` to omit),
@@ -170,11 +230,11 @@ The function must be defined in this form:
 
 The callback mechanism is as follows:
 
-* Inside `funct`, the only interesting member of the structure
-  given by `opt` is the void pointer `opt->value`.
-  `\*opt->value` will be the value that is saved into `var`, if you
+* Inside `func`, the only interesting member of the structure
+  given by `opt` is the void pointer `opt\->value`.
+  `\*opt\->value` will be the value that is saved into `var`, if you
   use `OPT_CALLBACK()`.
-  For example, do `*(unsigned long *)opt->value = 42;` to get 42
+  For example, do `*(unsigned long *)opt\->value = 42;` to get 42
   into an `unsigned long` variable.
 
 * Return value `0` indicates success and non-zero return