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