doc: desc. --user/--group options to module-{hide,forbid,tag}

Author: xdelaruelle

.hunspell.en.dic

@@ -1155,3 +1155,6 @@ isEnvVarDefined
 envVarEquals
 setEnvVarIfUndefined
 LMSTICKYRULE
+Chardon
+Jérémy
+Déchard

NEWS.rst

@@ -153,6 +153,14 @@ Modules 5.4.0 (not yet released)
   #503)
 * Init: Improve Tcsh shell completion script to complete against existing
   files when pattern starts with ``/``, ``.`` or ``~/``. (fix issue #523)
+* Add ``--user`` option to :mfcmd:`module-forbid`, :mfcmd:`module-hide` and
+  :mfcmd:`module-tag` modulefile commands to forbid, hide or tag only if user
+  is listed in the value of this new option. (fix issue #520 with contribution
+  from Jérémy Déchard)
+* Add ``--group`` option to :mfcmd:`module-forbid`, :mfcmd:`module-hide` and
+  :mfcmd:`module-tag` modulefile commands to forbid, hide or tag only if one
+  user's group is listed in the value of this new option. (fix issue #520 with
+  contribution from Jérémy Déchard)
 
 
 .. _5.3 release notes:

doc/source/changes.rst

@@ -1075,6 +1075,7 @@ The following modulefile Tcl commands appeared on Modules 5.
  * module specification on which stickiness applies is recorded in loaded
    environment to determine if it is still satisfied when updating
    environment.
+ * options ``--user`` and ``--group`` are added.
 
 :mfcmd:`break`
 

doc/source/design/hide-or-forbid-modulefile.rst

@@ -225,13 +225,17 @@ Specification
   - ``--hard``: highest hiding level
   - ``--not-user``: specify a list of users unaffected by hide mechanism
   - ``--not-group``: specify a list of groups whose member are unaffected by hide mechanism
+  - ``--user``: specify a list of users specifically affected by hide mechanism
+  - ``--group``: specify a list of groups whose member are specifically affected by hide mechanism
   - ``--before``: enables hide mechanism until a given date
   - ``--after``: enables hide mechanism after a given date
 
 - ``module-forbid`` accepts options that change its behavior:
 
   - ``--not-user``: specify a list of users unaffected by forbid mechanism
   - ``--not-group``: specify a list of groups whose member are unaffected by forbid mechanism
+  - ``--user``: specify a list of users specifically affected by forbid mechanism
+  - ``--group``: specify a list of groups whose member are specifically affected by forbid mechanism
   - ``--before``: enables forbid mechanism until a given date
   - ``--after``: enables forbid mechanism after a given date
   - ``--message``: supplements error message obtained when trying to evaluate a forbidden module with given text message
@@ -259,12 +263,16 @@ Specification
 
       - Unless on very specific cases, where a global rc file defines these hidden/forbidden commands for the full path modules
 
-- ``--not-user`` and ``--not-group`` specification is only supported on Unix platform
+- ``--user``, ``--group``, ``--not-user`` and ``--not-group`` specification is only supported on Unix platform
 
-  - These 2 options raise an error when used on Windows platform
+  - These options raise an error when used on Windows platform
   - In which case relative ``module-hide`` or ``module-forbid`` command is made ineffective as well as remaining content of the modulerc script hosting them
   - Error message is clearly seen when trying to load related modules and indicate where to find the erroneous command
 
+- ``--user`` and ``--group`` options prevail over ``--not-user`` and ``--not-group`` options
+
+  - When ``--user`` or ``--group`` is set, exclusion list from ``--not-user`` and ``--not-group`` are ignored
+
 - ``--before`` and ``--after`` are also supported by ``module-hide`` to phase-out modules prior to forbid their evaluation
 
 - ``--before`` and ``--after`` accept a date time as value

doc/source/design/module-tags.rst

@@ -83,13 +83,19 @@ Defining
 
   - ``--not-user``: specify a list of users unaffected by specified tagging
   - ``--not-group``: specify a list of groups whose member are unaffected by specified tagging
+  - ``--user``: specify a list of users specifically affected by specified tagging
+  - ``--group``: specify a list of groups whose member are specifically affected by specified tagging
 
-- ``--not-user`` and ``--not-group`` specification is only supported on Unix platform
+- ``--user``, ``--group``, ``--not-user`` and ``--not-group`` specification is only supported on Unix platform
 
-  - These 2 options raise an error when used on Windows platform
+  - These options raise an error when used on Windows platform
   - In which case relative ``module-tag`` command is made ineffective as well as remaining content of the modulerc script hosting them
   - Error message is clearly seen when trying to load related modules and indicate where to find the erroneous command
 
+- ``--user`` and ``--group`` options prevail over ``--not-user`` and ``--not-group`` options
+
+  - When ``--user`` or ``--group`` is set, exclusion list from ``--not-user`` and ``--not-group`` are ignored
+
 - ``module-tag`` is intended to be used in modulerc files
 
   - to be easily fetched during ``avail`` sub-command processing

doc/source/modulefile.rst

@@ -470,6 +470,8 @@ the *modulefile* is being loaded.
  * ``--before datetime``
  * ``--not-user {user...}``
  * ``--not-group {group...}``
+ * ``--user {user...}``
+ * ``--group {group...}``
  * ``--message {text message}``
  * ``--nearly-message {text message}``
 
@@ -487,6 +489,14 @@ the *modulefile* is being loaded.
  specified. When both options are set, forbidding is not applied if a match is
  found for ``--not-user`` or ``--not-group``.
 
+ If ``--user`` option is set, forbidding is applied only if the username of
+ the user currently running :file:`modulecmd.tcl` is part of the list of
+ username specified. Following the same approach, if ``--group`` option is
+ set, forbidding is applied only if current user is member of one the group
+ specified. When both options are set, forbidding is applied if a match is
+ found for ``--user`` or ``--group``. These two options prevail over
+ ``--not-user`` and ``--not-group`` options.
+
  Error message returned when trying to evaluate a forbidden module can be
  supplemented with the *text message* set through ``--message`` option.
 
@@ -521,6 +531,9 @@ the *modulefile* is being loaded.
     .. versionchanged:: 5.4
        Full path file name may be used to designate *modulefile*
 
+    .. versionchanged:: 5.4
+       Options ``--user`` and ``--group`` added
+
 .. mfcmd:: module-hide [options] modulefile...
 
  Hide *modulefile* to exclude it from available module search or module
@@ -535,6 +548,8 @@ the *modulefile* is being loaded.
  * ``--before datetime``
  * ``--not-user {user...}``
  * ``--not-group {group...}``
+ * ``--user {user...}``
+ * ``--group {group...}``
 
  When ``--soft`` option is set, *modulefile* is also set hidden, but hiding is
  disabled when search or selection query's root name matches module's root
@@ -569,6 +584,14 @@ the *modulefile* is being loaded.
  When both options are set, hiding is not applied if a match is found for
  ``--not-user`` or ``--not-group``.
 
+ If ``--user`` option is set, hiding is applied only if the username of the
+ user currently running :file:`modulecmd.tcl` is part of the list of username
+ specified. Following the same approach, if ``--group`` option is set, hiding
+ is applied only if current user is member of one the group specified. When
+ both options are set, hiding is applied if a match is found for ``--user`` or
+ ``--group``. These two options prevail over ``--not-user`` and
+ ``--not-group`` options.
+
  If the :option:`--all` option is set on :subcmd:`avail`, :subcmd:`aliases`,
  :subcmd:`whatis` or :subcmd:`search` sub-commands, hiding is disabled thus
  hidden modulefiles are included in module search. Hard-hidden modules (i.e.,
@@ -611,6 +634,9 @@ the *modulefile* is being loaded.
     .. versionchanged:: 5.4
        Full path file name may be used to designate *modulefile*
 
+    .. versionchanged:: 5.4
+       Options ``--user`` and ``--group`` added
+
 .. mfcmd:: module-info option [info-args]
 
  Provide information about the :file:`modulecmd.tcl` program's state. Some of
@@ -786,6 +812,8 @@ the *modulefile* is being loaded.
 
  * ``--not-user {user...}``
  * ``--not-group {group...}``
+ * ``--user {user...}``
+ * ``--group {group...}``
 
  If ``--not-user`` option is set, the tag is not applied if the username of
  the user currently running :file:`modulecmd.tcl` is part of the list of
@@ -794,6 +822,14 @@ the *modulefile* is being loaded.
  specified. When both options are set, the tag is not applied if a match is
  found for ``--not-user`` or ``--not-group``.
 
+ If ``--user`` option is set, the tag is applied only if the username of the
+ user currently running :file:`modulecmd.tcl` is part of the list of username
+ specified. Following the same approach, if ``--group`` option is set, the tag
+ is applied only if current user is member of one the group specified. When
+ both options are set, the tag is applied if a match is found for ``--user``
+ or ``--group``. These two options prevail over ``--not-user`` and
+ ``--not-group`` options.
+
  The parameter *modulefile* may also be a symbolic modulefile name or a
  modulefile alias. It may also leverage a specific syntax to finely select
  module version (see `Advanced module version specifiers`_ section below).
@@ -822,6 +858,9 @@ the *modulefile* is being loaded.
     .. versionchanged:: 5.4
        Full path file name may be used to designate *modulefile*
 
+    .. versionchanged:: 5.4
+       Options ``--user`` and ``--group`` added
+
 .. mfcmd:: module-version modulefile version-name...
 
  Assigns the symbolic *version-name* to the *modulefile*. This command