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

Pranit Bauva [off-list ref] 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?

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.

On Thu, Mar 24, 2016 at 9:37 PM, Junio C Hamano [off-list ref] wrote:

Pranit Bauva [off-list ref] writes:

quoted

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?

Will include this.

quoted

 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.

What I meant by this statement is that (your example), let's say we
have "add", "remove" and "edit" sub commands. Now the user has to pick
between the three. He cannot choose more than 1 from these.

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.

Thanks for taking time to explain all the details behind it. I can
include these bits in the documentation. :)