Re: [PATCH] api-parse-options.txt: document OPT_CMDMODE()

[Junio C Hamano <gitster@pobox.com>]

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.
> ---

Sign-off?

>  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.