{"thread":{"id":"14078","subject":"[PATCH 2/2] Extend parse-options test suite","startedAt":"2008-06-22T00:00:01Z","lastAt":"2008-06-22T15:04:26Z","messageCount":7,"participants":["Stephan Beyer","Michele Ballabio"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"80583","messageId":"1214092802-8175-1-git-send-email-s-beyer@gmx.net","threadId":"14078","inReplyTo":null,"subject":"[PATCH 1/2] api-parse-options.txt: Introduce documentation for parse options API","fromName":"Stephan Beyer","fromEmail":"s-beyer@gmx.net","sentAt":"2008-06-22T00:00:01Z","receivedAt":"2008-06-22T00:00:01Z","isPatch":true,"sender":{"key":"s-beyer@gmx.net","avatar":"https://avatars.githubusercontent.com/u/143889?v=4"},"body":"Add some documentation of basics, macros and callback\nimplementation of the parse-options API.\n\nSigned-off-by: Stephan Beyer \n---\n Documentation/technical/api-parse-options.txt | 206 ++++++++++++++++++++++++-\n 1 files changed, 204 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt\nindex b7cda94..a916db4 100644\n--- a/Documentation/technical/api-parse-options.txt\n+++ b/Documentation/technical/api-parse-options.txt\n@@ -1,6 +1,208 @@\n parse-options API\n =================\n \n-Talk about \n+The parse-options API is used to parse and massage options in git\n+and to provide a usage help with consistent look.\n \n-(Pierre)\n+Basics\n+------\n+\n+The argument vector `argv[]` may usually contain mandatory or optional\n+'non-option arguments', e.g. a filename or a branch, and 'options'.\n+Options are optional arguments that start with a dash and\n+that allow to change the behavior of a command.\n+\n+* There are basically three types of options:\n+ 'boolean' options,\n+ options with (mandatory) 'arguments' and\n+ options with 'optional arguments'\n+ (i.e. a boolean option that can be adjusted).\n+\n+* There are basically two forms of options: \n+ 'Short options' consist of one dash (`-`) and one alphanumeric\n+ character.\n+ 'Long options' begin with two dashes (`\\--`) and some \n+ alphanumeric characters.\n+\n+* Options are case-sensitive.\n+ Please define 'lower-case long options' only.\n+\n+The parse-options API allows:\n+\n+* 'sticked' and 'separate form' of options with arguments.\n+ `-oArg` is sticked, `-o Arg` is separate form.\n+ `\\--option=Arg` is sticked, `\\--option Arg` is separate form.\n+\n+* Long options may be 'abbreviated', as long as the abbreviation\n+ is unambiguous.\n+\n+* Short options may be bundled, e.g. `-a -b` can be specified as `-ab`.\n+\n+* Boolean long options can be 'negated' (or 'unset') by prepending\n+ `no-`, e.g. `\\--no-abbrev` instead of `\\--abbrev`.\n+\n+* Options and other arguments can clearly be separated using the `\\--`\n+ option, e.g. `-a -b \\--option \\-- \\--this-is-a-file` indicates that\n+ `\\--this-is-a-file` must not be processed as an option.\n+\n+Steps to parse options\n+----------------------\n+\n+. `#include \"parse-options.h\"`\n+\n+. define a NULL-terminated\n+ `static const char * const builtin_foo_usage[]` array\n+ containing alternative usage strings\n+\n+. define `builtin_foo_options` array as described below\n+ in section 'Data Structure'.\n+\n+. in `cmd_foo(int argc, const char **argv, const char *prefix)`\n+ call\n+\n+\targc = parse_options(argc, argv, builtin_foo_options, builtin_foo_usage, flags);\n++\n+`parse_options()` will filter out the processed options of `argv[]` and leave the\n+non-option arguments in `argv[]`.\n+`argc` is updated appropriately because of the assignment.\n++\n+Flags are the bitwise-or of:\n+\n+`PARSE_OPT_KEEP_DASHDASH`::\n+\tUsually long options (`\\--long-opt`) are boiled down to their\n+\tshort option equivalent, if available.\n+\tUsing this flag, long options are kept.\n+\n+`PARSE_OPT_STOP_AT_NON_OPTION`::\n+\tUsually all options the whole argument vector is massaged\n+\tand reordered.\n+\tUsing this flag, processing is stopped at the first non-option\n+\targument.\n+\n+Data Structure\n+--------------\n+\n+The main data structure is an array of the `option` struct,\n+say `static struct option builtin_add_options[]`.\n+There are some macros to easily define options:\n+\n+`OPT__ABBREV(&int_var)`::\n+\tAdd `\\--abbrev []`.\n+\n+`OPT__DRY_RUN(&int_var)`::\n+\tAdd `-n, \\--dry-run`.\n+\n+`OPT__QUIET(&int_var)`::\n+\tAdd `-q, \\--quiet`.\n+\n+`OPT__VERBOSE(&int_var)`::\n+\tAdd `-v, \\--verbose`.\n+\n+`OPT_GROUP(description)`::\n+\tStart an option group. `description` is a short string that\n+\tdescribes the group or an empty string.\n+\tStart the description with an upper-case letter.\n+\n+`OPT_BOOLEAN(short, long, &int_var, description)`::\n+\tIntroduce a boolean option.\n+\t`int_var` is incremented on each use.\n+\n+`OPT_BIT(short, long, &int_var, description, mask)`::\n+\tIntroduce a boolean option.\n+\tIf used, `int_var` is bitwise-ored with `mask`.\n+\n+`OPT_SET_INT(short, long, &int_var, description, integer)`::\n+\tIntroduce a boolean option.\n+\tIf used, set `int_var` to `integer`.\n+\n+`OPT_SET_PTR(short, long, &ptr_var, description, ptr)`::\n+\tIntroduce a boolean option.\n+\tIf used, set `ptr_var` to `ptr`.\n+\n+`OPT_STRING(short, long, &str_var, arg_str, description)`::\n+\tIntroduce an option with string argument.\n+\tThe string argument is put into `str_var`.\n+\n+`OPT_INTEGER(short, long, &int_var, description)`::\n+\tIntroduce an option with integer argument.\n+\tThe integer is put into `int_var`.\n+\n+`OPT_DATE(short, long, &int_var, description)`::\n+\tIntroduce an option with date argument, see `approxidate()`.\n+\tThe timestamp is put into `int_var`.\n+\n+`OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`::\n+\tIntroduce an option with argument.\n+\tThe argument will be fed into the function given by `func_ptr`\n+\tand the result will be put into `var`.\n+\tSee 'Option Callbacks' below for a more elaborate description.\n+\n+`OPT_ARGUMENT(long, description)`::\n+\tIntroduce a long-option argument that will be kept in `argv[]`.\n+\n+\n+The last element of the array must be `OPT_END()`.\n+\n+If not stated otherwise, interpret the arguments as follows:\n+\n+* `short` is a character for the short option\n+ (e.g. `\\'e\\'` for `-e`, use `0` to omit),\n+\n+* `long` is a string for the long option\n+ (e.g. `\"example\"` for `\\--example`, use `NULL` to omit),\n+\n+* `int_var` is an integer variable,\n+\n+* `str_var` is a string variable (`char *`),\n+\n+* `arg_str` is the string that is shown as argument\n+ (e.g. `\"branch\"` will result in ``).\n+ If set to `NULL`, three dots (`...`) will be displayed.\n+\n+* `description` is a short string to describe the effect of the option.\n+ It shall begin with a lower-case letter and a full stop (`.`) shall be\n+ omitted at the end.\n+\n+Option Callbacks\n+----------------\n+\n+The function must be defined in this form:\n+\n+\tint func(const struct option *opt, const char *arg, int unset)\n+\n+The callback mechanism is as follows:\n+\n+* Inside `funct`, the only interesting member of the structure\n+ given by `opt` is the void pointer `opt->value`.\n+ `\\*opt->value` will be the value that is saved into `var`, if you\n+ use `OPT_CALLBACK()`.\n+ For example, do `*(unsigned long *)opt->value = 42;` to get 42\n+ into an `unsigned long` variable.\n+\n+* Return value `0` indicates success and non-zero return\n+ value will invoke `usage_with_options()` and, thus, die.\n+\n+* If the user negates the option, `arg` is `NULL` and `unset` is 1.\n+\n+Sophisticated option parsing\n+----------------------------\n+\n+If you need, for example, option callbacks with optional arguments\n+or without arguments at all, or if you need other special cases,\n+that are not handled by the macros above, you need to specify the\n+members of the `option` structure manually.\n+\n+This is not covered in this document, but well documented\n+in `parse-options.h` itself.\n+\n+Examples\n+--------\n+\n+See `test-parse-options.c` and\n+`builtin-add.c`,\n+`builtin-clone.c`,\n+`builtin-commit.c`,\n+`builtin-fetch.c`,\n+`builtin-fsck.c`,\n+`builtin-rm.c`\n+for real-world examples.\n-- \n1.5.6.310.g344d\n"},{"id":"80582","messageId":"1214092802-8175-2-git-send-email-s-beyer@gmx.net","threadId":"14078","inReplyTo":"1214092802-8175-1-git-send-email-s-beyer@gmx.net","subject":"[PATCH 2/2] Extend parse-options test suite","fromName":"Stephan Beyer","fromEmail":"s-beyer@gmx.net","sentAt":"2008-06-22T00:00:02Z","receivedAt":"2008-06-22T00:00:02Z","isPatch":true,"sender":{"key":"s-beyer@gmx.net","avatar":"https://avatars.githubusercontent.com/u/143889?v=4"},"body":"This patch serves two purposes:\n 1. test-parse-option.c should be a more complete\n example for the parse-options API, and\n 2. there have been no tests for OPT_CALLBACK,\n OPT_DATE, OPT_BIT, OPT_SET_INT and OPT_SET_PTR\n before.\n\nSigned-off-by: Stephan Beyer \n---\nOn reviewing you should perhaps first have a look at the .c file,\nthen the changes of t0040 make more sense.\n\n t/t0040-parse-options.sh | 116 +++++++++++++++++++++++++++++++++++++++++++---\n test-parse-options.c | 39 ++++++++++++++--\n 2 files changed, 144 insertions(+), 11 deletions(-)\n\ndiff --git a/t/t0040-parse-options.sh b/t/t0040-parse-options.sh\nindex 9965cfa..87c6164 100755\n--- a/t/t0040-parse-options.sh\n+++ b/t/t0040-parse-options.sh\n@@ -11,23 +11,35 @@ cat > expect.err << EOF\n usage: test-parse-options \n \n -b, --boolean get a boolean\n+ -4, --or4 bitwise-or boolean with ...0100\n+\n -i, --integer get a integer\n -j get a integer, too\n+ --set23 set integer to 23\n+ -t