Complex option arguments about docopt

[keleshev]

Let me be devil's advocate and say that there are other ways to achieve that.

I case of git, this usage would work out of the box when NFA is implemented (see discussion #46), which will happen sooner or later.

usage: git log [<options>] [<since>..<until>] [[--] <path>...]

Although, you would need to put spaces around .. like git log 10.days.ago .. 1.day.ago

If you would want to avoid spaces around .. you can do <since..until> then.

About --date-filter 10.days.ago 1.day.ago: that would probably be more readable as --since=10.days.ago --until=1.day.ago, isn't it?

In case of a list of probabilities --background 0.25 0.25 0.25 0.25, it could be implemented as --background=0.25,0.25,0.25,0.25 or using shell-arrays notation --background=0.25:0.25:0.25:0.25

The reason I'm so defensive is not because this is hard to implement—I think it is very easy to implement, just applying existing positional arguments' rules to options' arguments—but because it opens a can possibilities to be ambiguous: when I read --background=0.25:0.25:0.25:0.25 I can immediately see what's happening there, however in case of --background 0.25 0.25 0.25 0.25 I don't really know if numbers relate to each other, or if they relate to --background.

I have a rule-of-thumb: if I want to add some CLI-feature to one of my programs, and I can't implement it with docopt—that means that there is something wrong with the CLI I'm building, it will be too complex for the user. "CLI smell" if you like :-)

[keleshev]

This is possible. Full-pattern matching could theoretically be applied for options' arguments. Things like:

Usage: prog --option=[<a> | <b> <c>...]

But I'm very scared to use programs that would require that. This is very ambiguous both for humans and parsers.

Right now you can accumulate option's argument into a list:

assert docopt('usage: prog --opt=<arg>...', '--opt=a --opt=b --opt c') == \
        {'--opt': ['a', 'b', 'c']}

If I can see real cases were having pattern-matching inside option's argument makes a better CLI interface—I will go for it.

[VorontsovIE]

Really my example is from real life. For example, e.g. --background A C G T - is an option for 4-elements array of probabilities of nucleotides in genome. Usually my program uses uniform background 0.25 0.25 0.25 0.25
I don't want to set this values as required, because 90% times it can be omitted, but sometimes I want to set probabilities. But one number separately means nothing, only 4 numbers all together can be useful

Also one can imagine such use-case:
git log [<since>..<until>]
If someone makes such filtering optional, then it'd be difficult to state this with docopt:
mygit log --date-filter 10.days.ago 1.day.ago --branch-filter master

[VorontsovIE]

Thank you for your advice! I think it'd be the best in my case.
Can docopt automatically parse 0.25:0.25:0.25:0.25 as array or it yields a string?

[keleshev]

docopt will yield a string "0.25:0.25:0.25:0.25", but you can use something like schema for validating and adapting data returned by docopt.

Maybe something like:

>>> from docopt import docopt
>>> args = docopt('usage: prog --bg=<x:x:x:x>', '-b 0:1:2:3')
>>> args
{'--bg': '0:1:2:3'}
>>> from schema import Schema, And, Use
>>> schema = Schema({'--bg': And(Use(lambda s: map(float, s.split(':'))), lambda l: len(l) == 4)})
>>> schema.validate(args)
{'--bg': [0.0, 1.0, 2.0, 3.0]}

[dodecatheon]

Hi,

I know this is closed, but I'd like a little more flexible form for enumerations, and maybe this can be handled via schema.

Let's say I enter

prog --bg 1,2,3,4 --bg 5,6,7

How do I use schema to get to

args = {'--bg': ['1', '2', '3', '4', '5', '6', '7']}

[keleshev]

@dodecatheon It's a bad idea (I think) to allow 2 ways of passing many arguments to an option. I would choose either --bg=1 --bg=2 --bg=3 => [1, 2, 3], which docopt will make into a list automaticaly, or having them comma-separated: --bg=1,2,3 => [1, 2, 3]. In this cas you would need some transformations.

from schema import Schema, And, Use

schema = Schema({'--bg': And(Use(lambda s: s.split(',')), [Use(int)])})
assert schema.validate({'--bg': '1,2,3'}) == {'--bg': [1, 2, 3]}