Re: [PATCH] api-parse-options.txt: document OPT_CMDMODE()
From: Junio C Hamano <hidden>
Date: 2016-06-15 23:08:56
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?
quoted hunk
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.