Improve usability of command line UI

[stecman]

Having CompletionCommand::execute attempt completion by default is a pretty poor user experience, especially if you're not sure what the command is for since it gives an error immediately that references the library internals:

$ myapp _completion

  [RuntimeException]
  Failed to configure from environment; Environment var COMP_LINE not set.

_completion [-g|--generate-hook] [-p|--program="..."] [--shell-type[="..."]]

Ideally this would be changed so that:

1. By default (ie. with no options or arguments), the running myapp _completion prints use instructions or help.
2. An option like --run-completion is required to attempt completion.

[aik099]

👍

Maybe we should add some instructions from README.md to this command help screen, so that people would know that --generate-hook argument needs to be used and command itself is designed to be used from .bashrc.

Ideally I see 2 more modes for _completion command:

• app _complete install - generates & installs hook (does nothing if already installed)
• app _complete validate - checks that hook was installed and is working and prints out clever fixing suggestions if it doesn't

The Travis CI gem (https://github.com/travis-ci/travis.rb) does completion installation too. It added following to my ~/.bashrc:

# added by travis gem
[ -f /home/alex/.travis/travis.sh ] && source /home/alex/.travis/travis.sh

Currently it's not easy to start because a hook needs to be generated and added to .bashrc or other place manually.

[aik099]

@stecman if you support plan from #30 (comment), then please specify what folder we can use to store generated hooks.

[stecman]

The intended use is to put the generate-hook call in your shell profile rather than generating a hook and saving the output in the shell profile, so this doesn't really need a folder. Having the hook generated on profile load only adds a small overhead and means that the hook is always up to date. Thus, an "installed" hook might look something like:

[ -f /usr/bin/foobar ] && source <(foobar _completion --generate-hook)

[aik099]

So my suggestion in #30 (comment) is completely off I guess. Then what's needed is:

1. add --run-completion|-r option, that would trigger completion
2. if both --generate-hook and --run-completion options are not given, then forward user to app help _completion command
3. update hook generation instructions to use this command:

[ -f /absolute/path/to/app ] && source <(/absolute/path/to/app _completion --generate-hook --program app)

1. update generated hook code to include --run-completion option, when invoking _completion command.

[aik099]

We should also replace BASH with shell because it's auto-complete not only for BASH in any help texts.

[aik099]

@stecman , ping.

[stecman]

@aik099, your list of things needed is good, except for:

3. update hook generation instructions to use this command
   [ -f /absolute/path/to/app ] ...

It makes sense for that file existence check to be included during a scripted install process (eg. app _complete install), but I'm not sure that it needs to go in the readme or usage instructions unless it's just a small comment at the end in addition to this:

4. If you want the completion to apply automatically for all new shell sessions, add the command from step 3 to your shell's profile (eg. ~/.bash_profile or ~/.zshrc).

I see the file check to be mostly of value where a user hasn't directly set up the completion themselves and an error like -bash: /absolute/path/to/app: No such file or directory in every new shell doesn't give any easy hints for debugging.

[aik099]

It makes sense for that file existence check to be included during a scripted install process (eg. app _complete install), but I'm not sure that it needs to go in the readme or usage instructions unless it's just a small comment at the end in addition to this:

I'm confused. In #30 (comment) you said that you preffer real-time hook generation vs generating hook once and installing it. So what is it?

I see the file check to be mostly of value where a user hasn't directly set up the completion themselves and an error like -bash: /absolute/path/to/app: No such file or directory in every new shell doesn't give any easy hints for debugging.

I guess we need to note, that /absolute/path/to/app needs to be replaced with you app file.

[aik099]

And we go with install and validate sub-commands like I proposed in #30 (comment) , then --generate-hook option needs to be transformed into sub-command as well.

[stecman]

I'm confused. In # 30 (comment) you said that you prefer real-time hook generation vs generating hook once and installing it. So what is it?

Real-time. Perhaps our interpretations of install in this context differ. There are a few 'install' type actions I see:

1. Registering completion in the current shell (ie. running source <(/absolute/path/to/app _completion --generate-hook --program app))
2. Adding the code from 1. to the shell profile so that 1. automatically occurs for each new shell.

When I say "scripted install" / app _completion install, I mean option 2.. Option 1. can't actually be done automatically by a command/sub-command as it's not possible to alter the parent shell of a process.

My point was that adding [ -f /absolute/path/to/app ] && ... to the instructions in the readme as they are at the moment isn't useful for people getting started with the library. This is getting a little off topic though - an automatic install command probably belongs in its own issue.