1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
.. _shell-completion:
Shell completion
================
Goal is to provide tool to define shell completion through modulefile. Need
comes from the ability of the :mfcmd:`source-sh` modulefile command to
reproduce :ref:`the shell changes made by a sourced shell
script<source-shell-script-in-modulefile>`. Completion definitions are part
of those shell changes, so there is a need to be able to define them through
modulefile command.
:mfcmd:`complete` and :mfcmd:`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
--------
:mfcmd:`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 :mfcmd:`complete` command will produce shell code as output
only if *shell* name corresponds to the shell the :file:`modulecmd.tcl` script
has been initialized for.
If an unsupported *shell* name is set, :mfcmd:`complete` command is simply
ignored. No error is produced as the shell specified may be supported on a
latter version of the :file:`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
:mfcmd:`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.
:mfcmd:`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, :mfcmd:`complete` becomes :mfcmd:`uncomplete`.
uncomplete
----------
:mfcmd:`uncomplete` is evaluated on *unload* mode. Like other *undo* command,
it is ignored when unloading a modulefile.
:mfcmd:`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.
:mfcmd:`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
:mfcmd:`complete` command when a modulefile is unloaded.
.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent:
|
