Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .hunspell.en.dic
Original file line number Diff line number Diff line change
Expand Up @@ -753,6 +753,7 @@ readModuleContent
readline
readlink
repo
reindex
reportError
reportUsage
reportWarning
Expand Down
2 changes: 2 additions & 0 deletions INSTALL.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2019,6 +2019,8 @@ installation.
| :mconfig:`sticky_purge` | ``error`` | :instopt:`--with-sticky-purge`, | | |
| | | :envvar:`MODULES_STICKY_PURGE` | | |
+-----------------------------------+----------------------------------------------+----------------------------------------------+--------------+-----------+
| :mconfig:`subcmd_alias` | *Empty by default* | :envvar:`MODULES_SUBCMD_ALIAS` | | |
+-----------------------------------+----------------------------------------------+----------------------------------------------+--------------+-----------+
| :mconfig:`tag_abbrev` | auto-loaded=aL:loaded=L:hidden=H:\ | :instopt:`--with-tag-abbrev`, | | |
| | hidden-loaded=H:forbidden=F:nearly-\ | :envvar:`MODULES_TAG_ABBREV` | | |
| | forbidden=nF:sticky=S:super-sticky=sS:\ | | | |
Expand Down
40 changes: 40 additions & 0 deletions MIGRATING.rst
Original file line number Diff line number Diff line change
Expand Up @@ -158,6 +158,46 @@ meantime.
:mfcmd:`umask` applies to the shells and scripting languages that are able to
change their own mask. See the :ref:`Shell support` section for details.

Defining sub-command aliases
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

People using several tools side by side may expect the same action to bear
the same name in each of them. The :mconfig:`subcmd_alias` configuration
option is introduced to define additional names for the sub-commands of the
:command:`module` and :command:`ml` commands. Its value is a colon-separated
list of ``alias=target`` definitions.

.. parsed-literal::

:ps:`$` module config subcmd_alias find=avail:loaded=list
:ps:`$` module find -t foo
/path/to/modulefiles:
foo/1.0
foo/2.0
:ps:`$` ml loaded
No Modulefiles Currently Loaded.

An alias may bear the name of an existing sub-command, which is then
shadowed. Alias target is always a sub-command of :command:`module`, never
another alias: in the following example ``find`` still designates
:subcmd:`avail`.

.. parsed-literal::

:ps:`$` module config subcmd_alias find=avail:avail=spider

Defined aliases are listed at the end of the :subcmd:`module help<help>`
usage message and are completed like the sub-command they designate. Aliases
apply to the command line only: :mfcmd:`module` commands written in
modulefiles are not affected.

When the configuration option is changed from its default value using the
:subcmd:`config` sub-command, the :envvar:`MODULES_SUBCMD_ALIAS` environment
variable is defined accordingly. See the :envvar:`MODULES_SUBCMD_ALIAS`
description for details and the :ref:`spack-like-sub-command-names` cookbook
recipe for a complete example that maps the command names of the Spack
package manager.


v5.7
----
Expand Down
6 changes: 6 additions & 0 deletions NEWS.rst
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,12 @@ Modules 5.8.0 (not yet released)
modulefile command. (fix issue #532)
* Fix :command:`ml` command to correctly call a sub-command when command
line switches like :option:`--tag` are set before the sub-command name.
* Add the :mconfig:`subcmd_alias` configuration option to define aliases for
module sub-commands. An alias may shadow an existing sub-command and always
designates a sub-command, never another alias. Defined aliases are reported
on usage message and handled by shell completion. When set, the
:envvar:`MODULES_SUBCMD_ALIAS` environment variable supersedes the option
value. (fix issue #712)


.. _5.7 release notes:
Expand Down
4 changes: 2 additions & 2 deletions doc/source/changes.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1162,7 +1162,7 @@ The following environment variables appeared on Modules 5.
| | :envvar:`MODULES_SPIDER_JSON_OUTPUT`, |
| | :envvar:`__MODULES_PRIORITY_\<VAR\>`, |
| | :envvar:`MODULES_FAMILY_\<NAME\>_VERSION`, |
| | :envvar:`__MODULES_UMASK` |
| | :envvar:`__MODULES_UMASK`, :envvar:`MODULES_SUBCMD_ALIAS` |
+------------+-----------------------------------------------------------------+

Modules Specific Tcl Commands
Expand Down Expand Up @@ -1400,7 +1400,7 @@ The following Modules configuration option has been introduced on Modules 5.
| | :mconfig:`ignore_cache_subcmds` |
+------------+-----------------------------------------------------------------+
| 5.8 | :mconfig:`avail_json_output`, :mconfig:`list_json_output`, |
| | :mconfig:`spider_json_output` |
| | :mconfig:`spider_json_output`, :mconfig:`subcmd_alias` |
+------------+-----------------------------------------------------------------+

:mconfig:`auto_handling`
Expand Down
159 changes: 159 additions & 0 deletions doc/source/cookbook/spack-like-sub-command-names.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,159 @@
.. _spack-like-sub-command-names:

Spack-like sub-command names
============================

People using both Modules and the `Spack`_ package manager regularly type the
command name of one tool when using the other. For instance ``spack find``
lists the installed packages and ``spack list`` the packages that could be
installed, whereas ``module avail`` lists the available modulefiles and
``module list`` the loaded ones.

This recipe describes how to make the :command:`module` command understand
the command names of Spack.

.. _Spack: https://spack.io/

Implementation
--------------

Starting version 5.8, the :mconfig:`subcmd_alias` configuration option defines
additional names for module sub-commands. Its value is a colon-separated list
of ``alias=target`` definitions.

Following table lists the Spack commands that have an equivalent among module
sub-commands and the alias definition required, if any, to make
:command:`module` accept the Spack name.

+---------------------+-------------------------------+-------------------------+
| Spack command | Module sub-command | Alias definition |
+=====================+===============================+=========================+
| ``spack load`` | :subcmd:`load` | *Same name* |
+---------------------+-------------------------------+-------------------------+
| ``spack unload`` | :subcmd:`unload` | *Same name* |
+---------------------+-------------------------------+-------------------------+
| ``spack find`` | :subcmd:`avail` | ``find=avail`` |
+---------------------+-------------------------------+-------------------------+
| ``spack list`` | :subcmd:`spider` | ``list=spider`` |
+---------------------+-------------------------------+-------------------------+
| ``spack versions`` | :subcmd:`avail` | ``versions=avail`` |
+---------------------+-------------------------------+-------------------------+
| ``spack info`` | :subcmd:`help` | ``info=help`` |
+---------------------+-------------------------------+-------------------------+
| ``spack spec`` | :subcmd:`display` | ``spec=display`` |
+---------------------+-------------------------------+-------------------------+
| ``spack location`` | :subcmd:`path` | ``location=path`` |
+---------------------+-------------------------------+-------------------------+
| ``spack edit`` | :subcmd:`edit` | *Same name* |
+---------------------+-------------------------------+-------------------------+
| ``spack test`` | :subcmd:`test` | *Same name* |
+---------------------+-------------------------------+-------------------------+
| ``spack audit`` | :subcmd:`lint` | ``audit=lint`` |
+---------------------+-------------------------------+-------------------------+
| ``spack reindex`` | :subcmd:`cachebuild` | ``reindex=cachebuild`` |
+---------------------+-------------------------------+-------------------------+
| ``spack clean`` | :subcmd:`cacheclear` | ``clean=cacheclear`` |
+---------------------+-------------------------------+-------------------------+
| ``spack config`` | :subcmd:`config` | *Same name* |
+---------------------+-------------------------------+-------------------------+
| ``spack commands`` | :subcmd:`help` | ``commands=help`` |
+---------------------+-------------------------------+-------------------------+
| ``spack help`` | :subcmd:`help` | *Same name* |
+---------------------+-------------------------------+-------------------------+

An installed package in Spack corresponds to a modulefile available in the
enabled modulepaths. The packages Spack knows and could install correspond to
the modulefiles found by :subcmd:`spider` in all the modulepaths, including
those that are not enabled yet.

The ``list`` alias bears the name of an existing sub-command: it shadows the
:subcmd:`list` sub-command that reports the loaded modulefiles. Spack has no
dedicated command for this, as loaded packages are reported with
``spack find --loaded``. Loaded modulefiles are still obtained with the
:command:`ml` command without argument or with an abbreviation of the
shadowed sub-command, as aliases do not apply to abbreviations. An additional alias may also be defined for this purpose, like
``loaded=list``.

.. note:: Alias target is always a sub-command of :command:`module` and never
another alias. The ``find=avail`` definition designates the
:subcmd:`avail` sub-command, and would still do if an alias named
``avail`` was also defined.

Spack commands that install, build or describe the dependency graph of
packages (``install``, ``uninstall``, ``graph``, ``dependencies``, etc) have
no equivalent, as Modules does not build software. Commands made of several
words, like ``spack env activate``, cannot be mapped either: an alias only
stands for the sub-command name.

**Compatible with Modules v5.8+**

Installation
------------

To define these aliases for all users, set the configuration option in the
:file:`initrc` configuration file, which is located in the configuration
directory designated by the :instopt:`--etcdir` installation option.

.. code-block:: none
:caption: initrc

#%Module
module config subcmd_alias find=avail:list=spider:info=help:spec=display:location=path:versions=avail:commands=help:audit=lint:reindex=cachebuild:clean=cacheclear

A user may define them on its own by running the same :subcmd:`config`
sub-command in a shell session or by setting the
:envvar:`MODULES_SUBCMD_ALIAS` environment variable in its shell startup
files.

.. parsed-literal::

:ps:`$` module config subcmd_alias find=avail:list=spider:info=help:spec=display:location=path:versions=avail:commands=help:audit=lint:reindex=cachebuild:clean=cacheclear

When aliases are defined site-wide, a user may add its own definitions or
withdraw some of the site by prefixing the value with ``+`` or ``-``. For
instance to get a ``loaded`` alias in addition to those defined above:

.. parsed-literal::

:ps:`$` module config subcmd_alias +loaded=list

Usage example
-------------

With the above configuration set, the Spack command names are accepted by the
:command:`module` and :command:`ml` commands and are completed like the
sub-command they designate:

.. parsed-literal::

:ps:`$` module find -t foo
/path/to/modulefiles:
foo/1.0
foo/2.0
:ps:`$` module load foo/2.0
:ps:`$` module location foo/2.0
/path/to/modulefiles/foo/2.0
:ps:`$` module loaded
Currently Loaded Modulefiles:
1) foo/2.0

Defined aliases are reported at the end of the usage message:

.. parsed-literal::

:ps:`$` module help
...
Sub-command aliases:
audit Alias for 'lint' sub-command
clean Alias for 'cacheclear' sub-command
commands Alias for 'help' sub-command
find Alias for 'avail' sub-command
info Alias for 'help' sub-command
list Alias for 'spider' sub-command
loaded Alias for 'list' sub-command
location Alias for 'path' sub-command
reindex Alias for 'cachebuild' sub-command
spec Alias for 'display' sub-command
versions Alias for 'avail' sub-command

.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent:
131 changes: 131 additions & 0 deletions doc/source/design/subcmd-alias.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
.. _subcmd-alias:

Sub-command aliases
===================

This design document describes the :mconfig:`subcmd_alias` configuration
option that defines additional names for the sub-commands of the
:command:`module` command.

Configuration
-------------

- :mconfig:`subcmd_alias` configuration option

- Colon-separated list of ``alias=target`` definitions
- Empty by default, no installation option
- Superseded by the :envvar:`MODULES_SUBCMD_ALIAS` environment variable
- As a list option, elements may be appended or subtracted with the ``+``
and ``-`` prefixes of the :subcmd:`config` sub-command. A user is this way
able to adapt the definitions made site-wide in :file:`initrc`.

Definition validity
-------------------

A definition is taken into account if:

- it is made of exactly one alias name and one target separated by an equal
sign
- alias name is composed of letters, digits, underscore and hyphen-minus
characters and does not start with an hyphen-minus
- alias name is not ``ml``, which is not a sub-command but a way to call the
:command:`ml` command through :file:`modulecmd.tcl`
- target is a sub-command, designated by its name, one of its predefined
aliases (e.g., ``add``) or abbreviations (e.g., ``av``)

Other definitions are silently ignored, like done for the other configuration
options holding a list of definitions. When an alias is defined several times,
last definition applies.

The character set allowed for alias names is restricted on purpose. Alias
names are consumed by the shell completion scripts, where candidate words go
through constructs that expand them. Restricting names to characters that have
no special meaning for the supported shells guarantees that the content of an
environment variable cannot be evaluated as shell code.

Value reported by :subcmd:`config` sub-command is the list of the valid
definitions, in definition order, with target expressed as the sub-command
name it resolves to.

Resolution
----------

Sub-command name resolution is a two-step process:

1. if the name matches an alias defined in :mconfig:`subcmd_alias`, it is
replaced by the alias target
2. the result is resolved as before among the sub-command names, their
predefined aliases and abbreviations

First step is applied once and its result is never passed through it again.
This leads to the following properties:

- An alias always designates a sub-command, never another alias. Definitions
cannot be chained and cannot loop. With ``find=avail:avail=spider``,
``find`` designates :subcmd:`avail`.
- An alias may bear the name of a sub-command, of a predefined alias or of an
abbreviation. This name is then shadowed: it designates the alias target.
Two names may be swapped (``avail=list:list=avail``).
- Alias match is exact. An alias cannot be abbreviated, and the abbreviations
of a shadowed sub-command still designate this sub-command.

No sub-command name is protected against shadowing. If a definition makes
:subcmd:`config` unreachable, unsetting :envvar:`MODULES_SUBCMD_ALIAS` gives
back access to it.

Scope
-----

Aliases apply to the sub-command name set on the command line of the
:command:`module` and :command:`ml` commands. Translation occurs when the
command line is parsed, before any other processing. As a result everything
that depends on the sub-command name behaves as if the target name was typed:
command-line switch parsing, pager activation, result of
:mfcmd:`module-info command<module-info>`, logged event, configuration options
whose value is a list of sub-command names, etc.

With :command:`ml`, the word that may be an alias is the first argument that
is not a command-line switch. An alias name takes precedence over a module of
the same name, like sub-command names do.

Aliases do not apply to the :mfcmd:`module` command evaluated in modulefiles,
run-command files, initialization rc files or sourced script files. What a
modulefile does must not depend on the aliases defined by the user who loads
it, especially as an alias may shadow a sub-command.

Reporting
---------

Defined aliases are listed, sorted by name, in a dedicated section at the end
of the usage message returned by :subcmd:`help` sub-command without argument
and :option:`--help` option. This section is omitted when no alias is defined.

Shell completion
----------------

Completion scripts read :envvar:`MODULES_SUBCMD_ALIAS` to:

- propose alias names among the sub-command candidates
- translate the sub-command word into its target prior selecting the kind of
candidates to return

Definitions are filtered with the same character set rule than the
:command:`module` command. Target is not checked against the list of
sub-commands: an unknown target just leads to no specific completion.

bash, zsh and fish scripts read the environment variable each time completion
is triggered. tcsh completion relies on static rules: alias rules are
generated from the rule of their target when the completion script is sourced.
Aliases defined afterward in a tcsh session are not completed until this
script is sourced again.

Completion scripts call :command:`module` to fetch candidates (available
modules, loaded modules, collections). :envvar:`MODULES_SUBCMD_ALIAS` is
cleared for these calls to get the expected result even if the name of the
called sub-command is shadowed.

The value set in :file:`initrc` during initialization is exported in
:envvar:`MODULES_SUBCMD_ALIAS`, which makes site-wide definitions visible to
completion scripts.

.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent:
Loading
Loading