PR #696: describe optional third argument to hook.register() function

docs/source/025_new.rst

@@ -1,6 +1,13 @@
 New Features in Lmod
 ====================
 
+**hook.register(<hook_name>, func, <action>)**
+   (Lmod 8.7.25) The hook.register function now takes a optional third
+   argument: action.  The legal actions are the followning strings:
+   "replace", "append", "prepend".  See
+   :ref:`registering_multiple_hook_functions-label` for more details.
+
+
 **/etc/lmod/.modulespath**
    (Lmod 8.7.24) Sites can use /etc/lmod/.modulespath or set
    $LMOD_MODULEPATH_INIT during their site's startup scripts to

docs/source/170_hooks.rst

@@ -193,3 +193,50 @@ SitePackage.lua file one would do::
 
 As you can see you can add text to the beginning and/or the end of the
 text that is generated by avail, spider and list.
+
+.. _registering_multiple_hook_functions-label:
+
+Registering Multiple Hook functions
+-----------------------------------
+
+Lmod 8.7.35+ supports sites registering multiple functions for a
+single hook.  For example a site may wish to register more than one
+load hook.  The function **hook.register()** now takes an optional
+third argument to control how the functions are evaluated.  For
+example::
+
+    local function load_hook_a(t)
+        local frameStk  = require("FrameStk"):singleton()
+        local mt        = frameStk:mt()
+        local simpleName = string.match(t.modFullName, "(.-)/")
+        LmodMessage("Load hook A called on " .. simpleName)
+    end
+
+    local function load_hook_b(t)
+        local frameStk  = require("FrameStk"):singleton()
+        local mt        = frameStk:mt()
+        local simpleName = string.match(t.modFullName, "(.-)/")
+        LmodMessage("Load hook B called on " .. simpleName)
+    end
+
+    hook.register("load", load_hook_a)
+    hook.register("load", load_hook_b) -- overwrites the previous hook, 
+
+    hook.register("load", load_hook_a)
+    hook.register("load", load_hook_b,"replace") -- overwrites the previous hook, 
+
+    -- > the following will run load_hook_a then load_hook_b.
+    hook.register("load", load_hook_a, "append") -- appends to the previous hook
+    hook.register("load", load_hook_b, "append") -- appends to the previous hook
+
+    -- > the following will run load_hook_b then load_hook_a
+    hook.register("load", load_hook_a, "prepend") -- prepends to the previous hook
+    hook.register("load", load_hook_b, "prepend") -- prepends to the previous hook
+
+Note that if the optional third argument (the action argument) causes
+the 2nd call to hook.register to replace the first function.
+
+
+There are some hooks (such as groupName, SiteName, etc) that require
+return values.  The last register hook function will be used to return
+the value.