# module file 函數分類註釋版
★ 是用到過的。

## 子鍊結
[官方說明版抄寫](/qrbpeUVvRuy-Icukm-6rgg)
這個是從官方抄下來後整理的。
[純指令版抄寫](/RGAaP1tVT2GVLsqEwdGf3w)
這個只有指令，刪掉了官方說明。
[分類版抄寫](/u1lERgKTRpqc0slES18hog)
這個給chatgpt分類了。
[分類註釋版](/A9qu7fADR12kMVFc4qZZDQ)
這個附帶我寫的註釋，也就是此文。
## 不在官方教學的函數

★`os.execute("sudo ln -sf " .. gcc_link .. " /usr/bin/gcc")`
執行指令
★`io.stderr:write("GCC 11.4.0 loaded\n")`
輸出到`stderr流`

## 能影響到環境變量的指令

★`prepend_path ("PATH", "/path/to/pkg/bin")`
把值放入環境變量前。

★`prepend_path ("PATH", "/path/to/pkg/bin", "delim")`
能指定分隔字符的 prepend_path，常見的是`:`

`prepend_path {"PATH", "/path/to/pkg/bin", delim="delim", priority=*num*}`
能指定分隔字符和優先權的 prepend_path，使用 {}

`append_path ("PATH", "/path/to/pkg/bin")`
把值放入環境變量後。

`append_path ("PATH", "/path/to/pkg/bin", "delim")`

`append_path {"PATH", "/path/to/pkg/bin", delim="delim", priority=*num*}`

`remove_path ("PATH", "/path/to/pkg/bin")`
把值從環境變量移除。

`remove_path ("PATH", "/path/to/pkg/bin", "delim")`

`setenv ("NAME", "value")`
設定環境變量的值。別用此函數初始化變量，使用prepend_path或append_path。

`pushenv ("NAME", "value")`
與 setenv類似，但當 module file 被 load 時，先前的值被push 到 stack。當 module file被 unload 時，先前儲存的值會是當前的值。

`unsetenv ("NAME")`
重置環境變量。

幫助性指令
★`pathJoin ("/a", "b/c/", "d/")`
字串合成，變為/a/b/c/d。

★`os.getenv ("NAME")`
取得環境變量的值。

`isFile ("name")`
是文件？

`isDir ("name")`
是目錄？

`splitFileName ("name")`
分割目錄，例
local d,f=splitFileName("/a/b/c.ext"). Then d="/a/b", f="c.ext"

## 能影響到 module file 的指令

### 載入 modulefile

★`depends_on ("pkgA", "pkgB", "pkgC")`
當 modulefile 被 load 時，選項也 load。 unload 時，選項也 unload。
如果選項已經是 load 的，則 modulefile unload 時，不會 unload 選項。這是一個獨立的概念。
如果在 load 時， unload 選項，選項仍舊保留。

`depends_on_any("C","D")`
與 depends_on 類似。他先查詢C和D是否load了，有則使用第一個。
若皆無則從左找尋第一個可用的，找到後 load 目標。當 unload 時，目標也會 unload。

`load ("pkgA", "pkgB", "pkgC")`
load 選項。當 unload 時，會強制 unload 所有選項，使用 always_load 是更推薦的，因為一用戶可能用著用著套件就 unload 了。

`always_load ("pkgA", "pkgB", "pkgC")`
load 選項。當 unload 時，不會 unload 選項。

`load_any ("pkgA", "pkgB", "pkgC")`
load 第一個合法的選項，在皆不合法時報錯。當 unload 時，強制所有選項 unload。

`try_load ("pkgA", "pkgB", "pkgC")`
load 選項，但是找不到不報錯。

設定 module file 依賴項

`prereq ("name1", "name2")`
在 load 時，會檢查選項，若選項是 unload 的，則報錯。

`prereq_any ("name1", "name2")`
在 load 時，會檢查選項，如果全部都是 unload 的，則報錯

`conflict ("name1", "name2")`
當選項是 load 時，退出。

★`family ("name")`
實現階乘modulefile的重要函數。只能有一個 "name" 被 load。常用在字串"MPI"和"Compiler"，因為使用不同的MPI或compiler的套件理論上不兼容。

### mofulefile 版本限制

`atleast ("name", "version")`
版本>=version。

`between ("name", "v1", "v2")`
v1<=版本<=v2

`between ("name", "v1<", "<v2")`
v1<版本\<v2

`latest ("name")`
是系統上最新的版本。

`atmost ("name","version")`
版本<=version

### modulefile 可用性

`isloaded ("NAME")`
若"NAME"是loaded時，返回true，否則false。

`isAvail ("NAME")`
若"NAME"是可使用的時，返回true，否則false。

### 雜西雜八

`os.exit(number)`
離開當前文件，所有對環境變量的更改會取消。

`capture ("string")`
執行 "string" 然後捕獲返回值
例如:
local nprocs = capture("nprocs"):gsub("\n$","")

`subprocess ("string")`
執行 "string" 然後捕獲返回值，可能有'\n'，你需要自己處理。

## 一些常數
ex: 假設目前的module file 是 `某個$(MODULE_PATH)/gcc/1.1.1.lua`
`myModuleName ()` gcc
`myModuleVersion ()` 1.1.1
`myModuleFullName ()` gcc/1.1.1
`myModuleUsrName ()` gcc/1.1.1或gcc或1.1.1 (?)
`myFileName ()` 絕對路徑
`myShellName ()` bash
`myShellType ()` sh
`hierarchyA ("fullName", level)` 沒用過
`extensions ("numpy/2.1, scipy/3.2, foo/1.3")` 沒用過
`LmodVersion ()` lmod的版本
★`mode ()` 當前module file的狀態字串，能是 "load" 或 "unload" 或 "spider"

### 幫助文字或字串輸出
★`whatis ("STRING")`
當使用 `module whatis modulefile` 時，輸出所有的whatis函數的內容。一個whatis函數代表一行。
★`help ([[ help string ]])`
當使用 `module help modulefile` 時，輸出所有help函數的內容。一個help函數代表一行。
`LmodMessage ("string", …)`
輸出給 user
`LmodWarning ("string", …)`
輸出warning給 user
`LmodError ("string", "…")`
輸出error給 user，然後退出。

### 數學
`math.floor ()`
`math.ceil ()`
`math.max ()`
`math.min ()`

### 不想講的函數

三個來自 lua 的函數
require ()
loadfile ()
loadstring ()


requireFullName ()
inherit ()
isPending ("NAME")
convertToCanonical ("string")
execute {cmd="<any command>", modeA={"load"}}
haveDynamicMPATH ()
complete ("shellName","name","args")

add_property ("NAME", "value")
remove_property ("NAME", "value")

source_sh ("shellName","shell_script arg1 …")
LmodBreak (msg)
userInGroups ("group1", "group2", …)
mgrload (required, active_object)
set_alias ("name", "value")

### 題外化: 自動補全代碼資源

GNU Bash Manual - Programmable Completion
經典GNU風格
https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html

Bash Completion Cheat Sheet
看起來很精美的網站
https://devhints.io/bash

Bash Programmable Completion HOWTO：
經典死人風格教學
https://tldp.org/LDP/abs/html/tabexpansion.html

Spack 官方文件 - Shell Support：
看起來有點難
https://spack.readthedocs.io/en/latest/getting_started.html#shell-support

bash-completion GitHub 項目：
https://github.com/scop/bash-completion