Debian Codegraph @

doc/source/design/shell-completion.rst

raw
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: