"Fossies" - the Fresh Open Source Software Archive

Member "technical/api-parse-options.txt" (15 Dec 2018, 11508 Bytes) of package /linux/misc/git-htmldocs-2.20.1.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "api-parse-options.txt": 2.19.2_vs_2.20.0.

    1 parse-options API
    2 =================
    3 
    4 The parse-options API is used to parse and massage options in Git
    5 and to provide a usage help with consistent look.
    6 
    7 Basics
    8 ------
    9 
   10 The argument vector `argv[]` may usually contain mandatory or optional
   11 'non-option arguments', e.g. a filename or a branch, and 'options'.
   12 Options are optional arguments that start with a dash and
   13 that allow to change the behavior of a command.
   14 
   15 * There are basically three types of options:
   16   'boolean' options,
   17   options with (mandatory) 'arguments' and
   18   options with 'optional arguments'
   19   (i.e. a boolean option that can be adjusted).
   20 
   21 * There are basically two forms of options:
   22   'Short options' consist of one dash (`-`) and one alphanumeric
   23   character.
   24   'Long options' begin with two dashes (`--`) and some
   25   alphanumeric characters.
   26 
   27 * Options are case-sensitive.
   28   Please define 'lower-case long options' only.
   29 
   30 The parse-options API allows:
   31 
   32 * 'stuck' and 'separate form' of options with arguments.
   33   `-oArg` is stuck, `-o Arg` is separate form.
   34   `--option=Arg` is stuck, `--option Arg` is separate form.
   35 
   36 * Long options may be 'abbreviated', as long as the abbreviation
   37   is unambiguous.
   38 
   39 * Short options may be bundled, e.g. `-a -b` can be specified as `-ab`.
   40 
   41 * Boolean long options can be 'negated' (or 'unset') by prepending
   42   `no-`, e.g. `--no-abbrev` instead of `--abbrev`. Conversely,
   43   options that begin with `no-` can be 'negated' by removing it.
   44   Other long options can be unset (e.g., set string to NULL, set
   45   integer to 0) by prepending `no-`.
   46 
   47 * Options and non-option arguments can clearly be separated using the `--`
   48   option, e.g. `-a -b --option -- --this-is-a-file` indicates that
   49   `--this-is-a-file` must not be processed as an option.
   50 
   51 Steps to parse options
   52 ----------------------
   53 
   54 . `#include "parse-options.h"`
   55 
   56 . define a NULL-terminated
   57   `static const char * const builtin_foo_usage[]` array
   58   containing alternative usage strings
   59 
   60 . define `builtin_foo_options` array as described below
   61   in section 'Data Structure'.
   62 
   63 . in `cmd_foo(int argc, const char **argv, const char *prefix)`
   64   call
   65 
   66 	argc = parse_options(argc, argv, prefix, builtin_foo_options, builtin_foo_usage, flags);
   67 +
   68 `parse_options()` will filter out the processed options of `argv[]` and leave the
   69 non-option arguments in `argv[]`.
   70 `argc` is updated appropriately because of the assignment.
   71 +
   72 You can also pass NULL instead of a usage array as the fifth parameter of
   73 parse_options(), to avoid displaying a help screen with usage info and
   74 option list.  This should only be done if necessary, e.g. to implement
   75 a limited parser for only a subset of the options that needs to be run
   76 before the full parser, which in turn shows the full help message.
   77 +
   78 Flags are the bitwise-or of:
   79 
   80 `PARSE_OPT_KEEP_DASHDASH`::
   81 	Keep the `--` that usually separates options from
   82 	non-option arguments.
   83 
   84 `PARSE_OPT_STOP_AT_NON_OPTION`::
   85 	Usually the whole argument vector is massaged and reordered.
   86 	Using this flag, processing is stopped at the first non-option
   87 	argument.
   88 
   89 `PARSE_OPT_KEEP_ARGV0`::
   90 	Keep the first argument, which contains the program name.  It's
   91 	removed from argv[] by default.
   92 
   93 `PARSE_OPT_KEEP_UNKNOWN`::
   94 	Keep unknown arguments instead of erroring out.  This doesn't
   95 	work for all combinations of arguments as users might expect
   96 	it to do.  E.g. if the first argument in `--unknown --known`
   97 	takes a value (which we can't know), the second one is
   98 	mistakenly interpreted as a known option.  Similarly, if
   99 	`PARSE_OPT_STOP_AT_NON_OPTION` is set, the second argument in
  100 	`--unknown value` will be mistakenly interpreted as a
  101 	non-option, not as a value belonging to the unknown option,
  102 	the parser early.  That's why parse_options() errors out if
  103 	both options are set.
  104 
  105 `PARSE_OPT_NO_INTERNAL_HELP`::
  106 	By default, parse_options() handles `-h`, `--help` and
  107 	`--help-all` internally, by showing a help screen.  This option
  108 	turns it off and allows one to add custom handlers for these
  109 	options, or to just leave them unknown.
  110 
  111 Data Structure
  112 --------------
  113 
  114 The main data structure is an array of the `option` struct,
  115 say `static struct option builtin_add_options[]`.
  116 There are some macros to easily define options:
  117 
  118 `OPT__ABBREV(&int_var)`::
  119 	Add `--abbrev[=<n>]`.
  120 
  121 `OPT__COLOR(&int_var, description)`::
  122 	Add `--color[=<when>]` and `--no-color`.
  123 
  124 `OPT__DRY_RUN(&int_var, description)`::
  125 	Add `-n, --dry-run`.
  126 
  127 `OPT__FORCE(&int_var, description)`::
  128 	Add `-f, --force`.
  129 
  130 `OPT__QUIET(&int_var, description)`::
  131 	Add `-q, --quiet`.
  132 
  133 `OPT__VERBOSE(&int_var, description)`::
  134 	Add `-v, --verbose`.
  135 
  136 `OPT_GROUP(description)`::
  137 	Start an option group. `description` is a short string that
  138 	describes the group or an empty string.
  139 	Start the description with an upper-case letter.
  140 
  141 `OPT_BOOL(short, long, &int_var, description)`::
  142 	Introduce a boolean option. `int_var` is set to one with
  143 	`--option` and set to zero with `--no-option`.
  144 
  145 `OPT_COUNTUP(short, long, &int_var, description)`::
  146 	Introduce a count-up option.
  147 	Each use of `--option` increments `int_var`, starting from zero
  148 	(even if initially negative), and `--no-option` resets it to
  149 	zero. To determine if `--option` or `--no-option` was encountered at
  150 	all, initialize `int_var` to a negative value, and if it is still
  151 	negative after parse_options(), then neither `--option` nor
  152 	`--no-option` was seen.
  153 
  154 `OPT_BIT(short, long, &int_var, description, mask)`::
  155 	Introduce a boolean option.
  156 	If used, `int_var` is bitwise-ored with `mask`.
  157 
  158 `OPT_NEGBIT(short, long, &int_var, description, mask)`::
  159 	Introduce a boolean option.
  160 	If used, `int_var` is bitwise-anded with the inverted `mask`.
  161 
  162 `OPT_SET_INT(short, long, &int_var, description, integer)`::
  163 	Introduce an integer option.
  164 	`int_var` is set to `integer` with `--option`, and
  165 	reset to zero with `--no-option`.
  166 
  167 `OPT_STRING(short, long, &str_var, arg_str, description)`::
  168 	Introduce an option with string argument.
  169 	The string argument is put into `str_var`.
  170 
  171 `OPT_STRING_LIST(short, long, &struct string_list, arg_str, description)`::
  172 	Introduce an option with string argument.
  173 	The string argument is stored as an element in `string_list`.
  174 	Use of `--no-option` will clear the list of preceding values.
  175 
  176 `OPT_INTEGER(short, long, &int_var, description)`::
  177 	Introduce an option with integer argument.
  178 	The integer is put into `int_var`.
  179 
  180 `OPT_MAGNITUDE(short, long, &unsigned_long_var, description)`::
  181 	Introduce an option with a size argument. The argument must be a
  182 	non-negative integer and may include a suffix of 'k', 'm' or 'g' to
  183 	scale the provided value by 1024, 1024^2 or 1024^3 respectively.
  184 	The scaled value is put into `unsigned_long_var`.
  185 
  186 `OPT_EXPIRY_DATE(short, long, &timestamp_t_var, description)`::
  187 	Introduce an option with expiry date argument, see `parse_expiry_date()`.
  188 	The timestamp is put into `timestamp_t_var`.
  189 
  190 `OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`::
  191 	Introduce an option with argument.
  192 	The argument will be fed into the function given by `func_ptr`
  193 	and the result will be put into `var`.
  194 	See 'Option Callbacks' below for a more elaborate description.
  195 
  196 `OPT_FILENAME(short, long, &var, description)`::
  197 	Introduce an option with a filename argument.
  198 	The filename will be prefixed by passing the filename along with
  199 	the prefix argument of `parse_options()` to `prefix_filename()`.
  200 
  201 `OPT_ARGUMENT(long, description)`::
  202 	Introduce a long-option argument that will be kept in `argv[]`.
  203 
  204 `OPT_NUMBER_CALLBACK(&var, description, func_ptr)`::
  205 	Recognize numerical options like -123 and feed the integer as
  206 	if it was an argument to the function given by `func_ptr`.
  207 	The result will be put into `var`.  There can be only one such
  208 	option definition.  It cannot be negated and it takes no
  209 	arguments.  Short options that happen to be digits take
  210 	precedence over it.
  211 
  212 `OPT_COLOR_FLAG(short, long, &int_var, description)`::
  213 	Introduce an option that takes an optional argument that can
  214 	have one of three values: "always", "never", or "auto".  If the
  215 	argument is not given, it defaults to "always".  The `--no-` form
  216 	works like `--long=never`; it cannot take an argument.  If
  217 	"always", set `int_var` to 1; if "never", set `int_var` to 0; if
  218 	"auto", set `int_var` to 1 if stdout is a tty or a pager,
  219 	0 otherwise.
  220 
  221 `OPT_NOOP_NOARG(short, long)`::
  222 	Introduce an option that has no effect and takes no arguments.
  223 	Use it to hide deprecated options that are still to be recognized
  224 	and ignored silently.
  225 
  226 `OPT_PASSTHRU(short, long, &char_var, arg_str, description, flags)`::
  227 	Introduce an option that will be reconstructed into a char* string,
  228 	which must be initialized to NULL. This is useful when you need to
  229 	pass the command-line option to another command. Any previous value
  230 	will be overwritten, so this should only be used for options where
  231 	the last one specified on the command line wins.
  232 
  233 `OPT_PASSTHRU_ARGV(short, long, &argv_array_var, arg_str, description, flags)`::
  234 	Introduce an option where all instances of it on the command-line will
  235 	be reconstructed into an argv_array. This is useful when you need to
  236 	pass the command-line option, which can be specified multiple times,
  237 	to another command.
  238 
  239 `OPT_CMDMODE(short, long, &int_var, description, enum_val)`::
  240 	Define an "operation mode" option, only one of which in the same
  241 	group of "operating mode" options that share the same `int_var`
  242 	can be given by the user. `enum_val` is set to `int_var` when the
  243 	option is used, but an error is reported if other "operating mode"
  244 	option has already set its value to the same `int_var`.
  245 
  246 
  247 The last element of the array must be `OPT_END()`.
  248 
  249 If not stated otherwise, interpret the arguments as follows:
  250 
  251 * `short` is a character for the short option
  252   (e.g. `'e'` for `-e`, use `0` to omit),
  253 
  254 * `long` is a string for the long option
  255   (e.g. `"example"` for `--example`, use `NULL` to omit),
  256 
  257 * `int_var` is an integer variable,
  258 
  259 * `str_var` is a string variable (`char *`),
  260 
  261 * `arg_str` is the string that is shown as argument
  262   (e.g. `"branch"` will result in `<branch>`).
  263   If set to `NULL`, three dots (`...`) will be displayed.
  264 
  265 * `description` is a short string to describe the effect of the option.
  266   It shall begin with a lower-case letter and a full stop (`.`) shall be
  267   omitted at the end.
  268 
  269 Option Callbacks
  270 ----------------
  271 
  272 The function must be defined in this form:
  273 
  274 	int func(const struct option *opt, const char *arg, int unset)
  275 
  276 The callback mechanism is as follows:
  277 
  278 * Inside `func`, the only interesting member of the structure
  279   given by `opt` is the void pointer `opt->value`.
  280   `*opt->value` will be the value that is saved into `var`, if you
  281   use `OPT_CALLBACK()`.
  282   For example, do `*(unsigned long *)opt->value = 42;` to get 42
  283   into an `unsigned long` variable.
  284 
  285 * Return value `0` indicates success and non-zero return
  286   value will invoke `usage_with_options()` and, thus, die.
  287 
  288 * If the user negates the option, `arg` is `NULL` and `unset` is 1.
  289 
  290 Sophisticated option parsing
  291 ----------------------------
  292 
  293 If you need, for example, option callbacks with optional arguments
  294 or without arguments at all, or if you need other special cases,
  295 that are not handled by the macros above, you need to specify the
  296 members of the `option` structure manually.
  297 
  298 This is not covered in this document, but well documented
  299 in `parse-options.h` itself.
  300 
  301 Examples
  302 --------
  303 
  304 See `test-parse-options.c` and
  305 `builtin/add.c`,
  306 `builtin/clone.c`,
  307 `builtin/commit.c`,
  308 `builtin/fetch.c`,
  309 `builtin/fsck.c`,
  310 `builtin/rm.c`
  311 for real-world examples.