.. _module-selection-contexts:

Module selection contexts
=========================

Description of the different contexts where a module is expressed to get resolved to modulefiles.

.. _module_identification_to_select_one_module:

Module identification to select one module
------------------------------------------

- specification expresses exactly one module
- must qualify version to select in case a module has multiple versions
- expression may

  - be absolute like *mod/version*
  - be relative to the modulefile currently being evaluated like *./version* or */version*
  - refer to symbolic version or module alias

- specification used to resolve argument passed to the following commands:

  - ``module-version``
  - ``module-alias``
  - ``module-virtual`` (cannot use symbolic version or module alias, should define an actual module)
  - ``module-info symbols``
  - ``module-info version``
  - ``module-info loaded``

- relies on ``getModuleNameVersion`` procedure to get absolute name

.. _module_version_specification_to_return_all_matching_modules:

Module version specification to return all matching modules
-----------------------------------------------------------

- specification expresses one or multiple modules
- expression may

  - be absolute like *mod/version*
  - refer to implicit or explicitly defined default version like *mod*
  - refer to extended default version like *mod/1* (to refer to *mod/1.1.1*)
  - refer to symbolic version or module alias
  - specify multiple versions as list (*mod@1,2*) or range (*mod@:1* or *mod@1:2*)
  - refer to a variant specification (with or without a module name specification)

- all modules matching specification are retrieved with ``getModules``
- specification used to resolve argument passed to the following commands:

  - ``avail``
  - ``spider``
  - ``paths``
  - ``whatis``
  - ``list`` (matching specification retrieved from loaded modules, not ``getModules``)

- used to get all alias and symbolic version of loaded modules treated by:

  - ``list``

- used to get all existing aliases and symbolic version (no module specification) by:

  - ``aliases``

- used to get all existing modulefiles (no module specification) by:

  - ``search``

.. _module_version_specification_to_select_one_module:

Module version specification to select one module
-------------------------------------------------

- specification expresses one or multiple modules
- relies on the module version specification to return all matching modules
- then among matching modules, one is selected with ``getPathToModule``:

  - the one set has the default version (also called the explicit default version)
  - or the highest version in case no explicit default is found among results (also called the implicit default version)
  - nothing is returned in case no explicit default is found among matching modules and implicit default version mechanism is disabled

- module selection may trigger another match retrieval

  - for instance in case selection leads to an alias that resolves to a bare module name

- specification used to resolve argument passed to the following commands:

  - ``load``
  - ``unload`` (with attempt to match against loaded modules to resolve argument)
  - ``switch``
  - ``help``
  - ``test``
  - ``display``
  - ``path``
  - ``is-avail``

- used to resolve aliases or symbolic versions treated by following commands:

  - ``paths``
  - ``search``

.. _module_version_specification_to_check_compatibility:

Module version specification to check compatibility
---------------------------------------------------

- specification expresses one or multiple modules
- expression may

  - be absolute like *mod/version*
  - refer to implicit or explicitly defined default version like *mod*
  - refer to extended default version like *mod/1* (to refer to *mod/1.1.1*)
  - refer to symbolic version or module alias
  - specify multiple versions as list (*mod@1,2*) or range (*mod@:1* or *mod@1:2*)

- version specification is matched against loaded or loading modules with variety of procedures:

  - ``getLoadedMatchingName``
  - ``getLoadedWithClosestName``
  - ``isModuleEvaluated``

- specification used to resolve argument passed to the following commands:

  - ``is-loaded``
  - ``info-loaded``
  - ``prereq``
  - ``conflict``

- for prereq command when version specification does not have a match among loaded or loading modules

  - version specification is used to select one module per module specification
  - for instance ``prereq mod@:1.8 mod@1.10`` triggers load tentative of default version among *mod@:1.8* then if this tentative fails load of *mod@1.10* is attempted
  - another example with ``prereq mod mod@1.10``, which triggers load tentative of *mod/default* then if it fails load of mod@1.10 is attempted

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