Support for counted short flags, a-la ssh -vvv? about docopt HOT 22 CLOSED

For me -v3 is good enough (also shorter). But if someone comes up how to express that "flag should be counted" in the DSL—there might be a place for it.

from docopt.

Rather than requiring a mention in the DSL, maybe it could always count all argument-less short options? The count could be returned in place of True / False, which would still maintain compatibility with if args['-v']: checks.

from docopt.

@Met48 that's an option. However, that (a) might hit readability of the returned dict (b) maybe it's a bad convention and docopt should not promote it.

We could do -single-letter-long-options and tar-like optional - (tar xzf file vs tar -xzf file)—those I think are just bad ideas. Still not sure about -vvv.

from docopt.

This is a fairly common practice with commandline tools which allow varying degrees of verbosity. In addition to ssh, it's used in rsync, rpm. It's also been used in some versions of ps to indicate additional information should be provided (-w). It's used in the python interpreter itself (for -v, -O, and -d). It would be a valuable feature to have.

That said it would be fairly difficult to find a way to express this in the DSL, so it would probably be best to make all argument-less options (short and long) count instead of just using True/False. 0 is already falsey and >1 is already truthy, so unless people are checking whether the values in the dictionary are the True or False objects, it should have no impact on them, and while it's recommended to do that for None, I don't believe it's a best practice for True/False comparison.

from docopt.

I have the start of a patch for this, but it's got some issues so I'm not submitting it yet.

from docopt.

Got it. I'm going to submit a pull request shortly. Something to note, this broke none of the language agnostic tester. I also added a test explicitly for this.

from docopt.

I've submitted #32.

from docopt.

I think #32 was a good proposal, but @sonwell came up with better, more powerful API (we discussed it over skype):

• By default (as usual) flag options return True/False.
• Flag options can be "marked" as "repeating elements" (same way as <arguments> can be now): -v ... or -v -v or -vvv
• Those that are specified in that way—are counted and return number of occurrences.
• Invalid number of repetitions are rejected by docopt—same way as invalid number of repetitions of <arguments> are rejected in current implementation.

Example (language-agnostic) test-case:

r"""Usage: prog -v

"""
$ prog -v
{"-v": true}

r"""Usage: prog [-v -v]

"""
$ prog 
{"-v": 0}

$ prog -v
{"-v": 1}

$ prog -vv
{"-v": 2}

r"""Usage: prog -v ...

"""
$ prog 
"user-error"

$ prog -v
{"-v": 1}

$ prog -vv
{"-v": 2}

$ prog -vvvvvv
{"-v": 6}

r"""Usage: prog [-v | -vv | -vvv]

This one is probably most readable user-friednly variant.

"""
$ prog 
{"-v": 0}

$ prog -v
{"-v": 1}

$ prog -vv
{"-v": 2}

$ prog -vvvv
"user-error"

from docopt.

The above, I think, is a very good DSL extensions that covers some parts of DSL that are obscure now ("what if ... is applied to an option instead of an argument?").

From implementation point I suspect that Option.match should be made less greedy, and, maybe options should be collected into collected array during matching the same way as arguments are now.

This might allow some refactoring that will lead to simplification of:

        return Dict((a.name, a.value) for a in
                    (pot_options + options + pot_arguments + arguments))

Into something like:

        return Dict((a.name, a.value) for a in
                    (pot_options + pot_arguments + collected))

Or maybe even:

        return Dict((a.name, a.value) for a in collected)

Anyway, this issue is now marked as TODO.

from docopt.

Is there an ETA for this?

from docopt.

@mkomitee no, this will be TODO until someone has time to implement this or until someone does a pull request.

You were the author of #32 pull request—why not give implementing this a try?

from docopt.

So there should be two types of countable flag options in addition to the regular True/False type that is currently supported, one that is explicitly bounded and one that is not?

For the bounded ones, I like this one:

Usage: prog [-v | -vv | -vvv]

It feels like it has a bit of protection against people using it to go up much higher than 3 levels: surely by the time someone has written up to | -vvvvvv they'd quickly realise it'd be far less hideous to just set their options up to be -v 6.

I'm not sure I like this one though:

Usage: prog [-v -v]

Would it be necessary to define the option as prog [-v -v -v] in order to support -vvv, and [-v -v -v -v -v] to support -vvvvv (not that you'd really ever do that)? If that's the case, I don't really like that one - I think the example I mentioned earlier is much more explicit and clear.

Also, I'd like to propose a different way to do the unbounded syntax:

Usage: prog -v ...

It feels like it lacks detail for it to be fully obvious to a user of a docopt-based tool how it works. I've been thinking something like this might fill in some of the blanks:

Usage: prog -v[v...]

It implies that it's optional with [], and that the v is repeatable with ....

from docopt.

@shabbyrobe Sorry for late reply:

Internally [-v | -vv | -vvv] and [-v -v -v] mean the same, and are parsed into equivalent patterns, so it is up to the user to decide which one to use. By not mentioning the second (ugly) variant in the docs we can push user into the right direction of using [-v | -vv | -vvv].

prog -v[v...] looks good to me as a human, but it's too ambiguous to parse, taking into account that spaces are optional around "operators" such as [ ].

So the above language-agnostic test-cases captures the best API I can think of.

from docopt.

By not mentioning the second (ugly) variant in the docs we can push user into the right direction of using [-v | -vv | -vvv].

Perfect.

prog -v[v...] looks good to me as a human, but it's too ambiguous to parse, taking into account that spaces are optional around "operators" such as [ ].

Do you mean that more whitespace would always be accepted? If so, prog -v [ v ... ] wouldn't be so bad, would it? Or have I misunderstood?

from docopt.

Do you mean that more whitespace would always be accepted? If so, prog -v [ v ... ] wouldn't be so bad, would it? Or have I misunderstood?

I mean that both -v[v...] and -v [ v ... ] have already a meaning of option [ command ... ] and there is no way to distinguish it from the proposed -v[v...] syntax for -v.... That's why I think -v[v...] is a bad idea.

from docopt.

I follow you now. That makes sense.

So for the unbounded syntax, are you still considering prog -v ...?

from docopt.

Yes I'm considering prog -v .... I don't think that it has any use, but it makes a lot of sense to me:

Right now repeating or applying ... affects only arguments. I was always thinking about: what can it mean for options?! And the idea of counting flag-options if they are {repeated or have ... applied} just feels natural to me since the time it was proposed by @sonwell.

From implementation point it also makes sense—options will behave more similar to arguments.

Also it's probably a good idea to assign a meaning to "repeating" options with arguments. They probably should behave same way as "repeating" arguments—i.e. be collected into a list.

from docopt.

That does make sense. Will prog -v... work too? i.e. with no whitespace?

from docopt.

Sure, prog -v... will work. Right now spaces are artificially added around characters []()| and .... That is, prog [cmd](<arg>|-o) works now.

Although it looks like this is not very well formulated in documentation...

We will use the word "word" to describe a sequence of characters delimited by either whitespace, one of "|" characters, or "...".

from docopt.

OK, cool, I'm sold now. I know it's a very minor difference, but for some reason I have a strong human preference for -v... with no whitespace. With that supported, I'm 100% satisfied :D

from docopt.

This is now implemented (according to the tests above) in experimental branch. Multiple commands are counted the same way. Multiple options with argument are collected into list like multiple arguments were previously.

After more testing this will get into master branch and then released as 0.5.0 to PyPI during the upcoming week.

Any feedback is appreciated.

from docopt.

TA-DA. 0.5.0 is out with support for this.

from docopt.