From 82936f295f803a8f1fbe2d89856e9371baa3536c Mon Sep 17 00:00:00 2001 From: Stephan Beyer Date: Sun, 22 Jun 2008 01:54:36 +0200 Subject: api-builtin.txt: update and fix typo Mention NEED_WORK_TREE flag and command-list.txt. Fix "bulit-in" typo and AsciiDoc-formatting of a paragraph. Signed-off-by: Stephan Beyer Signed-off-by: Junio C Hamano --- Documentation/technical/api-builtin.txt | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt index 52cdb4c520..7ede1e64e5 100644 --- a/Documentation/technical/api-builtin.txt +++ b/Documentation/technical/api-builtin.txt @@ -4,7 +4,7 @@ builtin API Adding a new built-in --------------------- -There are 4 things to do to add a bulit-in command implementation to +There are 4 things to do to add a built-in command implementation to git: . Define the implementation of the built-in command `foo` with @@ -18,8 +18,8 @@ git: defined in `git.c`. The entry should look like: { "foo", cmd_foo, }, - - where options is the bitwise-or of: ++ +where options is the bitwise-or of: `RUN_SETUP`:: @@ -33,6 +33,12 @@ git: If the standard output is connected to a tty, spawn a pager and feed our output to it. +`NEED_WORK_TREE`:: + + Make sure there is a work tree, i.e. the command cannot act + on bare repositories. + This makes only sense when `RUN_SETUP` is also set. + . Add `builtin-foo.o` to `BUILTIN_OBJS` in `Makefile`. Additionally, if `foo` is a new command, there are 3 more things to do: @@ -41,8 +47,7 @@ Additionally, if `foo` is a new command, there are 3 more things to do: . Write documentation in `Documentation/git-foo.txt`. -. Add an entry for `git-foo` to the list at the end of - `Documentation/cmd-list.perl`. +. Add an entry for `git-foo` to `command-list.txt`. How a built-in is called -- cgit v1.2.3 From 6422f633216475939f9a6f317e41a164737cbb02 Mon Sep 17 00:00:00 2001 From: Michele Ballabio Date: Sun, 22 Jun 2008 16:39:04 +0200 Subject: parse-options.c: fix documentation syntax of optional arguments When an argument for an option is optional, short options don't need a space between the option and the argument, and long options need a "=". Otherwise, arguments are misinterpreted. Signed-off-by: Michele Ballabio Signed-off-by: Junio C Hamano --- parse-options.c | 15 ++++++++++++--- t/t1502-rev-parse-parseopt.sh | 2 +- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/parse-options.c b/parse-options.c index acf3fe3a1a..f8d52e21fe 100644 --- a/parse-options.c +++ b/parse-options.c @@ -344,7 +344,10 @@ void usage_with_options_internal(const char * const *usagestr, break; case OPTION_INTEGER: if (opts->flags & PARSE_OPT_OPTARG) - pos += fprintf(stderr, "[]"); + if (opts->long_name) + pos += fprintf(stderr, "[=]"); + else + pos += fprintf(stderr, "[]"); else pos += fprintf(stderr, " "); break; @@ -355,12 +358,18 @@ void usage_with_options_internal(const char * const *usagestr, case OPTION_STRING: if (opts->argh) { if (opts->flags & PARSE_OPT_OPTARG) - pos += fprintf(stderr, " [<%s>]", opts->argh); + if (opts->long_name) + pos += fprintf(stderr, "[=<%s>]", opts->argh); + else + pos += fprintf(stderr, "[<%s>]", opts->argh); else pos += fprintf(stderr, " <%s>", opts->argh); } else { if (opts->flags & PARSE_OPT_OPTARG) - pos += fprintf(stderr, " [...]"); + if (opts->long_name) + pos += fprintf(stderr, "[=...]"); + else + pos += fprintf(stderr, "[...]"); else pos += fprintf(stderr, " ..."); } diff --git a/t/t1502-rev-parse-parseopt.sh b/t/t1502-rev-parse-parseopt.sh index d24a47d114..3508d0a612 100755 --- a/t/t1502-rev-parse-parseopt.sh +++ b/t/t1502-rev-parse-parseopt.sh @@ -13,7 +13,7 @@ usage: some-command [options] ... --bar ... some cool option --bar with an argument An option group Header - -C [...] option C with an optional argument + -C[...] option C with an optional argument Extras --extra1 line above used to cause a segfault but no longer does -- cgit v1.2.3 From 224712e521c6d4f740045affa4d1ee1454db10d4 Mon Sep 17 00:00:00 2001 From: Stephan Beyer Date: Sun, 22 Jun 2008 17:04:25 +0200 Subject: api-parse-options.txt: Introduce documentation for parse options API Add some documentation of basics, macros and callback implementation of the parse-options API. Signed-off-by: Stephan Beyer Signed-off-by: Junio C Hamano --- Documentation/technical/api-parse-options.txt | 204 +++++++++++++++++++++++++- 1 file changed, 202 insertions(+), 2 deletions(-) diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index b7cda94f54..539863b1f9 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -1,6 +1,206 @@ parse-options API ================= -Talk about +The parse-options API is used to parse and massage options in git +and to provide a usage help with consistent look. -(Pierre) +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[=]`. + +`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)`:: + 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_BOOLEAN(short, long, &int_var, description)`:: + Introduce a boolean option. + `int_var` is incremented on each use. + +`OPT_BIT(short, long, &int_var, description, mask)`:: + Introduce a boolean option. + If used, `int_var` is bitwise-ored with `mask`. + +`OPT_SET_INT(short, long, &int_var, description, integer)`:: + Introduce a boolean option. + If used, set `int_var` to `integer`. + +`OPT_SET_PTR(short, long, &ptr_var, description, ptr)`:: + Introduce a boolean option. + If used, set `ptr_var` to `ptr`. + +`OPT_STRING(short, long, &str_var, arg_str, description)`:: + Introduce an option with string argument. + The string argument is put into `str_var`. + +`OPT_INTEGER(short, long, &int_var, description)`:: + Introduce an option with integer argument. + The integer is put into `int_var`. + +`OPT_DATE(short, long, &int_var, description)`:: + Introduce an option with date argument, see `approxidate()`. + The timestamp is put into `int_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_ARGUMENT(long, description)`:: + Introduce a long-option argument that will be kept in `argv[]`. + + +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 ``). + 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 `funct`, 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. -- cgit v1.2.3 From 010a2dacc1acf3305e399ef1eb2e620110b95d5e Mon Sep 17 00:00:00 2001 From: Stephan Beyer Date: Sun, 22 Jun 2008 17:04:26 +0200 Subject: Extend parse-options test suite This patch serves two purposes: 1. test-parse-option.c should be a more complete example for the parse-options API, and 2. there have been no tests for OPT_CALLBACK, OPT_DATE, OPT_BIT, OPT_SET_INT and OPT_SET_PTR before. Signed-off-by: Stephan Beyer Signed-off-by: Junio C Hamano --- t/t0040-parse-options.sh | 116 ++++++++++++++++++++++++++++++++++++++++++++--- test-parse-options.c | 39 ++++++++++++++-- 2 files changed, 144 insertions(+), 11 deletions(-) diff --git a/t/t0040-parse-options.sh b/t/t0040-parse-options.sh index 9965cfa1dc..6309aed451 100755 --- a/t/t0040-parse-options.sh +++ b/t/t0040-parse-options.sh @@ -11,23 +11,35 @@ cat > expect.err << EOF usage: test-parse-options -b, --boolean get a boolean + -4, --or4 bitwise-or boolean with ...0100 + -i, --integer get a integer -j get a integer, too + --set23 set integer to 23 + -t