Re: [BuildStream] bst CLI design and consistency (UI)

[Richard Maw <richard maw codethink co uk>]

On Wed, Dec 05, 2018 at 11:14:57AM +0100, Jürg Billeter wrote:
> On Fri, 2018-11-30 at 14:44 -0500, Chandan Singh wrote:
> > shell
> > ~~~~~
> >
> > Rather than introducing a new `-e` syntax for handling multiple elements, I am
> > wondering if we can do something similar by removing all positional arguments
> > except ELEMENTS, i.e. removing the CMD positional argument. Something like:
> >
> > 1. Convert COMMAND positional argument to a `-c`/`---command` optional
> >    argument. This will be a BREAKING change.
> > 2. Add support for multiple elements.
>
> I'd like to avoid the need for `--command`. Command wrappers on UNIX
> systems typically use `--` as separator where that's necessary. Is
> there no way with `Click` we can support `--` between element arguments
> and command?
>
> If `Click` has no built-in support for this, can't we do it ourselves,
> i.e., declare a single `Click` argument list for both? I don't know
> whether we can provide proper help/usage in that case, but worst case
> we could still explain usage in the help text for that combined option.
> And with mandatory .bst extensions, we could even make `--` optional.

I looked at doing this before settling on the `-e` syntax.

Click not only has no built-in support for this
but obstructs us in attempting to do our own parsing
by consuming the -- itself and having no facility for us to get it.

    $ cat > test.py <<'EOF'
    > import click
    > 
    > @click.command()
    > @click.argument('args', nargs=-1)
    > def main(args):
    >     print(args)
    > 
    > if __name__ == '__main__':
    >     main()
    > EOF
    $ python3 test.py foo bar -- baz qux
    foo bar baz qux

The closest we can get would be to have a CLI like:

    bst shell -- foo.bst bar.bst -- /bin/hello

The multiple-element-shell MR has been in flight since before it was decided
that elements ending in .bst is a hard requirement,
so wasn't reflected so much in discussion up until this point.

We _could_ have a heuristic to attempt to split
in the absence of -- at the beginning of the argument list
and -- at the end of the element list
(or -- before the elements and -- before the command if that helps).

If you're in the position to have an executable whose name ends in .bst,
then we can add a heuristic that absolute paths must be part of the command.

If we've got an executable called -- then we can also cope with the double --,
though this makes for an absurd command-line:

    # Run `-- baz qux` in a shell made of foo.bst and bar.bst.
    bst shell -- foo.bst bar.bst -- -- baz qux

I'm not a fan of heuristic-using command-line interfaces, as a user,
(I don't even like that commands like rm let you pass file paths without --
 given the problems this causes with people doing `rm *` in directories
 which contain files beginning with -)
since if it's not explicitly needed all the time it'll be forgotten
when someone has to write a script to drive it with arbitrary input;
when the only thing worse than it not being well documented how to do so
is the frequent case of there not actually being a way to.

I preferred adding the `-e` syntax as I thought it would be the least worst,
since it fit with the available facilities of click.py
and didn't require the CLI people use manually to differ
from the one they would have to use for scripts with arbitrary input.

Since the `-e` syntax is not acceptable I'll make `bst shell` use a heuristic,
though better ideas on how to make it obvious that -- escaping exists
are welcome.