From 9bab5b6061f1bc8ca54f8ac145f4f88c644e3bc4 Mon Sep 17 00:00:00 2001 From: Ilya Bobyr Date: Sat, 22 Mar 2014 02:47:34 -0700 Subject: rev-parse --parseopt: option argument name hints Built-in commands can specify names for option arguments when usage text is generated for a command. sh based commands should be able to do the same. Option argument name hint is any text that comes after [*=?!] after the argument name up to the first whitespace. Signed-off-by: Ilya Bobyr Signed-off-by: Junio C Hamano --- Documentation/git-rev-parse.txt | 34 ++++++++++++++++++++++++++++++++-- builtin/rev-parse.c | 13 ++++++++++++- t/t1502-rev-parse-parseopt.sh | 20 ++++++++++++++++++++ 3 files changed, 64 insertions(+), 3 deletions(-) diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 0d2cdcde5..e05e6b359 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -284,13 +284,13 @@ Input Format 'git rev-parse --parseopt' input format is fully text based. It has two parts, separated by a line that contains only `--`. The lines before the separator -(should be more than one) are used for the usage. +(should be one or more) are used for the usage. The lines after the separator describe the options. Each line of options has this format: ------------ -* SP+ help LF +*? SP+ help LF ------------ ``:: @@ -313,6 +313,12 @@ Each line of options has this format: * Use `!` to not make the corresponding negated long option available. +``:: + ``, if specified, is used as a name of the argument in the + help output, for options that take arguments. `` is + terminated by the first whitespace. When you need to use space in the + argument hint use dash instead. + The remainder of the line, after stripping the spaces, is used as the help associated to the option. @@ -333,6 +339,8 @@ h,help show the help foo some nifty option --foo bar= some cool option --bar with an argument +baz=arg another cool option --baz with a named argument +qux?path qux may take a path argument but has meaning by itself An option group Header C? option C with an optional argument" @@ -340,6 +348,28 @@ C? option C with an optional argument" eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)" ------------ + +Usage text +~~~~~~~~~~ + +When `"$@"` is `-h` or `--help` in the above example, the following +usage text would be shown: + +------------ +usage: some-command [options] ... + + some-command does foo and bar! + + -h, --help show the help + --foo some nifty option --foo + --bar ... some cool option --bar with an argument + --bar another cool option --baz with a named argument + --qux[=] qux may take a path argument but has meaning by itself + +An option group Header + -C[...] option C with an optional argument +------------ + SQ-QUOTE -------- diff --git a/builtin/rev-parse.c b/builtin/rev-parse.c index 45901df37..1a6122d3a 100644 --- a/builtin/rev-parse.c +++ b/builtin/rev-parse.c @@ -395,9 +395,10 @@ static int cmd_parseopt(int argc, const char **argv, const char *prefix) usage[unb++] = strbuf_detach(&sb, NULL); } - /* parse: (|,|)[=?]? SP+ */ + /* parse: (|,|)[*=?!]*? SP+ */ while (strbuf_getline(&sb, stdin, '\n') != EOF) { const char *s; + const char *end; struct option *o; if (!sb.len) @@ -419,6 +420,16 @@ static int cmd_parseopt(int argc, const char **argv, const char *prefix) o->value = &parsed; o->flags = PARSE_OPT_NOARG; o->callback = &parseopt_dump; + + /* Possible argument name hint */ + end = s; + while (s > sb.buf && strchr("*=?!", s[-1]) == NULL) + --s; + if (s != sb.buf && s != end) + o->argh = xmemdupz(s, end - s); + if (s == sb.buf) + s = end; + while (s > sb.buf && strchr("*=?!", s[-1])) { switch (*--s) { case '=': diff --git a/t/t1502-rev-parse-parseopt.sh b/t/t1502-rev-parse-parseopt.sh index 83b1300ce..960adf56a 100755 --- a/t/t1502-rev-parse-parseopt.sh +++ b/t/t1502-rev-parse-parseopt.sh @@ -18,6 +18,17 @@ An option group Header -C[...] option C with an optional argument -d, --data[=...] short and long option with an optional argument +Argument hints + -b short option required argument + --bar2 long option required argument + -e, --fuz + short and long option required argument + -s[] short option optional argument + --long[=] long option optional argument + -g, --fluf[=] short and long option optional argument + --longest + a very long argument hint + Extras --extra1 line above used to cause a segfault but no longer does @@ -39,6 +50,15 @@ b,baz a short and long option C? option C with an optional argument d,data? short and long option with an optional argument + Argument hints +b=arg short option required argument +bar2=arg long option required argument +e,fuz=with-space short and long option required argument +s?some short option optional argument +long?data long option optional argument +g,fluf?path short and long option optional argument +longest=very-long-argument-hint a very long argument hint + Extras extra1 line above used to cause a segfault but no longer does EOF -- cgit v1.2.1 From ce7f8745aa773dfe2fc0a1b8c327b50c7ce4a31e Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sun, 23 Mar 2014 15:26:36 -0700 Subject: t1502: protect runs of SPs used in the indentation The expected output from the argument help use runs of SPs to align the description of each option; a careless use of --whitespace=fix can turn leading parts of them into appropriate number of HTs. Prevent such a breakage by prefixing all the expected lines with leading vertical bars in the original and stripping them with a small sed script. Signed-off-by: Junio C Hamano --- t/t1502-rev-parse-parseopt.sh | 112 +++++++++++++++++++++--------------------- 1 file changed, 56 insertions(+), 56 deletions(-) diff --git a/t/t1502-rev-parse-parseopt.sh b/t/t1502-rev-parse-parseopt.sh index 960adf56a..922423e7d 100755 --- a/t/t1502-rev-parse-parseopt.sh +++ b/t/t1502-rev-parse-parseopt.sh @@ -3,64 +3,64 @@ test_description='test git rev-parse --parseopt' . ./test-lib.sh -cat > expect <<\END_EXPECT -cat <<\EOF -usage: some-command [options] ... - - some-command does foo and bar! - - -h, --help show the help - --foo some nifty option --foo - --bar ... some cool option --bar with an argument - -b, --baz a short and long option - -An option group Header - -C[...] option C with an optional argument - -d, --data[=...] short and long option with an optional argument - -Argument hints - -b short option required argument - --bar2 long option required argument - -e, --fuz - short and long option required argument - -s[] short option optional argument - --long[=] long option optional argument - -g, --fluf[=] short and long option optional argument - --longest - a very long argument hint - -Extras - --extra1 line above used to cause a segfault but no longer does - -EOF +sed -e 's/^|//' >expect <<\END_EXPECT +|cat <<\EOF +|usage: some-command [options] ... +| +| some-command does foo and bar! +| +| -h, --help show the help +| --foo some nifty option --foo +| --bar ... some cool option --bar with an argument +| -b, --baz a short and long option +| +|An option group Header +| -C[...] option C with an optional argument +| -d, --data[=...] short and long option with an optional argument +| +|Argument hints +| -b short option required argument +| --bar2 long option required argument +| -e, --fuz +| short and long option required argument +| -s[] short option optional argument +| --long[=] long option optional argument +| -g, --fluf[=] short and long option optional argument +| --longest +| a very long argument hint +| +|Extras +| --extra1 line above used to cause a segfault but no longer does +| +|EOF END_EXPECT -cat > optionspec << EOF -some-command [options] ... - -some-command does foo and bar! --- -h,help show the help - -foo some nifty option --foo -bar= some cool option --bar with an argument -b,baz a short and long option - - An option group Header -C? option C with an optional argument -d,data? short and long option with an optional argument - - Argument hints -b=arg short option required argument -bar2=arg long option required argument -e,fuz=with-space short and long option required argument -s?some short option optional argument -long?data long option optional argument -g,fluf?path short and long option optional argument -longest=very-long-argument-hint a very long argument hint - -Extras -extra1 line above used to cause a segfault but no longer does +sed -e 's/^|//' >optionspec <<\EOF +|some-command [options] ... +| +|some-command does foo and bar! +|-- +|h,help show the help +| +|foo some nifty option --foo +|bar= some cool option --bar with an argument +|b,baz a short and long option +| +| An option group Header +|C? option C with an optional argument +|d,data? short and long option with an optional argument +| +| Argument hints +|b=arg short option required argument +|bar2=arg long option required argument +|e,fuz=with-space short and long option required argument +|s?some short option optional argument +|long?data long option optional argument +|g,fluf?path short and long option optional argument +|longest=very-long-argument-hint a very long argument hint +| +|Extras +|extra1 line above used to cause a segfault but no longer does EOF test_expect_success 'test --parseopt help output' ' -- cgit v1.2.1