Group options

[conqp]

Is it possible to add a feature for dynamically grouping options, like:

Naval Fate.

Usage:
  naval_fate.py ship new <name>...
  naval_fate.py ship <name> move <x> <y> [ship_options]
  naval_fate.py ship shoot <x> <y>
  naval_fate.py mine (set|remove) <x> <y> [mine_options]
  naval_fate.py [options]

Options:
  -h --help     Show this screen.
  --version     Show version.

Mine Options:
  --moored      Moored (anchored) mine.
  --drifting    Drifting mine.

Ship Options:
  --speed=<kn>  Speed in knots [default: 10].

[frnhr]

I made a PR that enables just that: #313

This example would be:

Naval Fate.

Usage:
  naval_fate.py ship new <name>...
  naval_fate.py ship <name> move <x> <y> [-ship_options-]
  naval_fate.py ship shoot <x> <y>
  naval_fate.py mine (set|remove) <x> <y> [-mine_options-]
  naval_fate.py [options]

Options:
  -h --help     Show this screen.
  --version     Show version.

Mine Options:
  --moored      Moored (anchored) mine.
  --drifting    Drifting mine.

Ship Options:
  --speed=<kn>  Speed in knots [default: 10].

Feedback is very welcome.

[conqp]

Awesome work!

[keleshev]

Thanks for your taking your time.

Docopt syntax is based on POSIX, and we allow extensions only if their syntax is widely used. Do you have any alternatives to [-ship_options-] syntax that are more widely recognized? You are trying to solve this particular problem, that other CLI likely encountered before. How did they solve it? What syntax did they use?

[frnhr]

That's the best syntax I could come up with. Suggestions are welcome.

Another idea was to just use [ship_options] (exactly as suggested here by @conqp), but that would limit its usability only to options. That is ok for many applications and is probably more widely recognized. I'm interested in a bit more though (see example in the PR).

I wasn't able to find any mentions of similar problems nor their solutions by other parsers. Perhaps I'm bad at searching but I did try... From what I have encountered in the wild, subcommands would be the way to go, git-style. Naval Fate implemented with subcommands would, IMO, be as serious overkill.

[frnhr]

I have made a fork for my own use. I tried to make the authorship and copyright info plain. I hope you are ok with this, @keleshev. Let me know if not.

https://github.com/frnhr/docopt_plus

I will try to implement some additional features there. Some of which might be acceptable for merge with Docopt in the future.

[feluxe]

Docopt syntax is based on POSIX, and we allow extensions only if their syntax is widely used. Do you have any alternatives to [-ship_options-] syntax that are more widely recognized? You are trying to solve this particular problem, that other CLI likely encountered before. How did they solve it? What syntax did they use?

@frnhr @keleshev

I don't understand why we need an additional syntax for it. It works for options:

Usage:
naval_fate.py [options]

Options:
  -h --help     Show this screen.
  --version     Show version.

Just let it work for more_options the same way:

Usage:
naval_fate.py one [options]
naval_fate.py two [more_options]

Options:
    -h --help     Show this screen.
    --version     Show version.

More_options:
    -f, --foo     Foo

?

[frnhr]

Well, we don't need a new syntax, that's true. And probably more POSIX-y as well. But when I see usage pattern like this:

dump_and_erase.py (configuration | settings | options) [options]

I have no way of knowing whether options is a command or an option group. This makes it a "magic string", no? Using [-options-] (or whatever other new syntax is best) solves this issue.

Additionally, it might be interesting to have non-optional groups of options, for example:

naval_fate.py two -options-for-two- [three -options-for-three-]

Options for two:
  --x2 X2  The X-coordinate
  --y2 Y2  The Y-coordinate

Options for  three:
  --x3 X3  The X-coordinate
  --y3 Y3  The Y-coordinate

These are obviously contrived examples, perhaps there are better examples in the wild...

But yeah, it's not in any standard...

[conqp]

Oh, this issue is five years old. And I don't use docopt any longer. You might consider closing this.

[SeeSpotRun]

@conqp probably quicker if you close it yourself...