docopts adds the `--` token to the position arguments

[EricCrosson]

Howdy!

I think I've got a bug, or maybe it's a feature request.

I've got a hypothetical docstring like so

# Usage
#   search --directory=<string> <command>...

and I'm trying to run the <command>... grep -A4 some-package package.json

The trouble is, if I invoke my script without the -- I get

$ search --directory foo grep -A4 some-package package.json
error:
Usage:
  search --directory=<string> <command>...

and if I add the -- token so that the -A4 isn't parsed by docopts then I get

$ search --directory foo -- grep -A4 some-package package.json
docopt_print_ARGS => ARGS
           --directory = foo
         <command>,4 = package.json
         <command>,0 = --
         <command>,1 = grep
         <command>,2 = -A4
         <command>,3 = some-package
         <command>,# = 5

so it appears the -- is incorrectly being added as a position argument, in addition to being used as the no more arguments token.

This would be pretty gnarly to work around in the shell script, as I'd have to handle both the normal case where there is no -- and the exceptional case where -- is the first position argument. I think it's more natural to just drop the -- as a parsed argument.

What do you think? Would this break some backwards compatibility?

[Sylvain303]

Hi @EricCrosson

docopts is bounded to docopt syntax parser. Could you try some variant from the docopt.org documentation:

From: http://docopt.org/

A double dash "--", when not part of an option, is often used as a convention to separate options and positional arguments, in order to handle cases when, e.g., file names could be mistaken for options. In order to support this convention, add "[--]" into your patterns before positional arguments.

Usage: my_program [options] [--] <file>...

Apart from this special meaning, "--" is just a normal command, so you can apply any previously-described operations, for example, make it required (by dropping brackets "[ ]")

So, I didn't test, but I would say, that's a normal behavior. Does it help? Regards.

[EricCrosson]

Hi @Sylvain303 ,

thanks for reminding me about the way docopt handles --, it's been a few years! since I ran into that!

You're right, the addition of [--] gave me a workaround, although I had to manually check if the -- was provided and shift it off of the command array. Little wonky, but as you said, "works as intended."

Thanks again!

[Sylvain303]

Hi @EricCrosson,

Glad to help you. :smile:

In fact, it is not really "a workaround", it is the original behavior.

You should think it, as a "description language" for the command line syntax you expect to parse. As -- as not special meaning for doctop grammar it is parsed a normal parameter.

But, the grammar could be improved. :wink:

Have a nice day.