Repeating argument inside [options]

Hi.

I was trying to simplify some scripts by using [options] but i got into a issue when i had to have repeating arguments.

The following code is the old way where i have to define the repeating arguments in the usage section

from docopt import docopt

__docopt__ = """
usage:
  script foo <bar> [-v ...] [options]

Options:
  <bar>               Key identifier username
  -v                  increase verbosity
"""

args = docopt(__docopt__)
print(args)

that works fine when callde with

$ python repeat_broken.py foo asd -vvv

{'-v': 3,
 '<bar>': 'asd',
 'foo': True}

but when trying to move the repeating part down to the options definition i get the following

from docopt import docopt

__docopt__ = """
usage:
  script foo <bar> [options]

Options:
  <bar>               Key identifier username
  -v ...              increase verbosity
"""

args = docopt(__docopt__)
print(args)

and called with

$ python repeat_broken.py foo asd -vvv

{'-v': 'vv',
 '<bar>': 'asd',
 'foo': True}

In this case it interpretates the ... as something different then when defined in the usage section.

Is it intended that ... should not be possible to use in the options section or is this a bug?

[alexcrichton]

Cargo also recently ran into this problem, our doc string should in theory allow commands of the form:

cargo build --bin foo --bin bar

but unfortunately you can only pass one --bin for now. We could in theory modify the usage string to include [--bin NAME ...], but we’d have to repeat that for --test, --example, etc, and also repeat that across the other subcommands that Cargo has. Overall I agree with @BurntSushi that modifying the options section would be what I’d love to see as well!

[BurntSushi]

I have an experimental implementation of this working and I think it works quite nicely. I basically just took the idea in the OP and ran with it. If ... proceeds a flag name/argument in an option description (separated by exactly one space, just like the argument), then that flag is allowed to be repeated an arbitrary number of times. Namely, this:

Usage: prog [-a ...]

is equivalent to

Usage: prog [options]

Options:
  -a ...

I’ve written down some test cases that should clarify the rest:

r"""Usage: prog [options]

Options:
  -a ...  Foo
"""
$ program
{"-a": 0}
$ program -a
{"-a": 1}
$ program -a -a
{"-a": 2}
$ program -aa
{"-a": 2}
$ program -a -a -a
{"-a": 3}
$ program -aaa
{"-a": 3}

r"""Usage: prog [options]

Options:
  -a, --all ...  Foo
"""
$ program
{"-a": 0}
$ program -a
{"-a": 1}
$ program -a --all
{"-a": 2}
$ program -aa --all
{"-a": 3}
$ program --all
{"-a": 1}
$ program --all --all
{"-a": 2}

r"""Usage: prog [options]

Options:
  -a, --all ARG ...  Foo
"""
$ program
{"-a": []}
$ program -a 1
{"-a": ["1"]}
$ program -a 2 --all 3
{"-a": ["2", "3"]}
$ program -a4 -a5 --all 6
{"-a": ["4", "5", "6"]}
$ program --all 7
{"-a": ["7"]}
$ program --all 8 --all 9
{"-a": ["8", "9"]}

r"""Usage: prog [options]

Options:
  --all ...  Foo
"""
$ program
{"--all": 0}
$ program --all
{"--all": 1}
$ program --all --all
{"--all": 2}

r"""Usage: prog [options]

Options:
  --all=ARG ...  Foo
"""
$ program
{"--all": []}
$ program --all 1
{"--all": ["1"]}
$ program --all 2 --all 3
{"--all": ["2", "3"]}

r"""Usage: prog [options]

Options:
  --all  ...  Foo
"""
$ program --all --all
"user-error"

r"""Usage: prog [options]

Options:
  --all ARG  ...  Foo
"""
$ program --all foo --all bar
"user-error"

Two notes:

1. This prevents flag argument names from beginning with a .. I don’t think I’ve ever seen such a flag argument name in the wild, so I think that’s OK.
2. I’ve left out any ability to emulated bounded repetition, which can still only be expressed in a usage pattern (e.g., -aa). I’m not convinced we want that much flexibility in the option descriptions, and if we did, it could always be added later.