Erlang shell。

shell 是一個使用者介面程式，用於輸入運算式序列。這些運算式會被求值並返回一個值。shell 提供類似 Emacs 的快捷鍵組合來編輯目前行的文字。如需所有可用快捷鍵的列表，請參閱 ERTS 使用者指南中的 tty - 命令列介面。您也可以變更快捷鍵以更符合您的偏好，請參閱 edlin - shell 中的行編輯器。

歷史機制會儲存先前的指令及其值，之後可以在指令中使用這些資訊。要儲存多少指令和結果可以由使用者決定，可以互動式地透過呼叫 history/1 和 results/1，或設定 STDLIB 應用程式的應用程式組態參數 shell_history_length 和 shell_saved_results 來決定。透過設定 Kernel 應用程式的應用程式組態參數 shell_history，shell 歷史記錄可以儲存到磁碟中。

shell 使用輔助程序來評估指令，以保護歷史機制免受例外情況的影響。預設情況下，當發生例外情況時，評估程序會被終止，但可以透過呼叫 catch_exception/1 或設定 STDLIB 應用程式的應用程式組態參數 shell_catch_exception 來變更此行為。另請參閱下面的範例。

在使用者運算式中產生的變數綁定和本機程序字典變更會被保留，並且這些變數可以在後續指令中用來存取它們的值。這些綁定也可以被遺忘，以便這些變數可以重複使用。

特殊的 shell 指令都具有 (本機) 函數呼叫的語法。它們會被評估為一般的函數呼叫，並且可以在一個運算式序列中使用多個指令。

如果 shell 無法識別某個指令 (本機函數呼叫)，則會先嘗試在模組 user_default 中尋找該函數，您可以在其中放置自訂的本機指令。如果找到，則會評估該函數，否則會嘗試在模組 shell_default 中評估該函數。必須明確載入模組 user_default。

shell 也允許使用者啟動多個並行作業。一個作業可以視為一組可以與 shell 通訊的程序。

shell 中有一些對讀取和列印記錄的支援。在編譯期間，記錄運算式會被轉換為元組運算式。在執行階段，不知道元組是否表示記錄，並且編譯器使用的記錄定義在執行階段不可用。因此，為了讀取記錄語法並在可能時將元組列印為記錄，記錄定義必須由 shell 本身維護。

下面說明用於讀取、定義、遺忘、列出和列印記錄的 shell 指令。請注意，每個作業都有自己的一組記錄定義。為了方便起見，每次啟動新作業時都會讀取模組 shell_default 和 user_default (如果已載入) 中的記錄定義。例如，將以下行新增到 user_default 會使 file_info 的定義在 shell 中隨時可用

-include_lib("kernel/include/file.hrl").

shell 在兩種模式下執行

• 一般 (可能受限) 模式，可以在其中編輯指令並評估運算式
• 作業控制模式，JCL，可以在其中啟動、終止、分離和連接作業

只有目前連接的作業可以與 shell 「交談」。

Shell 指令

以下指令是始終可用的內建 shell 指令。在大多數系統中，c 模組中列出的指令也可以在 shell 中使用。

• b() - 列印目前的變數綁定。

• f() - 移除所有變數綁定。

• f(X) - 移除變數 X 的綁定。

  注意

  如果變數綁定中儲存了很大的值，您必須同時呼叫 f(X) 和呼叫 history(0) 或 results(0) 以釋放該記憶體。

• h() - 列印歷史記錄清單。

• history(N) - 將歷史記錄清單中要保留的先前指令數設定為 N。傳回先前的數字。預設值為 20。

• results(N) - 將歷史記錄清單中要保留的先前指令結果數設定為 N。傳回先前的數字。預設值為 20。

• e(N) - 重複指令 N，如果 N 為正數。如果為負數，則會重複第 N 個先前的指令 (也就是說，e(-1) 會重複先前的指令)。

• v(N) - 在目前的指令中使用指令 N 的傳回值，如果 N 為正數。如果為負數，則會使用第 N 個先前指令的傳回值 (也就是說，v(-1) 會使用先前指令的值)。

• help() - 評估 shell_default:help()。

• h(Module, Function) - 如果可用，則在 shell 中列印 Module:Function 的文件。

• ht(Module, Type) - 如果可用，則在 shell 中列印 Module:Type 的文件。

• hcb(Module, Callback) - 如果可用，則在 shell 中列印 Module:Callback 的文件。

• c(Mod) - 評估 shell_default:c(Mod)。這會編譯和載入模組 Mod，並在必要時清除舊版本的程式碼。Mod 可以是模組名稱或來源檔案路徑，有或沒有 .erl 副檔名。

• catch_exception(Bool) - 設定評估程序的例外處理。傳回先前的例外處理。預設值 (false) 是在發生例外情況時終止評估程序，這會導致 shell 建立新的評估程序。當例外處理設定為 true 時，評估程序會繼續執行。這表示，例如，連接到評估程序的連接埠和 ETS 表格以及程序會在例外情況中存留。

• rd(RecordName, RecordDefinition) - 在 shell 中定義記錄。RecordName 是一個原子，而 RecordDefinition 列出欄位名稱和預設值。通常透過使用下面說明的 rr/1,2,3 指令來讓 shell 知道記錄定義，但有時在執行時定義記錄會很方便。

• rf() - 移除所有記錄定義，然後從模組 shell_default 和 user_default (如果已載入) 讀取記錄定義。傳回已定義記錄的名稱。

• rf(RecordNames) - 移除選取的記錄定義。RecordNames 是一個記錄名稱或記錄名稱清單。若要移除所有記錄定義，請使用 '_'。

• rl() - 列印所有記錄定義。

• rl(RecordNames) - 列印選取的記錄定義。RecordNames 是一個記錄名稱或記錄名稱清單。

• rp(Term) - 使用 shell 已知的記錄定義列印術語。列印所有 Term；深度不受限制，就像列印傳回值時一樣。

• rr(Module) - 從模組的 BEAM 檔案讀取記錄定義。如果 BEAM 檔案中沒有記錄定義，則會改為尋找並讀取來源檔案。傳回已讀取記錄定義的名稱。Module 是一個原子。

• rr(Wildcard) - 從檔案讀取記錄定義。取代讀取之任何記錄名稱的現有定義。Wildcard 是在 filelib 中定義的萬用字串，但不是原子。

• rr(WildcardOrModule, RecordNames) - 從檔案讀取記錄定義，但捨棄 RecordNames (記錄名稱或記錄名稱清單) 中未提及的記錄名稱。

• rr(WildcardOrModule, RecordNames, Options) - 從檔案讀取記錄定義。編譯器選項 {i, Dir}、{d, Macro} 和 {d, Macro, Value} 會被識別並用於設定包含路徑和巨集定義。若要讀取所有記錄定義，請使用 '_' 作為 RecordNames 的值。

• lf() - 輸出本機定義的函數，如果存在，則輸出函數規格。

• lt() - 輸出本機定義的類型。

• lr() - 輸出本機定義的記錄。

• ff() - 忘記本機定義的函數 (包括函數規格，如果存在)。

• ff({FunName,Arity}) - 忘記一個本地定義的函式（包含函式規格，如果存在）。其中 FunName 是函式名稱，以原子 (atom) 表示，而 Arity 是一個整數。

• tf() - 忘記本地定義的型別。

• tf(Type) - 忘記本地定義的型別，其中 Type 是型別名稱，以原子 (atom) 表示。

• fl() - 忘記本地定義的函式、型別和記錄。

• save_module(FilePath) - 將所有本地定義的函式、型別和記錄儲存到模組檔案中，其中 FilePath 應包含檔案的路徑和模組名稱，並帶有 .erl 後綴。

  範例： src/my_module.erl

範例

以下範例是與 Shell 的一段長對話。以 > 開頭的指令是輸入到 Shell 的內容。其他行則是來自 Shell 的輸出。

strider 1> erl
Erlang (BEAM) emulator version 5.3 [hipe] [threads:0]

Eshell V5.3  (abort with ^G)
1> Str = "abcd".
"abcd"

指令 1 設定變數 Str 為字串 "abcd"。

2> L = length(Str).
4

指令 2 設定 L 為字串 Str 的長度。

3> Descriptor = {L, list_to_atom(Str)}.
{4,abcd}

指令 3 建立元組 Descriptor，並評估 BIF list_to_atom/1 。

4> L.
4

指令 4 印出變數 L 的值。

5> b().
Descriptor = {4,abcd}
L = 4
Str = "abcd"
ok

指令 5 評估內部 Shell 指令 b()，這是 "bindings" 的縮寫。這會印出目前的 Shell 變數及其綁定。ok 在最後是函式 b() 的回傳值。

6> f(L).
ok

指令 6 評估內部 Shell 指令 f(L)（"forget" 的縮寫）。變數 L 的值被移除。

7> b().
Descriptor = {4,abcd}
Str = "abcd"
ok

指令 7 印出新的綁定。

8> f(L).
ok

指令 8 沒有效果，因為 L 沒有值。

9> {L, _} = Descriptor.
{4,abcd}

指令 9 對 Descriptor 執行模式比對操作，將新值綁定到 L。

10> L.
4

指令 10 印出 L 的目前值。

11> {P, Q, R} = Descriptor.
** exception error: no match of right hand side value {4,abcd}

指令 11 嘗試將 {P, Q, R} 與 Descriptor 比對，後者為 {4, abc}。比對失敗，且沒有任何新變數被綁定。以 "** exception error:" 開頭的輸出不是表達式的值（因為表達式評估失敗而沒有值），而是系統印出的警告，通知使用者發生錯誤。其他變數（L、Str 等）的值保持不變。

12> P.
* 1:1: variable 'P' is unbound
13> Descriptor.
{4,abcd}

指令 12 和 13 顯示 P 未綁定，因為上一個指令失敗，並且 Descriptor 沒有改變。

14>{P, Q} = Descriptor.
{4,abcd}
15> P.
4

指令 14 和 15 顯示正確的比對，其中 P 和 Q 被綁定。

16> f().
ok

指令 16 清除所有綁定。

接下來的幾個指令假設 test1:demo(X) 定義如下

demo(X) ->
    put(aa, worked),
    X = 1,
    X + 10.

17> put(aa, hello).
undefined
18> get(aa).
hello

指令 17 和 18 設定並檢查處理程序字典中項目 aa 的值。

19> Y = test1:demo(1).
11

指令 19 評估 test1:demo(1)。評估成功，且在處理程序字典中所做的變更對 Shell 可見。可以在指令 20 中看到字典項目 aa 的新值。

20> get().
[{aa,worked}]
21> put(aa, hello).
worked
22> Z = test1:demo(2).
** exception error: no match of right hand side value 1
     in function  test1:demo/1

指令 21 和 22 將字典項目 aa 的值變更為 hello 並呼叫 test1:demo(2)。評估失敗，且在發生錯誤之前，在 test1:demo(2) 中對字典所做的變更被捨棄。

23> Z.
* 1:1: variable 'Z' is unbound
24> get(aa).
hello

指令 23 和 24 顯示 Z 未被綁定，且字典項目 aa 保留其原始值。

25> erase(), put(aa, hello).
undefined
26> spawn(test1, demo, [1]).
<0.57.0>
27> get(aa).
hello

指令 25、26 和 27 顯示在背景評估 test1:demo(1) 的效果。在此情況下，表達式會在新產生的處理程序中評估。在處理程序字典中所做的任何變更都僅限於新產生的處理程序，因此 Shell 無法看到。

28> io:format("hello hello\n").
hello hello
ok
29> e(28).
hello hello
ok
30> v(28).
ok

指令 28、29 和 30 使用 Shell 的歷史記錄功能。指令 29 重新評估指令 28。指令 30 使用指令 28 的值（結果）。對於純函式（沒有副作用的函式），結果是相同的。對於有副作用的函式，結果可能會不同。

接下來的幾個指令顯示一些記錄操作。假設 ex.erl 定義一個記錄如下

-record(rec, {a, b = val()}).

val() ->
    3.

31> c(ex).
{ok,ex}
32> rr(ex).
[rec]

指令 31 和 32 編譯檔案 ex.erl 並讀取 ex.beam 中的記錄定義。如果編譯器沒有在 BEAM 檔案上輸出任何記錄定義，rr(ex) 會嘗試改為從原始程式碼檔案讀取記錄定義。

33> rl(rec).
-record(rec,{a,b = val()}).
ok

指令 33 印出名為 rec 的記錄定義。

34> #rec{}.
** exception error: undefined shell command val/0

指令 34 嘗試建立一個 rec 記錄，但由於函式 val/0 未定義而失敗。

35> #rec{b = 3}.
#rec{a = undefined,b = 3}

指令 35 顯示解決方法：明確將值指派給無法以其他方式初始化的記錄欄位。

36> rp(v(-1)).
#rec{a = undefined,b = 3}
ok

指令 36 使用 Shell 維護的記錄定義印出新建立的記錄。

37> rd(rec, {f = orddict:new()}).
rec

指令 37 直接在 Shell 中定義記錄。此定義會取代從檔案 ex.beam 讀取的定義。

38> #rec{}.
#rec{f = []}
ok

指令 38 使用新的定義建立記錄，並印出結果。

39> rd(rec, {c}), A.
* 1:15: variable 'A' is unbound
40> #rec{}.
#rec{c = undefined}
ok

指令 39 和 40 顯示記錄定義會以副作用方式更新。指令的評估失敗，但 rec 的定義已執行。

對於下一個指令，假設 test1:loop(N) 定義如下

loop(N) ->
    io:format("Hello Number: ~w~n", [N]),
    loop(N+1).

41> test1:loop(0).
Hello Number: 0
Hello Number: 1
Hello Number: 2
Hello Number: 3

User switch command
 --> i
 --> c
.
.
.
Hello Number: 3374
Hello Number: 3375
Hello Number: 3376
Hello Number: 3377
Hello Number: 3378
** exception exit: killed

指令 41 評估 test1:loop(0)，這會使系統進入無限迴圈。此時使用者輸入 ^G (Control G)，這會暫停目前處理程序的輸出（該處理程序卡在迴圈中），並啟動 JCL 模式。在 JCL 模式中，使用者可以啟動和停止作業。

在此特定情況下，指令 i ("interrupt") 會終止迴圈程式，而指令 c 會再次連線到 Shell。由於處理程序在我們終止它之前在背景中執行，因此在顯示訊息 "** exception exit: killed" 之前會發生更多輸出。

42> E = ets:new(t, []).
#Ref<0.1662103692.2407923716.214192>

指令 42 建立一個 ETS 表格。

43> ets:insert({d,1,2}).
** exception error: undefined function ets:insert/1

指令 43 嘗試將元組插入到 ETS 表格中，但遺失第一個參數（表格）。此例外狀況會終止評估器處理程序。

44> ets:insert(E, {d,1,2}).
** exception error: argument is of wrong type
     in function  ets:insert/2
        called as ets:insert(16,{d,1,2})

指令 44 更正了錯誤，但 ETS 表格已毀損，因為它由終止的評估器處理程序擁有。

45> f(E).
ok
46> catch_exception(true).
false

指令 46 將評估器處理程序的例外狀況處理設定為 true。也可以在啟動 Erlang 時使用 erl -stdlib shell_catch_exception true 設定例外狀況處理。

47> E = ets:new(t, []).
#Ref<0.1662103692.2407923716.214197>
48> ets:insert({d,1,2}).
* exception error: undefined function ets:insert/1

指令 48 犯了與指令 43 相同的錯誤，但這次評估器處理程序繼續運作。輸出開頭的單星號表示例外狀況已被捕獲。

49> ets:insert(E, {d,1,2}).
true

指令 49 成功將元組插入到 ETS 表格中。

50> ets:insert(#Ref<0.1662103692.2407923716.214197>, {e,3,4}).
true

指令 50 將另一個元組插入到 ETS 表格中。這次，第一個參數是表格識別碼本身。Shell 可以剖析具有 PID (<0.60.0>)、埠 (#Port<0.536>)、參考 (#Ref<0.1662103692.2407792644.214210>) 和外部函式 (#Fun<a.b.1>) 的指令，但除非可以在執行中的系統中建立對應的 PID、埠、參考或函式，否則指令會失敗。

51> halt().
strider 2>

指令 51 結束 Erlang 執行階段系統。

JCL 模式

當 Shell 啟動時，它會啟動單一評估器處理程序。此處理程序以及它產生的任何本地處理程序都稱為 job。只有目前的作業（稱為 connected）可以執行標準 I/O 操作。所有其他作業（稱為 detached）如果嘗試使用標準 I/O，則會被 blocked。

所有不使用標準 I/O 的作業都以正常方式執行。

Shell 跳脫鍵 ^G (Control G) 會分離目前的作業並啟動 JCL 模式。JCL 模式提示字元為 "-->"。如果在提示字元中輸入 "?"，則會顯示以下說明訊息

--> ?
c [nn]            - connect to job
i [nn]            - interrupt job
k [nn]            - kill job
j                 - list all jobs
s [shell]         - start local shell
r [node [shell]]  - start remote shell
q                 - quit erlang
? | h             - this message

JCL 指令具有以下含義

• c [nn] - 連接到作業編號 <nn> 或目前的作業。標準 Shell 會恢復。目前作業使用標準 I/O 的操作會與使用者對 Shell 的輸入交錯。

• i [nn] - 停止作業編號 nn 或目前作業的目前評估器處理程序，但不會終止 Shell 處理程序。因此，任何變數綁定和處理程序字典都會保留，且可以再次連接作業。此指令可用於中斷無限迴圈。

• k [nn] - 終止作業編號 nn 或目前的作業。作業中所有產生的處理程序都會被終止，前提是它們尚未評估 group_leader/1 BIF，且位於本地電腦上。在遠端節點上產生的處理程序不會被終止。

• j - 列出所有作業。會印出所有已知作業的清單。目前的作業名稱會加上 '*' 字首。

• s - 啟動新的作業。這會指派新的索引 [nn]，可以在參考中使用。

• s [shell] - 啟動新的作業。這會指派新的索引 [nn]，可以在參考中使用。如果指定選用的引數 shell，則會假設它是一個實作替代 Shell 的模組。

• r [node] - 在 node 上啟動遠端作業。這用於分散式 Erlang，以便允許在一個節點上執行的 Shell 控制在網路節點上執行的一些應用程式。如果指定選用的引數 shell，則會假設它是一個實作替代 Shell 的模組。

• q - 結束 Erlang。請注意，如果 Erlang 是以忽略中斷的系統旗標 +Bi 啟動，則此選項會停用（例如，在執行限制 Shell 時，這會很有用，請參閱下一節）。

• ? - 顯示以上說明訊息。

Shell 跳脫行為可以透過 STDLIB 應用程式變數 shell_esc 變更。變數的值可以是 jcl (erl -stdlib shell_esc jcl) 或 abort (erl -stdlib shell_esc abort)。第一個選項會將 ^G 設定為啟動 JCL 模式（這也是預設行為）。後者會將 ^G 設定為終止目前的 Shell 並啟動新的 Shell。當 shell_esc 設定為 abort 時，無法叫用 JCL 模式。

如果您希望 Erlang 節點從一開始就具有遠端作業 (而不是預設的本地作業)，請使用旗標 -remsh 啟動 Erlang，例如，erl -remsh other_node@other_host

受限 Shell

Shell 可以以受限模式啟動。在此模式下，只有在允許的情況下，Shell 才會評估函數呼叫。此功能使我們能夠，例如，防止使用者從提示符號意外呼叫可能會損害正在執行的系統的函數（與系統標誌 +Bi 結合使用時很有用）。

當受限 Shell 評估表達式並遇到函數呼叫或運算子應用時，它會呼叫回呼函數（並提供有關相關函數呼叫的資訊）。此回呼函數會回傳 true 以讓 Shell 繼續進行評估，或回傳 false 以中止評估。使用者可以實作兩個可能的回呼函數：

• local_allowed(Func, ArgList, State) -> {boolean(),NewState}

  此函數用於判斷是否允許呼叫具有引數 ArgList 的本地函數 Func。

• non_local_allowed(FuncSpec, ArgList, State) -> {boolean(),NewState} | {{redirect,NewFuncSpec,NewArgList},NewState}

  此函數用於判斷是否允許呼叫具有引數 ArgList 的非本地函數 FuncSpec（{Module,Func} 或 fun）。回傳值 {redirect,NewFuncSpec,NewArgList} 可用於讓 Shell 評估與 FuncSpec 和 ArgList 指定的函數不同的其他函數。

這些回呼函數是從 erl_eval 手冊頁中描述的本地和非本地評估函數處理常式中呼叫的。（ArgList 中的引數會在呼叫回呼函數之前進行評估。）

從 OTP 25.0 開始，如果評估 Erlang 建構時發生錯誤，例如在模式匹配期間發生 badmatch 或在 comprehension 中發生 bad_generator，則評估器會分派到 erlang:raise(error, Reason, Stacktrace)。此呼叫將根據 non_local_allowed/3 回呼函數進行檢查。您可以禁止它、允許它或重新導向到您選擇的另一個呼叫。

引數 State 是一個元組 {ShellState,ExprState}。回傳值 NewState 具有相同的形式。這可以用於在回呼函數的呼叫之間傳遞狀態。ShellState 中儲存的資料在整個 Shell 工作階段中都有效。ExprState 中儲存的資料僅在評估目前表達式時有效。

有兩種啟動受限 Shell 工作階段的方法：

• 使用 STDLIB 應用程式變數 restricted_shell，並將回呼模組的名稱指定為其值。範例（使用在 callback_mod.erl 中實作的回呼函數）：$ erl -stdlib restricted_shell callback_mod。
• 從正常的 Shell 工作階段中，呼叫函數 start_restricted/1。這會退出目前的評估器並以受限模式啟動新的評估器。

注意事項

• 當受限 Shell 模式啟用或停用時，在節點上啟動的新作業會分別以受限模式或正常模式執行。
• 如果已在特定節點上啟用受限模式，則連線到此節點的遠端 Shell 也會在受限模式下執行。
• 回呼函數不能用於允許或禁止從編譯程式碼呼叫的函數執行（僅限從在 Shell 提示符號輸入的表達式呼叫的函數）。

載入回呼模組時發生的錯誤會根據受限 Shell 的啟動方式以不同方式處理。

• 如果在模擬器啟動期間透過設定 STDLIB 變數啟動受限 Shell，且無法載入回呼模組，則會使用僅允許 q() 和 init:stop() 命令的預設受限 Shell 作為備援。
• 如果使用 start_restricted/1 啟動受限 Shell，且無法載入回呼模組，則會將錯誤報告傳送到錯誤記錄器，且呼叫會回傳 {error,Reason}。

提示

預設的 Shell 提示函數會顯示節點的名稱（如果節點可以是分散式系統的一部分）和目前的命令編號。使用者可以透過呼叫 prompt_func/1 或為 STDLIB 應用程式設定應用程式組態參數 shell_prompt_func 來自訂提示函數。同樣地，也可以透過呼叫 multiline_prompt_func/1 或為 STDLIB 應用程式設定應用程式參數 shell_multiline_prompt 來設定多行提示。

自訂的提示函數會以元組 {Mod, Func} 的形式表示。該函數會以 Mod:Func(L) 的形式呼叫，其中 L 是 Shell 建立的鍵值對清單。目前只有一對：{history, N}，其中 N 是目前的命令編號。該函數會回傳字元清單或原子。此限制是由於 Erlang I/O 協定所致。清單和原子中允許使用程式碼點 255 以外的 Unicode 字元。請注意，在受限模式下，必須允許呼叫 Mod:Func(L)，否則會呼叫預設的 Shell 提示函數。