Debian Codegraph @

doc/source/design/control-mode-behaviors.rst

raw
1 .. _control-mode-behaviors:
2
3 Control mode behaviors
4 ======================
5
6 - Modulefile commands that modify environment variables applies
7
8 - a behavior when modulefile is loaded
9 - and another behavior when modulefile is unloaded
10
11 - Depending on the situation, it seems interesting to apply a different
12 behavior when modulefile is unloaded:
13
14 - restore value unset at load time, either:
15
16 - append-on-unload
17 - prepend-on-unload
18
19 - remove value from list: remove-on-unload
20 - unset full variable value: unset-on-unload
21 - set another value, either:
22
23 - append-on-unload
24 - prepend-on-unload
25 - set-on-unload (for non-path-like variable)
26
27 - do nothing: noop-on-unload
28
29 - Also when modulefile loads sometimes it may be interesting to apply a
30 slightly different behavior depending on the situation:
31
32 - set value only if variable is undefined: set-if-undef
33
34 - Concerned modulefile commands:
35
36 - :mfcmd:`module use<module>`
37 - :mfcmd:`module unuse<module>`
38 - :mfcmd:`setenv`
39 - :mfcmd:`unsetenv`
40 - :mfcmd:`append-path`
41 - :mfcmd:`prepend-path`
42 - :mfcmd:`remove-path`
43
44 - Only applies when the above commands are called from a modulefile (as some
45 of these commands can also act as module sub-commands)
46
47 Unload behavior
48 ---------------
49
50 - Unload behavior of concerned modulefile commands:
51
52 +--------------+-------------------------+--------------------------+-----------------------+
53 | Command | Default unload behavior | Specific unload behavior | Alternative behaviors |
54 | | | | to add |
55 +==============+=========================+==========================+=======================+
56 | module use | remove-on-unload | *n/a* | |
57 +--------------+-------------------------+--------------------------+-----------------------+
58 | module unuse | remove-on-unload | *n/a* | append-on-unload, |
59 | | | | prepend-on-unload, |
60 | | | | noop-on-unload |
61 +--------------+-------------------------+--------------------------+-----------------------+
62 | setenv | unset-on-unload | *n/a* | |
63 +--------------+-------------------------+--------------------------+-----------------------+
64 | unsetenv | noop-on-unload | set-on-unload (when 2nd | unset-on-unload |
65 | | | argument is provided) | |
66 +--------------+-------------------------+--------------------------+-----------------------+
67 | append-path | remove-on-unload | *n/a* | |
68 +--------------+-------------------------+--------------------------+-----------------------+
69 | prepend-path | remove-on-unload | *n/a* | |
70 +--------------+-------------------------+--------------------------+-----------------------+
71 | remove-path | noop-on-unload | *n/a* | remove-on-unload, |
72 | | | | append-on-unload, |
73 | | | | prepend-on-unload |
74 +--------------+-------------------------+--------------------------+-----------------------+
75
76 - When either restoring or setting other value for path-like modulefile
77 commands, it is needed to know if the value should be appended or prepended.
78
79 - Either restoring or setting other value result in the same behavior name
80
81 - *append-on-unload* and *prepend-on-unload*
82 - position of the option will determine if the values to set are:
83
84 - those unset at load time: when option is placed prior value list
85 - a different list of value: when option is placed after value list to
86 unset at load time and another value list is defined after option
87
88 - The *set-on-unload* behavior is only useful for modulefile commands which
89 unset value on load mode, as commands that set value on load mode mainly
90 need to unset the value set.
91
92 - Default unload behavior of ``module unuse``, ``unsetenv`` and
93 ``remove-path`` commands can also be set as an option in their argument
94 list. Helps to dynamically choose the behavior to apply, which could be the
95 default behavior.
96
97 Load behavior
98 -------------
99
100 - Load behavior of concerned modulefile commands:
101
102 +--------------+-----------------------+-----------------------+
103 | Command | Default load behavior | Alternative behaviors |
104 | | | to add |
105 +==============+=======================+=======================+
106 | module use | set-on-load | |
107 +--------------+-----------------------+-----------------------+
108 | module unuse | remove-on-load | |
109 +--------------+-----------------------+-----------------------+
110 | setenv | set-on-load | set-if-undef |
111 +--------------+-----------------------+-----------------------+
112 | unsetenv | unset-on-load | |
113 +--------------+-----------------------+-----------------------+
114 | append-path | add-on-load | |
115 +--------------+-----------------------+-----------------------+
116 | prepend-path | add-on-load | |
117 +--------------+-----------------------+-----------------------+
118 | remove-path | remove-on-load | |
119 +--------------+-----------------------+-----------------------+
120
121 Modulefile command options
122 --------------------------
123
124 - Alternative behaviors could be specified by setting the associated option
125 over the modulefile command:
126
127 - ``--remove-on-unload``
128 - ``--append-on-unload``
129 - ``--prepend-on-unload``
130 - ``--noop-on-unload``
131 - ``--unset-on-unload``
132 - ``--set-if-undef``
133
134 - The ``--append-on-unload`` and ``--prepend-on-unload`` options either:
135
136 - restore the value list removed at load time if placed prior this value
137 list
138 - set a different value list if a different list of value is specified
139 after option (all the values set after the option are considered element
140 to add to the path-like variable)
141 - both options also accept to be set prior or right after variable name or
142 even right at the end of argument list to restore value list removed at
143 load time
144
145 - The ``--set-if-undef`` option does not change the behavior of ``setenv``
146 when modulefile is unloaded: environment variable will be unset whether the
147 option is set or not.
148
149 - The ``--remove-on-unload`` option can be set anywhere in argument list
150
151 - The ``--remove-on-unload``, ``--append-on-unload`` and
152 ``--prepend-on-unload`` options cannot be mixed with the ``--index`` option
153 of ``remove-path`` sub-command.
154
155 - The ``--append-on-unload``, ``--prepend-on-unload`` options cannot be
156 mixed with the ``--glob`` option of ``remove-path`` sub-command.
157
158 - The ``--remove-on-unload``, ``--append-on-unload``, ``--prepend-on-unload``
159 and ``--noop-on-unload`` options:
160
161 - can be placed at different positions in argument list to limit error
162 cases
163 - if multiple options of this kind are defined in argument list, the one
164 defined at the most right is retained
165
166 Misc
167 ----
168
169 - *FUTURE*: what is applied to:
170
171 - ``module use`` may also be interesting for ``module load``
172 - ``module unuse`` may also be interesting for ``module unload``
173
174 - See also :ref:`mode-select` design which corresponds to a different approach
175 to the same kind of feature
176
177 .. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: