Re: [PATCH] api-parse-options.txt: document OPT_CMDMODE()
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Mar 24, 2016, 16:07 UTC
- Message-ID
- <xmqqtwjvamhe.fsf@gitster.mtv.corp.google.com>
- In-Reply-To
- <01020153a7e08100-cf66fc9f-7293-4d8c-98c6-f322721c741f-000000@eu-west-1.amazonses.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?
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.