Re: [PATCH] api-parse-options.txt: document OPT_CMDMODE()
Pranit Bauva <pranit.bauva@gmail.com> writes:
> OPT_CMDMODE() was introduced in the release of 1.8.5 which makes the use
> of subcommands in the form of arguments a lot cleaner and easier.
> ---
Show 17 quoted lines
> Documentation/technical/api-parse-options.txt | 6 ++++++
> 1 file changed, 6 insertions(+)
>
> diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt
> index 5f0757d..8130d26 100644
> --- a/Documentation/technical/api-parse-options.txt
> +++ b/Documentation/technical/api-parse-options.txt
> @@ -231,6 +231,12 @@ There are some macros to easily define options:
> pass the command-line option, which can be specified multiple times,
> to another command.
>
> +`OPT_CMDMODE(short, long, &int_var, description, enum_val)`::
> + Introduce an option for subcommands. It is useful when you want to use
> + the command with a particular sub command only and ignore other sub
> + commands it has. It will set `int_var` to enum_val if the argument is
> + invoked.
> +
Sorry, but I do not get what "when you want to... ignore other sub command it has" wants to say.
CMDMODE is a mechanism to actively notice when multiple "operation mode" options that specify mutually incompatible operation modes are given and error out without the user of parse_options() to implement that mutual exclusion herself. That is, if you have 'add', 'remove' and 'edit' operation modes, with OPT_BOOL(), you would have to say:
options[] = {
OPT_BOOL('a', "add", &add, ...),
OPT_BOOL('r', "remove", &remove, ...),
OPT_BOOL('e', "edit", &edit, ...),
...
};
parse_options(ac, av, prefix, options, ...); if (!!add + !!remove + !!edit > 1)
die("at most one add/remove/edit can be used at a time"); if (add)
do_add();
if (remove)
do_remove();
if (edit)
do_edit();but with CMDMODE, you can do:
options[] = {
OPT_BOOL('a', "add", &mode, ...),
OPT_BOOL('r', "remove", &mode, ...),
OPT_BOOL('e', "edit", &mode, ...),
...
};
parse_options(ac, av, prefix, options, ...); switch (mode) {
case 'a': do_add(); break;
case 'r': do_remove(); break;
case 'e': do_edit(); break;
...
}and parse_options notices that "mode" is shared across these three options, and implements the mutual-exclusion itself.
Pranit Bauva