parse-options: deprecate OPT_BOOLEAN
commitb04ba2bb42957f63567f530e092385f085b25e63
authorJunio C Hamano <gitster@pobox.com>
Tue, 27 Sep 2011 23:56:49 +0000 (27 16:56 -0700)
committerJunio C Hamano <gitster@pobox.com>
Wed, 28 Sep 2011 00:00:04 +0000 (27 17:00 -0700)
tree995067e56b042a7d4d9df32a50268ef614972737
parent8d714b11df2b65e5f4272c1616e561930010be90
parse-options: deprecate OPT_BOOLEAN

It is natural to expect that an option defined with OPT_BOOLEAN() could be
used in this way:

int option = -1; /* unspecified */

struct option options[] = {
OPT_BOOLEAN(0, "option", &option, "set option"),
                OPT_END()
};
parse_options(ac, av, prefix, options, usage, 0);

        if (option < 0)
         ... do the default thing ...
else if (!option)
... --no-option was given ...
else
... --option was given ...

to easily tell three cases apart:

 - There is no mention of the `--option` on the command line;
 - The variable is positively set with `--option`; or
 - The variable is explicitly negated with `--no-option`.

Unfortunately, this is not the case. OPT_BOOLEAN() increments the variable
every time `--option` is given, and resets it to zero when `--no-option`
is given.

As a first step to remedy this, introduce a true boolean OPT_BOOL(), and
rename OPT_BOOLEAN() to OPT_COUNTUP(). To help transitioning, OPT_BOOLEAN
and OPTION_BOOLEAN are defined as deprecated synonyms to OPT_COUNTUP and
OPTION_COUNTUP respectively.

This is what db7244b (parse-options new features., 2007-11-07) from four
years ago started by marking OPTION_BOOLEAN as "INCR would have been a
better name".

Some existing users do depend on the count-up semantics; for example,
users of OPT__VERBOSE() could use it to raise the verbosity level with
repeated use of `-v` on the command line, but they probably should be
rewritten to use OPT__VERBOSITY() instead these days.  I suspect that some
users of OPT__FORCE() may also use it to implement different level of
forcibleness but I didn't check.

On top of this patch, here are the remaining clean-up tasks that other
people can help:

 - Look at each hit in "git grep -e OPT_BOOLEAN"; trace all uses of the
   value that is set to the underlying variable, and if it can proven that
   the variable is only used as a boolean, replace it with OPT_BOOL(). If
   the caller does depend on the count-up semantics, replace it with
   OPT_COUNTUP() instead.

 - Same for OPTION_BOOLEAN; replace it with OPTION_SET_INT and arrange to
   set 1 to the variable for a true boolean, and otherwise replace it with
   OPTION_COUNTUP.

 - Look at each hit in "git grep -e OPT__VERBOSE -e OPT__QUIET" and see if
   they can be replaced with OPT__VERBOSITY().

I'll follow this message up with a separate patch as an example.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
Documentation/technical/api-parse-options.txt
parse-options.c
parse-options.h