Fix bash completion

[phamann]

TL;DR

Fixes bash/zsh completion and adds documentation to README.md. Closes #127

Why?

Unfortunately our flag parsing library kingpin produces the bash completion as a side-effect of its main kingpin.Parse(args ...) function. It also doesn't follow its own convention of writing the output the io.Writer's provided to app.Writers(out, in), thus we have no control over the output. Lastly it attempts to call app.Terminate() to exit the program early. See full implementation here.

We attempt to control kingpin's side-effects via suppressing any writing to stdout/err during Parse() and preventing it from terminating the application - which gives us much greater control over error and usage output. However our own logic was conflicting with the completion and appending usage to the end of the output thus breaking completion.

How?

Due to the above, the easiest solution is to detect that completion flags are present and allow kingpins parsing logic to terminate the app early. This has the trade-off of making it harder to test, which is why I've omitted any test coverage in this PR 😿

[triblondon]

I find this a tad confusing - what's the difference between --completion-bash and --completion-script-bash? Does installing it in the profile avoid the need to use the --completion-bash flag? When would you want to do one vs the other? And when we say autocomplete do we mean tab-based autocomplete? If not how do I trigger the autocompletion (I know this is a shell specific thing but you're providing instructions for both popular shells and I imagine the resulting UX would be similar?)

[phamann]

Good questions.

The --completetion-script-bash generates the shell script that you'd source in your bash profile via eval "$(fastly --completion-script-bash)" or similar, and tells your shell how to load the tab autocompletions.

_fastly_bash_autocomplete() {
    local cur prev opts base
    COMPREPLY=()
    cur="${COMP_WORDS[COMP_CWORD]}"
    opts=$( ${COMP_WORDS[0]} --completion-bash ${COMP_WORDS[@]:1:$COMP_CWORD} )
    COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
    return 0
}
complete -F _fastly_bash_autocomplete fastly

The --completion-bash actually provides the completions in a newline delimited list. Such as:

create
list
describe
update
delete

So TL;DR the script tells your shell how to invoke the CLI with the completion flag to get the list of tab completions. I.e. users only need to know about --completion-script-bash and how to source it in their shell.

[triblondon]

That's great, thanks. Do you think people other than me would benefit from that context? If so, you could update the README text.

[thommahoney]

My comment is not blocking. I think @triblondon wanted to move the installation instructions into their own file anyway.