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