Shell completion¶
Goal is to provide tool to define shell completion through modulefile. Need
comes from the ability of the source-sh modulefile command to
reproduce the shell changes made by a sourced shell
script. Completion definitions are part
of those shell changes, so there is a need to be able to define them through
modulefile command.
complete and uncomplete modulefile commands are introduced
to give this ability to define or unset completion for commands in shell that
provides a command to define such completion. Such shells are:
- bash
- tcsh
- fish
No shell command to setup completion has been found on other shells. For instance on zsh, completion is made through files saved in specific directories.
complete¶
complete takes as argument:
- shell: name of the shell this completion definition should be applied to
- command: name of the command the completion targets
- completion arguments aka body: parameter to define completion on shell
Shell should correspond to one of the supported shell name. When modulefile
is evaluated, the complete command will produce shell code as output
only if shell name corresponds to the shell the modulecmd.tcl script
has been initialized for.
If an unsupported shell name is set, complete command is simply
ignored. No error is produced as the shell specified may be supported on a
latter version of the modulecmd.tcl script and the modulefile may be
provided for use by different version of this script.
Command name should be a non-empty string. Otherwise an evaluation error is returned.
Body is shell-specific. When modulefile is evaluated the body defined on a
complete command is not checked by module. Possible options are
numerous and really different from one shell to another so it is up to the
modulefile author to ensure the body definition used is correctly supported on
targeted shell.
Body value is not escaped to fit shell evaluation. Defined syntax should be compatible with this evaluation. It is up to the modulefile writer to use the correct syntax as it cannot be guessed depending on what writer wants to achieve.
For shells like fish:
- Completion definition consist of multiple complete commands for a single command name.
- Prior applying completion definition, any previous completion is cleared for command. We ensure modulefile provides the full completion definition for command this way.
Note: when loading module on fish shell, completion is first fully removed for command. It is expected that modulefile provides the full completion definition for command and not rely on previous definition made elsewhere.
complete is evaluated on load but also refresh mode. Important on
the later to get completion correctly redefined when initializing sub-shells.
On unload mode, complete becomes uncomplete.
uncomplete¶
uncomplete is evaluated on unload mode. Like other undo command,
it is ignored when unloading a modulefile.
uncomplete does not require a shell name as argument. Only the
command name is expected.
Command name should be a non-empty string. Otherwise an evaluation error is returned.
uncomplete command is provided in case of a need to specifically
unset a defined completion. There should not be a lot of use case for this
command, but it does not cost much to add as it is needed to undo the
complete command when a modulefile is unloaded.