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

[Pranit Bauva]

On Thu, Mar 24, 2016 at 10:46 PM, Junio C Hamano  wrote:
> Pranit Bauva  writes:
>
 +`OPT_CMDMODE(short, long, _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.
>
> Then I find the word "ignore others" misleading.  Quite the
> contrary, the user has to be aware of the others and not to give
> them.
>
> Define an "operating mode" option, only one of which in the
> same group of "operating mode" options that share the same
> `int_var` can be given by the user.  `enum_val` is set to
> `int_var` when the option is used, but an error is reported
> if other "operating mode" option has already set its value
> to the same `int_var`.
>
> or something?

Seems a crystal clear explanation to me. Thanks. I was unaware that it
throws an error.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Junio C Hamano]

Pranit Bauva  writes:

>>> +`OPT_CMDMODE(short, long, _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.

Then I find the word "ignore others" misleading.  Quite the
contrary, the user has to be aware of the others and not to give
them.

Define an "operating mode" option, only one of which in the
same group of "operating mode" options that share the same
`int_var` can be given by the user.  `enum_val` is set to
`int_var` when the option is used, but an error is reported
if other "operating mode" option has already set its value
to the same `int_var`.

or something?

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Pranit Bauva]

On Thu, Mar 24, 2016 at 9:37 PM, Junio C Hamano  wrote:
> Pranit Bauva  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?

Will include this.

>>  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, _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", , ...),
> OPT_BOOL('r', "remove", , ...),
> OPT_BOOL('e', "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", , ...),
> OPT_BOOL('r', "remove", , ...),
> OPT_BOOL('e', "edit", , ...),
> ...
> };
> 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. :)
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Junio C Hamano]

Pranit Bauva  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, _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", , ...),
OPT_BOOL('r', "remove", , ...),
OPT_BOOL('e', "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", , ...),
OPT_BOOL('r', "remove", , ...),
OPT_BOOL('e', "edit", , ...),
...
};
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.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html