Debian Codegraph @

doc/source/design/mod-to-sh-sub-command.rst

raw
1 .. _mod-to-sh-sub-command:
2
3 mod-to-sh sub-command
4 =====================
5
6 Produce shell code of environment changes made by loading designated
7 modulefiles and send this content to the report message channel. User views
8 the produced shell code as output.
9
10 :subcmd:`mod-to-sh` could be send as the opposite of :subcmd:`sh-to-mod`. The
11 former transforms a modulefile into shell code whereas the latter transforms
12 shell code into a modulefile.
13
14
15 Configuration
16 -------------
17
18 None.
19
20
21 Sub-command properties
22 ----------------------
23
24 General properties:
25
26 * Shortcut name: none
27 * Accepted option: ``--force``, ``--icase``, ``--auto``, ``--no-auto``
28 * Expected number of argument: 2 to N
29 * Accept boolean variant specification: yes
30 * Parse module version specification: yes
31 * Fully read modulefile when checking validity: yes
32 * Sub-command only called from top level: yes
33 * Lead to modulefile evaluation: yes (``load`` mode)
34
35 Arguments expected:
36
37 * First argument should be a supported shell name
38
39 * like *bash* or *fish*
40 * An error is produced if an unsupported shell is specified
41 * It defines the language that sub-command will use to produce shell code
42
43 * After the first argument, comes the modulefile specification
44
45 * Multiple modulefiles can be specified
46 * With advanced version specifiers and variants
47 * It defines the modulefiles to load
48
49 ``mod-to-sh`` loads designated modulefile(s) and instead of rendering the
50 corresponding environment changes to the stdout channel, the shell code is
51 sent to the message report channel (stderr).
52
53 Target shell is changed, from the one specified as argument to
54 :file:`modulecmd.tcl` script to the one specified as argument to ``mod-to-sh``
55 sub-command.
56
57 Once shell code is produced and sent to the message channel (stderr), target
58 shell defined for :file:`modulecmd.tcl` is restored to get on the regular
59 code channel (stdout) the evaluation status. For instance for *sh* shell:
60 ``test 0`` if successful, ``test 0 = 1`` otherwise.
61
62 Shell code produced by ``mod-to-sh`` is only sent to message channel. It is
63 not sent to the code channel.
64
65 ``modtosh_real_shell`` state is introduced and set by ``mod-to-sh``
66 sub-command. When defined, shell code rendering procedure knows if code should
67 be sent to the message channel and then cleared, not to be rendered on code
68 channel. This state contains the target shell of :file:`modulecmd.tcl`. So
69 shell rendering procedure can restore target shell then produce the final
70 shell code to render (evaluation status).
71
72 Modulefile evaluation is made like a regular ``module load``. Thus if
73 specified modulefile is already loaded, its corresponding environment changes
74 will not appear on the ``mod-to-sh`` result.
75
76 Shell code produced for ``mod-to-sh`` is filtered to only contain environment
77 changes of designated modulefiles and not the Modules-specific environment
78 context (like ``LOADEDMODULES`` or ``_LMFILES_`` environment variables).
79
80 ``mod-to-sh`` sub-command automatically adjusts the :mconfig:`verbosity`
81 configuration option to the ``silent`` mode. As produced shell code is sent
82 to the message channel, it should not mix with report messages. Setting
83 verbosity to ``silent`` disables loading messages or :mfcmd:`reportWarning`,
84 :mfcmd:`reportError` and :mfcmd:`puts stderr<puts>` messages defined in
85 modulefiles. :mconfig:`verbosity` is not changed if set to ``trace`` mode or
86 any higher mode (debugging).
87
88
89 module-info command
90 -------------------
91
92 As ``mod-to-sh`` leads to modulefile evaluation, the :mfcmd:`module-info
93 command<module-info>` modulefile command returns the ``mod-to-sh`` string
94 when used in a modulefile evaluated through this sub-command. It can also be
95 queried against this command name string to return Boolean value depending if
96 ``mod-to-sh`` is the sub-command currently running.
97
98 .. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: