Debian Codegraph @

doc/source/design/output-configuration.rst

raw
1 .. _output-configuration:
2
3 Output configuration
4 ====================
5
6 Configuration
7 -------------
8
9 - Introduce options to define the content of the output:
10
11 - :mconfig:`avail_output`: elements to report on :subcmd:`avail` sub-command regular mode
12 - :mconfig:`avail_terse_output`: elements to report on ``avail`` sub-command terse mode
13 - :mconfig:`list_output`: elements to report on :subcmd:`list` sub-command regular mode
14 - :mconfig:`list_terse_output`: elements to report on ``list`` sub-command terse mode
15 - :mconfig:`spider_output`: elements to report on :subcmd:`spider` sub-command regular mode
16 - :mconfig:`spider_terse_output`: elements to report on ``spider`` sub-command terse mode
17
18 Specification
19 -------------
20
21 - Output configuration is available
22
23 - For ``avail`` sub-command, on regular and :option:`--terse` modes
24 - For ``list`` sub-command, on regular and :option:`--terse` modes
25 - For ``spider`` sub-command, on regular and :option:`--terse` modes
26
27 - Output configuration is not available (but could be added later on)
28
29 - For :option:`--long` and :option:`--json` modes
30 - For :subcmd:`aliases`, :subcmd:`savelist`, :subcmd:`whatis`/:subcmd:`search` and :subcmd:`display`/:subcmd:`help` sub-commands
31
32 - Output configuration defines the content of the output not its format
33
34 - Options :option:`--terse`, :option:`--long` and :option:`--json` defines output format
35
36 - These configurations are set by default with the elements reported by default
37
38 - ``avail_output``: ``modulepath:alias:dirwsym:sym:tag:variantifspec:key``
39 - ``avail_terse_output``: ``modulepath:alias:dirwsym:sym:tag:variantifspec``
40 - ``list_output``: ``header:idx:variant:sym:tag:key``
41 - ``list_terse_output``: ``header``
42 - ``spider_output``: ``modulepath:alias:dirwsym:sym:tag:variantifspec:via:key``
43 - ``spider_terse_output``: ``modulepath:alias:dirwsym:sym:tag:variantifspec``
44
45 - The above default value could be superseded:
46
47 - with an environment variable, that can be set through the use of the :subcmd:`config` sub-command
48
49 - :envvar:`MODULES_AVAIL_OUTPUT` to supersede ``avail_output`` default value
50 - :envvar:`MODULES_AVAIL_TERSE_OUTPUT` to supersede ``avail_terse_output`` default value
51 - :envvar:`MODULES_LIST_OUTPUT` to supersede ``list_output`` default value
52 - :envvar:`MODULES_LIST_TERSE_OUTPUT` to supersede ``list_terse_output`` default value
53 - :envvar:`MODULES_SPIDER_OUTPUT` to supersede ``spider_output`` default value
54 - :envvar:`MODULES_SPIDER_TERSE_OUTPUT` to supersede ``spider_terse_output`` default value
55
56 - with the :option:`-o`/:option:`--output` command-line option
57
58 - which applies to the current output mode defined
59 - ``-o``/``--output`` also supersedes environment variable definition
60
61 - Accepted elements in value lists are:
62
63 - For ``avail`` options: modulepath, alias, provided-alias, dirwsym,
64 indesym, sym, tag, key, variant, variantifspec, hidden, via (only on
65 regular output)
66 - For ``list`` options: header, idx, variant, alias, indesym, sym, tag, key,
67 hidden
68 - For ``spider`` options: modulepath, alias, provided-alias, dirwsym,
69 indesym, sym, tag, key, variant, variantifspec, hidden, via (only on
70 regular output)
71
72 - If the ``-o``/``--output`` options are wrongly specified
73
74 - An error is raised and evaluation terminates
75 - It may happen in the following situations
76
77 - No value set after the option
78 - Option set on unsupported module sub-command
79 - Element set in option value unsupported by module sub-command
80 - Elements set in option value not separated by colon character (``:``)
81 - Option set on unsupported output format (``--long`` or ``--json``)
82 - The above situations apply whether command is called from the terminal or within a modulefile
83
84 - For all these new configuration options
85
86 - accepted value is a list of strings separated by colon character (``:``)
87 - order of elements in the list does not matter
88 - an empty string is a valid value (means only the modulefile name has to be reported)
89
90 - If the ``MODULES_AVAIL_OUTPUT``/``MODULES_AVAIL_TERSE_OUTPUT``,
91 ``MODULES_LIST_OUTPUT``/``MODULES_LIST_TERSE_OUTPUT``,
92 ``MODULES_SPIDER_OUTPUT``/``MODULES_SPIDER_TERSE_OUTPUT`` env vars are
93 wrongly specified
94
95 - Their value is ignored
96 - So the default value takes precedence, unless a ``-o``/``--output`` option is specified
97 - Value in environment variable is wrongly specified for instance in the following situations
98
99 - Element set in option value unsupported by module sub-command
100 - Elements set in option value not separated by colon character (``:``)
101
102 - ``avail_output`` supersedes ``avail_report_dir_sym`` and ``avail_report_mfile_sym`` configurations
103
104 - Enabled ``avail_report_dir_sym`` corresponds to adding ``dirsym`` value to ``avail_output``
105 - Enabled ``avail_report_mfile_sym`` corresponds to adding ``sym`` value to ``avail_output``
106 - Both ``avail_report_dir_sym`` and ``avail_report_mfile_sym`` could be removed safely as:
107
108 - it was not possible to define them at configure time
109 - or change default value with an environment variable
110
111 - Some output content cannot be controlled at the moment with the output options:
112
113 - Hidden modules is exclusively controlled by ``--all`` option to get these modules unveiled
114 - Indepth/no-indepth output is exclusively controlled by ``--no-indepth/--indepth`` and related configuration option
115
116 - When *modulepath* element is removed from an ``avail`` or ``spider``-related option
117
118 - all the modulefiles returned from all searched modulepaths are merged and sorted as a single set
119 - a module appearing in several modulepaths is only reported once
120 - tags or symbols applying to a lower priority module with same name are still reported
121
122 Output key
123 ^^^^^^^^^^
124
125 - An output key is added to print a legend explaining the output
126
127 - Meaning of ``()``, ``{}`` or ``<>`` is explained
128 - Default version is colored specifically
129 - Every tag shortened to a defined abbreviation
130 - Every tag colored specifically
131 - Every variant type set (``variant=value``, ``+boolvariant``, ``-boolvariant``, ``%shortcutvariantvalue``, etc)
132 - Legend entries only concern elements that can be found in reported output
133 - Legend entries are not reported on JSON output mode
134
135 - Output key is enabled by default on ``avail``, ``spider`` and ``list`` sub-command output
136
137 - Key is reported at the end of the output
138 - No key section is reported if no element need to be described (no color, no symbol, no tag, etc)
139
140 - Variant keys are not adapted for ``avail``/``spider`` output
141
142 - Even if all possible values are reported instead of the only one set
143 - Users should be able to understand ``name=val1,val2,...`` corresponds to
144 the ``name=value`` key entry
145 - Same applies to the shortcut variant key
146
147 .. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: