Repeated options (-vvv) don't give a count value

[rdonkin]

I was trying to get repeated -v arguments working to increase level of verbosity (as used by ssh, rsync, ansible, etc).

This seems to be supported by docopt, based on this try.docopt.org test, giving a value of 2 for the v option in output - but the example below doesn't work in docopt/docopts 0.6.3:

#  mywrapper [-h|--help] [options] [-v|-vv|-vvv|-vvvv|-vvvvv]
# 
# Options:
#   -v, --verbose                       Show verbose Ansible output
#   -vv                                 Show verbose Ansible output
#   -vvv                                Show verbose Ansible output
#   -vvvv                               Show verbose Ansible output
#   -vvvvv                              Show verbose Ansible output

Any use of -vv for example gives a usage error.

I am currently having to use options like --v3 as a workaround. Using --v=3 would be OK but not as pleasant for the user as repeating -v to get more verbose.

Any suggestions on how to do this?

[Sylvain303]

Hi @rdonkin

It is standard docopt, not related to docopts

Seems to work for me:

$ ./docopts -h 'usage: prog [-v...]' : -vvv
v=3

Is it what you are looking for?

[Sylvain303]

Also works that way too (tough I would have say it is not normal single letter option definition):

$ ./docopts --version
docopts v0.6.3-rc1 commit 13f0bbc built at 2019-08-05T07:15:08Z
built from: go version go1.11.4 linux/amd64
Copyright (C) 2013 Vladimir Keleshev, Lari Rasku.
Copyleft (Ɔ)  2019 Sylvain Viart (golang version).
License MIT <http://opensource.org/licenses/MIT>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

$ ./docopts -h 'usage: naval_fate.py [-v|-vv|-vvv|-vvvv|-vvvvv]' : -vvv
v=3

could you share a shell script which produces the bug please?

[Sylvain303]

oh, I got it. Sorry I replied a bit faster.

It's the extra Options: section which introduces a bias in the result. Interesting.

$ cat bug_40.sh 
#!/usr/bin/env bash
#
# Usage:  mywrapper [-h|--help] [options] [-v|-vv|-vvv|-vvvv|-vvvvv]
#
# Options:
#   -v, --verbose                       Show verbose Ansible output
#   -vv                                 Show verbose Ansible output
#   -vvv                                Show verbose Ansible output
#   -vvvv                               Show verbose Ansible output
#   -vvvvv                              Show verbose Ansible output

# if docopts is in PATH, not needed.
# Note: docopts.sh is also found in PATH
PATH=../..:$PATH
# auto parse the header above, See: docopt_get_help_string
source docopts.sh --auto -G "$@"

docopt_print_ARGS -G

which gives:

$ ./bug_40.sh 
docopt_print_ARGS -G => ARGS_*
ARGS__vv=false
ARGS__vvv=false
ARGS__vvvv=false
ARGS__vvvvv=false
ARGS_h=false
ARGS_help=false
ARGS_verbose=0

That one is interesting.

$ ./bug_40.sh -vvv
docopt_print_ARGS -G => ARGS_*
ARGS__vv=false
ARGS__vvv=false
ARGS__vvvv=false
ARGS__vvvvv=false
ARGS_h=false
ARGS_help=false
ARGS_verbose=3

Something related to docopt/docopt#386 that brings inconsistency behavior, and is bugged it the main docopt-go too. I really want to fix this ugly one, I need to fix it in the lib.

It will introduce a behavior change, for those using the result. I've done some more tests and the behavior also changes when --option=ARG and --option ARG. So confusing...

Need a great work on that.

[Sylvain303]

So @rdonkin, before fighting for a better world, here is a work around for tomorrow:

$ ./with-option-and-doc.sh -vvv
docopt_print_ARGS -G => ARGS_*
ARGS_h=false
ARGS_help=false
ARGS_verbose=3

or even more verbosely: 😉

$ ./with-option-and-doc.sh --verbose --verbose --verbose --verbose --verbose
docopt_print_ARGS -G => ARGS_*
ARGS_h=false
ARGS_help=false
ARGS_verbose=5

drum roll...
Solution, use the doc part of docopt, the parser will do the rest:

$ ./with-option-and-doc.sh -h
Usage:  mywrapper [-h|--help] [options] [-v|-vv|-vvv|-vvvv|-vvvvv]

Options:
  -v, --verbose                 Show verbose Ansible output up to 4 options
                                level 1 : bla speek a little
                                level 2 : speak loud and clear
                                level 3 : really verbose and boring
                                level 4 : flood, debug glory details

now, that said, I have a question:

If docopts was able to warn you about some wrong usage here, what would you expect as error message or warning? How would you have interacted with docopts to understand what happen here?

It's a real serious question as I'm working on the parser to provide helpful, descriptive error messages.
Could you describe or imagine how the command line tool could have helped you?

This bug details for curious reader:

In this corner case, we are facing a behavior which is confusing. This behavior is not part of docopts but in the docopt-go lib I use, probably also present in python legacy original code.

When you don't use the Options: description the parser only behave by reading Usage:. But when is parses Options: this associate new options definition with the Usage:. In docopt internal it is called defaults. When there is defaults docopt also add them as option not parsed with false value. It also behave differently if option are defined --option=ARG or --option ARG associating the key --option or ARG which is also confusing. For me all this inconsistency reflect a bug.

[rdonkin]

Thanks @Sylvain303 - that worked well.

It would be nice if the syntax could remain confined to the Options section, as it's quite long. Not sure if having a 2nd line in Usage is possible, or defines mutually exclusive sets of options.

Perhaps a good solution would be if docopt.org had an example of repeated options - I had to read a few GitHub issues then try out the interactive web test app before I could even check this was possible.

Not sure about the parser error, it's probably OK if it's fairly technical with enough detail and request to submit a GitHub issue (if this is to flag up issues).

[Sylvain303]

It would be nice if the syntax could remain confined to the Options section, as it's quite long. Not sure if having a 2nd line in Usage is possible, or defines mutually exclusive sets of options.

This part is native docopt syntax:

Usage: describe the valid usage available via the docopt language.
Options: describe the option itself, allowing longname equiv + default value

Of course many line of Usage are possible and define the program's validation CLI provided by the docopt parser, but you may may speak about splitting one definition on multiple lines.

The short version is [-v ...] which wont stop with a parse error at 5 -v you have to do it in the code.
Next you can document it as I suggested. When you add documentation and synonym for long option --verbose the option is outputted by using the long name.

Perhaps a good solution would be if docopt.org had an example of repeated options

There is one: Use ellipsis "..."

Usage:
  my_program command --option <argument>
  my_program [<optional-argument>]
  my_program --another-option=<with-argument>
  my_program (--either-that-option | <or-this-argument>)
  my_program <repeating-argument> <repeating-argument>...

everything in docopt can use this repeatability even groups.

• I had to read a few GitHub issues then try out the interactive web test app before I could even check this was possible.

You may be right, the example could be more useful, the doc is spread on many locations. This point may be improved.

Not sure about the parser error, it's probably OK if it's fairly technical with enough detail and request to submit a GitHub issue (if this is to flag up issues).

I'm not sure to understand this part of the message. In this particular issue, you are hitting some weakness of docopt actual implementation and documentation. Your attempt was almost good.

As I'm trying to improve the feedback of using docopt through docopts implementation, I just wanted if you got a feedback on how we could improve the user experience. You said about the global documentation on doctop.org. I will look if it could be updated.

Thanks for your feedback, you can close the issue, if its resolved for you. I will open a new one the correcting the docopt lib behavior we are facing in that context.