[RFC] Automate the creation of shell completions

[donovanglover]

I noticed that some options like crystal spec --verbose are missing from the shell completions. To prevent missing completions like this from happening, I believe that some form of automation should be in place. One solution would be to extend OptionParser to handle shell completions as well.

Advantages

• Less barriers to entry. Knowledge of how to write completions for a specific shell (bash, zsh, etc.) is not needed. Everything is automated and leaves no room for error.
• Easily verifiable. It is easy to verify that all possible options are accounted for.
• Don't repeat yourself. You only have to change one location (the source file) to update both the program and its shell completions.

Disadvantages

• Complexity. Any form of file generation adds complexity to the build process.
• Scope. Some edge cases or other wanted features may be nontrivial to implement.
• Delegation of responsibility. OptionParser now handles shell completions as well.

It may also be ideal to create a command similar to crystal docs, but for shell completions instead.

Any other solutions are also appreciated. The goal of this RFC is to prevent having to write the same thing multiple times and ensure that all possible shell completions exist.

[straight-shoota]

A maybe far-fetched idea that comes to mind is perhaps taking a look at docopt - a standard for command line interface description. This could either be implemented by OptionParser emiting or parsing docopt markup. That output can then be used to automatically generate shell completion scripts.
It's an additional step but there are already converters from docopt to shell completion. Maybe it's easier to do this directly in Crystal... but a standard format could be worth considering.

[HertzDevil]

I think we should do it for the compiler regardless of whether it will be backed by OptionParser. The interface could be something like crystal tool complete -- crystal ....

A thing to consider is that OptionParser provides no means of validating an argument against a set of strings by itself; it alone is inadequate for generating shell completions for e.g. --define (all built-in flags supported by the compiler) and --emit (llvm-ir and so on).