Allow custom shell code to process Swift custom completion candidates

[rgoldberg]

Allow custom shell code to process Swift custom shell completion candidates.

Currently, the completion candidates returned from Swift custom shell completion code to the requesting shell are only processed in a single way per shell. Sometimes, you need more complex shell-side scripting to parse more complex completion concepts.

e.g., I want to match the completing shell word against the Swift String name property of certain structs, but, once a completion candidate has been selected, I want the text that is inserted into the command line to be the integer id property from the same struct. I cannot do this using the current embedded call to the zsh _describe function.

The solution is to add a shellScript: String = "" parameter to CompletionKind.custom(…).

When the shell completion script is generated, the value of shellScript will be escaped for a single-quoted shell string, and then be inserted into a single quoted string. If that string is empty, existing completion candidate processing will be used; otherwise, the given shell script will be run via eval to process the custom completion candidates when completion candidates are requested by the user.

The custom shell script will be able to access the completion candidates from a shell array, tentatively named completions (for zsh, there will be 2 arrays non_empty_completions & empty_completions). The custom shell script will be responsible for matching, displaying & inserting candidates.

if the completion closure is not provided, it will default to nil, in which case the generated completion script will eval the shellScript without calling Swift for completions (i.e. it won't call the Swift binary with a ---completions option). In this case, all completion candidate arrays available to shellScript will be empty.

The shellScript can be completely different for different shells; Swift code would need to switch on CompletionShell.requesting for different shells & on CompletionShell.requestingVersion for different versions of a shell.

In the future, if there are common complex reusable completion candidate processing patterns, functions returning a String of shell code could be added to SAP so that users could use them instead of the default processing without needing to write the scripts themselves, as they would probably be complicated, and producing similar functionality across 3 shells would be even more difficult.