| 1 |
.. _shell-completion: |
| 2 |
|
| 3 |
Shell completion |
| 4 |
================ |
| 5 |
|
| 6 |
Goal is to provide tool to define shell completion through modulefile. Need |
| 7 |
comes from the ability of the :mfcmd:`source-sh` modulefile command to |
| 8 |
reproduce :ref:`the shell changes made by a sourced shell |
| 9 |
script<source-shell-script-in-modulefile>`. Completion definitions are part |
| 10 |
of those shell changes, so there is a need to be able to define them through |
| 11 |
modulefile command. |
| 12 |
|
| 13 |
:mfcmd:`complete` and :mfcmd:`uncomplete` modulefile commands are introduced |
| 14 |
to give this ability to define or unset completion for commands in shell that |
| 15 |
provides a command to define such completion. Such shells are: |
| 16 |
|
| 17 |
* bash |
| 18 |
* tcsh |
| 19 |
* fish |
| 20 |
|
| 21 |
No shell command to setup completion has been found on other shells. For |
| 22 |
instance on zsh, completion is made through files saved in specific |
| 23 |
directories. |
| 24 |
|
| 25 |
|
| 26 |
complete |
| 27 |
-------- |
| 28 |
|
| 29 |
:mfcmd:`complete` takes as argument: |
| 30 |
|
| 31 |
* shell: name of the shell this completion definition should be applied to |
| 32 |
* command: name of the command the completion targets |
| 33 |
* completion arguments aka body: parameter to define completion on shell |
| 34 |
|
| 35 |
*Shell* should correspond to one of the supported shell name. When modulefile |
| 36 |
is evaluated, the :mfcmd:`complete` command will produce shell code as output |
| 37 |
only if *shell* name corresponds to the shell the :file:`modulecmd.tcl` script |
| 38 |
has been initialized for. |
| 39 |
|
| 40 |
If an unsupported *shell* name is set, :mfcmd:`complete` command is simply |
| 41 |
ignored. No error is produced as the shell specified may be supported on a |
| 42 |
latter version of the :file:`modulecmd.tcl` script and the modulefile may be |
| 43 |
provided for use by different version of this script. |
| 44 |
|
| 45 |
*Command* name should be a non-empty string. Otherwise an evaluation error is |
| 46 |
returned. |
| 47 |
|
| 48 |
*Body* is shell-specific. When modulefile is evaluated the body defined on a |
| 49 |
:mfcmd:`complete` command is not checked by module. Possible options are |
| 50 |
numerous and really different from one shell to another so it is up to the |
| 51 |
modulefile author to ensure the body definition used is correctly supported on |
| 52 |
targeted shell. |
| 53 |
|
| 54 |
*Body* value is not escaped to fit shell evaluation. Defined syntax should be |
| 55 |
compatible with this evaluation. It is up to the modulefile writer to use the |
| 56 |
correct syntax as it cannot be guessed depending on what writer wants to |
| 57 |
achieve. |
| 58 |
|
| 59 |
For shells like fish: |
| 60 |
|
| 61 |
* Completion definition consist of multiple complete commands for a single |
| 62 |
*command* name. |
| 63 |
* Prior applying completion definition, any previous completion is cleared for |
| 64 |
*command*. We ensure modulefile provides the full completion definition for |
| 65 |
*command* this way. |
| 66 |
|
| 67 |
**Note**: when loading module on fish shell, completion is first fully removed |
| 68 |
for *command*. It is expected that modulefile provides the full completion |
| 69 |
definition for *command* and not rely on previous definition made elsewhere. |
| 70 |
|
| 71 |
:mfcmd:`complete` is evaluated on *load* but also *refresh* mode. Important on |
| 72 |
the later to get completion correctly redefined when initializing sub-shells. |
| 73 |
On *unload* mode, :mfcmd:`complete` becomes :mfcmd:`uncomplete`. |
| 74 |
|
| 75 |
uncomplete |
| 76 |
---------- |
| 77 |
|
| 78 |
:mfcmd:`uncomplete` is evaluated on *unload* mode. Like other *undo* command, |
| 79 |
it is ignored when unloading a modulefile. |
| 80 |
|
| 81 |
:mfcmd:`uncomplete` does not require a *shell* name as argument. Only the |
| 82 |
*command* name is expected. |
| 83 |
|
| 84 |
*Command* name should be a non-empty string. Otherwise an evaluation error is |
| 85 |
returned. |
| 86 |
|
| 87 |
:mfcmd:`uncomplete` command is provided in case of a need to specifically |
| 88 |
unset a defined completion. There should not be a lot of use case for this |
| 89 |
command, but it does not cost much to add as it is needed to undo the |
| 90 |
:mfcmd:`complete` command when a modulefile is unloaded. |
| 91 |
|
| 92 |
.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: |