undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
de1fee2f1e
git-commit-vandalism/Documentation/technical/api-parse-options.txt
SZEDER Gábor fa83cc834d parse-options: add support for parsing subcommands 
Several Git commands have subcommands to implement mutually exclusive
"operation modes", and they usually parse their subcommand argument
with a bunch of if-else if statements.

Teach parse-options to handle subcommands as well, which will result
in shorter and simpler code with consistent error handling and error
messages on unknown or missing subcommand, and it will also make
possible for our Bash completion script to handle subcommands
programmatically.

The approach is guided by the following observations:

  - Most subcommands [1] are implemented in dedicated functions, and
    most of those functions [2] either have a signature matching the
    'int cmd_foo(int argc, const char **argc, const char *prefix)'
    signature of builtin commands or can be trivially converted to
    that signature, because they miss only that last prefix parameter
    or have no parameters at all.

  - Subcommand arguments only have long form, and they have no double
    dash prefix, no negated form, and no description, and they don't
    take any arguments, and can't be abbreviated.

  - There must be exactly one subcommand among the arguments, or zero
    if the command has a default operation mode.

  - All arguments following the subcommand are considered to be
    arguments of the subcommand, and, conversely, arguments meant for
    the subcommand may not preceed the subcommand.

So in the end subcommand declaration and parsing would look something
like this:

    parse_opt_subcommand_fn *fn = NULL;
    struct option builtin_commit_graph_options[] = {
        OPT_STRING(0, "object-dir", &opts.obj_dir, N_("dir"),
                   N_("the object directory to store the graph")),
        OPT_SUBCOMMAND("verify", &fn, graph_verify),
        OPT_SUBCOMMAND("write", &fn, graph_write),
        OPT_END(),
    };
    argc = parse_options(argc, argv, prefix, options,
                         builtin_commit_graph_usage, 0);
    return fn(argc, argv, prefix);

Here each OPT_SUBCOMMAND specifies the name of the subcommand and the
function implementing it, and the address of the same 'fn' subcommand
function pointer.  parse_options() then processes the arguments until
it finds the first argument matching one of the subcommands, sets 'fn'
to the function associated with that subcommand, and returns, leaving
the rest of the arguments unprocessed.  If none of the listed
subcommands is found among the arguments, parse_options() will show
usage and abort.

If a command has a default operation mode, 'fn' should be initialized
to the function implementing that mode, and parse_options() should be
invoked with the PARSE_OPT_SUBCOMMAND_OPTIONAL flag.  In this case
parse_options() won't error out when not finding any subcommands, but
will return leaving 'fn' unchanged.  Note that if that default
operation mode has any --options, then the PARSE_OPT_KEEP_UNKNOWN_OPT
flag is necessary as well (otherwise parse_options() would error out
upon seeing the unknown option meant to the default operation mode).

Some thoughts about the implementation:

  - The same pointer to 'fn' must be specified as 'value' for each
    OPT_SUBCOMMAND, because there can be only one set of mutually
    exclusive subcommands; parse_options() will BUG() otherwise.

    There are other ways to tell parse_options() where to put the
    function associated with the subcommand given on the command line,
    but I didn't like them:

      - Change parse_options()'s signature by adding a pointer to
        subcommand function to be set to the function associated with
        the given subcommand, affecting all callsites, even those that
        don't have subcommands.

      - Introduce a specific parse_options_and_subcommand() variant
        with that extra funcion parameter.

  - I decided against automatically calling the subcommand function
    from within parse_options(), because:

      - There are commands that have to perform additional actions
        after option parsing but before calling the function
        implementing the specified subcommand.

      - The return code of the subcommand is usually the return code
        of the git command, but preserving the return code of the
        automatically called subcommand function would have made the
        API awkward.

  - Also add a OPT_SUBCOMMAND_F() variant to allow specifying an
    option flag: we have two subcommands that are purposefully
    excluded from completion ('git remote rm' and 'git stash save'),
    so they'll have to be specified with the PARSE_OPT_NOCOMPLETE
    flag.

  - Some of the 'parse_opt_flags' don't make sense with subcommands,
    and using them is probably just an oversight or misunderstanding.
    Therefore parse_options() will BUG() when invoked with any of the
    following flags while the options array contains at least one
    OPT_SUBCOMMAND:

      - PARSE_OPT_KEEP_DASHDASH: parse_options() stops parsing
        arguments when encountering a "--" argument, so it doesn't
        make sense to expect and keep one before a subcommand, because
        it would prevent the parsing of the subcommand.

        However, this flag is allowed in combination with the
        PARSE_OPT_SUBCOMMAND_OPTIONAL flag, because the double dash
        might be meaningful for the command's default operation mode,
        e.g. to disambiguate refs and pathspecs.

      - PARSE_OPT_STOP_AT_NON_OPTION: As its name suggests, this flag
        tells parse_options() to stop as soon as it encouners a
        non-option argument, but subcommands are by definition not
        options...  so how could they be parsed, then?!

      - PARSE_OPT_KEEP_UNKNOWN: This flag can be used to collect any
        unknown --options and then pass them to a different command or
        subsystem.  Surely if a command has subcommands, then this
        functionality should rather be delegated to one of those
        subcommands, and not performed by the command itself.

        However, this flag is allowed in combination with the
        PARSE_OPT_SUBCOMMAND_OPTIONAL flag, making possible to pass
        --options to the default operation mode.

  - If the command with subcommands has a default operation mode, then
    all arguments to the command must preceed the arguments of the
    subcommand.

    AFAICT we don't have any commands where this makes a difference,
    because in those commands either only the command accepts any
    arguments ('notes' and 'remote'), or only the default subcommand
    ('reflog' and 'stash'), but never both.

  - The 'argv' array passed to subcommand functions currently starts
    with the name of the subcommand.  Keep this behavior.  AFAICT no
    subcommand functions depend on the actual content of 'argv[0]',
    but the parse_options() call handling their options expects that
    the options start at argv[1].

  - To support handling subcommands programmatically in our Bash
    completion script, 'git cmd --git-completion-helper' will now list
    both subcommands and regular --options, if any.  This means that
    the completion script will have to separate subcommands (i.e.
    words without a double dash prefix) from --options on its own, but
    that's rather easy to do, and it's not much work either, because
    the number of subcommands a command might have is rather low, and
    those commands accept only a single --option or none at all.  An
    alternative would be to introduce a separate option that lists
    only subcommands, but then the completion script would need not
    one but two git invocations and command substitutions for commands
    with subcommands.

    Note that this change doesn't affect the behavior of our Bash
    completion script, because when completing the --option of a
    command with subcommands, e.g. for 'git notes --<TAB>', then all
    subcommands will be filtered out anyway, as none of them will
    match the word to be completed starting with that double dash
    prefix.

[1] Except 'git rerere', because many of its subcommands are
    implemented in the bodies of the if-else if statements parsing the
    command's subcommand argument.

[2] Except 'credential', 'credential-store' and 'fsmonitor--daemon',
    because some of the functions implementing their subcommands take
    special parameters.

Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-08-19 11:13:14 -07:00

350 lines
13 KiB
Plaintext
Raw Blame History

parse-options API
=================
The parse-options API is used to parse and massage options in Git
and to provide a usage help with consistent look.
Basics
------
The argument vector `argv[]` may usually contain mandatory or optional
'non-option arguments', e.g. a filename or a branch, 'options', and
'subcommands'.
Options are optional arguments that start with a dash and
that allow to change the behavior of a command.
* There are basically three types of options:
'boolean' options,
options with (mandatory) 'arguments' and
options with 'optional arguments'
(i.e. a boolean option that can be adjusted).
* There are basically two forms of options:
'Short options' consist of one dash (`-`) and one alphanumeric
character.
'Long options' begin with two dashes (`--`) and some
alphanumeric characters.
* Options are case-sensitive.
Please define 'lower-case long options' only.
The parse-options API allows:
* 'stuck' and 'separate form' of options with arguments.
`-oArg` is stuck, `-o Arg` is separate form.
`--option=Arg` is stuck, `--option Arg` is separate form.
* Long options may be 'abbreviated', as long as the abbreviation
is unambiguous.
* Short options may be bundled, e.g. `-a -b` can be specified as `-ab`.
* Boolean long options can be 'negated' (or 'unset') by prepending
`no-`, e.g. `--no-abbrev` instead of `--abbrev`. Conversely,
options that begin with `no-` can be 'negated' by removing it.
Other long options can be unset (e.g., set string to NULL, set
integer to 0) by prepending `no-`.
* Options and non-option arguments can clearly be separated using the `--`
option, e.g. `-a -b --option -- --this-is-a-file` indicates that
`--this-is-a-file` must not be processed as an option.
Subcommands are special in a couple of ways:
* Subcommands only have long form, and they have no double dash prefix, no
negated form, and no description, and they don't take any arguments, and
can't be abbreviated.
* There must be exactly one subcommand among the arguments, or zero if the
command has a default operation mode.
* All arguments following the subcommand are considered to be arguments of
the subcommand, and, conversely, arguments meant for the subcommand may
not preceed the subcommand.
Therefore, if the options array contains at least one subcommand and
`parse_options()` encounters the first dashless argument, it will either:
* stop and return, if that dashless argument is a known subcommand, setting
`value` to the function pointer associated with that subcommand, storing
the name of the subcommand in argv[0], and leaving the rest of the
arguments unprocessed, or
* stop and return, if it was invoked with the `PARSE_OPT_SUBCOMMAND_OPTIONAL`
flag and that dashless argument doesn't match any subcommands, leaving
`value` unchanged and the rest of the arguments unprocessed, or
* show error and usage, and abort.
Steps to parse options
----------------------
. `#include "parse-options.h"`
. define a NULL-terminated
`static const char * const builtin_foo_usage[]` array
containing alternative usage strings
. define `builtin_foo_options` array as described below
in section 'Data Structure'.
. in `cmd_foo(int argc, const char **argv, const char *prefix)`
call
argc = parse_options(argc, argv, prefix, builtin_foo_options, builtin_foo_usage, flags);
+
`parse_options()` will filter out the processed options of `argv[]` and leave the
non-option arguments in `argv[]`.
`argc` is updated appropriately because of the assignment.
+
You can also pass NULL instead of a usage array as the fifth parameter of
parse_options(), to avoid displaying a help screen with usage info and
option list. This should only be done if necessary, e.g. to implement
a limited parser for only a subset of the options that needs to be run
before the full parser, which in turn shows the full help message.
+
Flags are the bitwise-or of:
`PARSE_OPT_KEEP_DASHDASH`::
Keep the `--` that usually separates options from
non-option arguments.
`PARSE_OPT_STOP_AT_NON_OPTION`::
Usually the whole argument vector is massaged and reordered.
Using this flag, processing is stopped at the first non-option
argument.
`PARSE_OPT_KEEP_ARGV0`::
Keep the first argument, which contains the program name. It's
removed from argv[] by default.
`PARSE_OPT_KEEP_UNKNOWN_OPT`::
Keep unknown options instead of erroring out. This doesn't
work for all combinations of arguments as users might expect
it to do. E.g. if the first argument in `--unknown --known`
takes a value (which we can't know), the second one is
mistakenly interpreted as a known option. Similarly, if
`PARSE_OPT_STOP_AT_NON_OPTION` is set, the second argument in
`--unknown value` will be mistakenly interpreted as a
non-option, not as a value belonging to the unknown option,
the parser early. That's why parse_options() errors out if
both options are set.
Note that non-option arguments are always kept, even without
this flag.
`PARSE_OPT_NO_INTERNAL_HELP`::
By default, parse_options() handles `-h`, `--help` and
`--help-all` internally, by showing a help screen. This option
turns it off and allows one to add custom handlers for these
options, or to just leave them unknown.
`PARSE_OPT_SUBCOMMAND_OPTIONAL`::
Don't error out when no subcommand is specified.
Note that `PARSE_OPT_STOP_AT_NON_OPTION` is incompatible with subcommands;
while `PARSE_OPT_KEEP_DASHDASH` and `PARSE_OPT_KEEP_UNKNOWN_OPT` can only be
used with subcommands when combined with `PARSE_OPT_SUBCOMMAND_OPTIONAL`.
Data Structure
--------------
The main data structure is an array of the `option` struct,
say `static struct option builtin_add_options[]`.
There are some macros to easily define options:
`OPT__ABBREV(&int_var)`::
Add `--abbrev[=<n>]`.
`OPT__COLOR(&int_var, description)`::
Add `--color[=<when>]` and `--no-color`.
`OPT__DRY_RUN(&int_var, description)`::
Add `-n, --dry-run`.
`OPT__FORCE(&int_var, description)`::
Add `-f, --force`.
`OPT__QUIET(&int_var, description)`::
Add `-q, --quiet`.
`OPT__VERBOSE(&int_var, description)`::
Add `-v, --verbose`.
`OPT_GROUP(description)`::
Start an option group. `description` is a short string that
describes the group or an empty string.
Start the description with an upper-case letter.
`OPT_BOOL(short, long, &int_var, description)`::
Introduce a boolean option. `int_var` is set to one with
`--option` and set to zero with `--no-option`.
`OPT_COUNTUP(short, long, &int_var, description)`::
Introduce a count-up option.
Each use of `--option` increments `int_var`, starting from zero
(even if initially negative), and `--no-option` resets it to
zero. To determine if `--option` or `--no-option` was encountered at
all, initialize `int_var` to a negative value, and if it is still
negative after parse_options(), then neither `--option` nor
`--no-option` was seen.
`OPT_BIT(short, long, &int_var, description, mask)`::
Introduce a boolean option.
If used, `int_var` is bitwise-ored with `mask`.
`OPT_NEGBIT(short, long, &int_var, description, mask)`::
Introduce a boolean option.
If used, `int_var` is bitwise-anded with the inverted `mask`.
`OPT_SET_INT(short, long, &int_var, description, integer)`::
Introduce an integer option.
`int_var` is set to `integer` with `--option`, and
reset to zero with `--no-option`.
`OPT_STRING(short, long, &str_var, arg_str, description)`::
Introduce an option with string argument.
The string argument is put into `str_var`.
`OPT_STRING_LIST(short, long, &struct string_list, arg_str, description)`::
Introduce an option with string argument.
The string argument is stored as an element in `string_list`.
Use of `--no-option` will clear the list of preceding values.
`OPT_INTEGER(short, long, &int_var, description)`::
Introduce an option with integer argument.
The integer is put into `int_var`.
`OPT_MAGNITUDE(short, long, &unsigned_long_var, description)`::
Introduce an option with a size argument. The argument must be a
non-negative integer and may include a suffix of 'k', 'm' or 'g' to
scale the provided value by 1024, 1024^2 or 1024^3 respectively.
The scaled value is put into `unsigned_long_var`.
`OPT_EXPIRY_DATE(short, long, &timestamp_t_var, description)`::
Introduce an option with expiry date argument, see `parse_expiry_date()`.
The timestamp is put into `timestamp_t_var`.
`OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`::
Introduce an option with argument.
The argument will be fed into the function given by `func_ptr`
and the result will be put into `var`.
See 'Option Callbacks' below for a more elaborate description.
`OPT_FILENAME(short, long, &var, description)`::
Introduce an option with a filename argument.
The filename will be prefixed by passing the filename along with
the prefix argument of `parse_options()` to `prefix_filename()`.
`OPT_NUMBER_CALLBACK(&var, description, func_ptr)`::
Recognize numerical options like -123 and feed the integer as
if it was an argument to the function given by `func_ptr`.
The result will be put into `var`. There can be only one such
option definition. It cannot be negated and it takes no
arguments. Short options that happen to be digits take
precedence over it.
`OPT_COLOR_FLAG(short, long, &int_var, description)`::
Introduce an option that takes an optional argument that can
have one of three values: "always", "never", or "auto". If the
argument is not given, it defaults to "always". The `--no-` form
works like `--long=never`; it cannot take an argument. If
"always", set `int_var` to 1; if "never", set `int_var` to 0; if
"auto", set `int_var` to 1 if stdout is a tty or a pager,
0 otherwise.
`OPT_NOOP_NOARG(short, long)`::
Introduce an option that has no effect and takes no arguments.
Use it to hide deprecated options that are still to be recognized
and ignored silently.
`OPT_PASSTHRU(short, long, &char_var, arg_str, description, flags)`::
Introduce an option that will be reconstructed into a char* string,
which must be initialized to NULL. This is useful when you need to
pass the command-line option to another command. Any previous value
will be overwritten, so this should only be used for options where
the last one specified on the command line wins.
`OPT_PASSTHRU_ARGV(short, long, &strvec_var, arg_str, description, flags)`::
Introduce an option where all instances of it on the command-line will
be reconstructed into a strvec. This is useful when you need to
pass the command-line option, which can be specified multiple times,
to another command.
`OPT_CMDMODE(short, long, &int_var, description, enum_val)`::
Define an "operation 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. `int_var` is set to `enum_val` 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`.
In new commands consider using subcommands instead.
`OPT_SUBCOMMAND(long, &fn_ptr, subcommand_fn)`::
Define a subcommand. `subcommand_fn` is put into `fn_ptr` when
this subcommand is used.
The last element of the array must be `OPT_END()`.
If not stated otherwise, interpret the arguments as follows:
* `short` is a character for the short option
(e.g. `'e'` for `-e`, use `0` to omit),
* `long` is a string for the long option
(e.g. `"example"` for `--example`, use `NULL` to omit),
* `int_var` is an integer variable,
* `str_var` is a string variable (`char *`),
* `arg_str` is the string that is shown as argument
(e.g. `"branch"` will result in `<branch>`).
If set to `NULL`, three dots (`...`) will be displayed.
* `description` is a short string to describe the effect of the option.
It shall begin with a lower-case letter and a full stop (`.`) shall be
omitted at the end.
Option Callbacks
----------------
The function must be defined in this form:
int func(const struct option *opt, const char *arg, int unset)
The callback mechanism is as follows:
* Inside `func`, the only interesting member of the structure
given by `opt` is the void pointer `opt->value`.
`*opt->value` will be the value that is saved into `var`, if you
use `OPT_CALLBACK()`.
For example, do `*(unsigned long *)opt->value = 42;` to get 42
into an `unsigned long` variable.
* Return value `0` indicates success and non-zero return
value will invoke `usage_with_options()` and, thus, die.
* If the user negates the option, `arg` is `NULL` and `unset` is 1.
Sophisticated option parsing
----------------------------
If you need, for example, option callbacks with optional arguments
or without arguments at all, or if you need other special cases,
that are not handled by the macros above, you need to specify the
members of the `option` structure manually.
This is not covered in this document, but well documented
in `parse-options.h` itself.
Examples
--------
See `test-parse-options.c` and
`builtin/add.c`,
`builtin/clone.c`,
`builtin/commit.c`,
`builtin/fetch.c`,
`builtin/fsck.c`,
`builtin/rm.c`
for real-world examples.
Reference in New Issue View Git Blame Copy Permalink