<commit_before>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, and 'options'.
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:

* 'sticked' and 'separate form' of options with arguments.
  `-oArg` is sticked, `-o Arg` is separate form.
  `\--option=Arg` is sticked, `\--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`.

* 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.

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, 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.
+
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.

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__DRY_RUN(&int_var)`::
	Add `-n, \--dry-run`.

`OPT__QUIET(&int_var)`::
	Add `-q, \--quiet`.

`OPT__VERBOSE(&int_var)`::
	Add `-v, \--verbose`.

`OPT_GROUP(description)`::<commit_msg>parseopt: document KEEP_ARGV0, KEEP_UNKNOWN, NO_INTERNAL_HELP<commit_after>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, and 'options'.
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:

* 'sticked' and 'separate form' of options with arguments.
  `-oArg` is sticked, `-o Arg` is separate form.
  `\--option=Arg` is sticked, `\--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`.

* 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.

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, 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 fourth 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`::
	Keep unknown arguments 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,
	stopping the parser early.

`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.

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__DRY_RUN(&int_var)`::
	Add `-n, \--dry-run`.

`OPT__QUIET(&int_var)`::
	Add `-q, \--quiet`.

`OPT__VERBOSE(&int_var)`::
	Add `-v, \--verbose`.

`OPT_GROUP(description)`::
{'fraction_non_alphanumeric': 0.11809497438737367, 'fraction_numerical': 0.00027689325764917625, 'mean_word_length': 3.7968127490039842, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2641287', 'n_tokens_mistral': 2271, 'n_tokens_neox': 2229, 'n_words': 932}