How to frame unordered arguments in docopt?

Question

I'm trying to frame a docopt usage which accepts set of options.

Naval Fate.

Usage:
  naval_fate.py ship
  [-b <b_command>]
  [-e <e_command>]

Runnable example: http://try.docopt.org/?doc=Naval+Fate.%0D%0A%0D%0AUsage%3A%0D%0A++naval_fate.py+ship%0D%0A++%5B-b+%3Cb_command%3E%5D%0D%0A++%5B-e+%3Ce_command%3E%5D&argv=ship+-e+c+

If I use this, it works fine:

ship -b barg -e earg

The output is:

{
  "-b": true, 
  "-e": true, 
  "<b_command>": "barg", 
  "<e_command>": "earg", 
  "ship": true
}

But if use this, it still gives the same values to the respective arguments:

ship -e earg -b barg 

Output:

{
  "-b": true, 
  "-e": true, 
  "<b_command>": "earg", 
  "<e_command>": "barg", 
  "ship": true
}

Note that I passed earg to -e but it is assigned to b_command in the output.

I saw the same behavior with golang's docopt-go package. Is my usage string wrong? If so, how should I frame the docopt usage string such that it assigns the correct values correct arguments and honors the specified arguments?

Answer 1

naval_fate.py ship
[-b <b_command>]
[-e <e_command>]

The interpretation of the docopt you wrote is as follows:

• The subcommand ship,
• Followed by zero or more of the following in any order:
  • The boolean flag -b,
  • A positional argument <b_command>,
  • The boolean flag -e,
  • A positional argument <e_command>.

So all of the following would be considered legal input commands:

naval_fate.py ship -e
naval_fate.py ship BB -e
naval_fate.py ship -eb
naval_fate.py ship BB EE

The correct way to express flags like -b <b_command> and -e <e_command> is through a section called Options.

Naval Fate.

Usage:
  naval_fate.py ship [options]

Options:
  -b <b_command>   Description of -b
  -e <e_command>   Description of -e