# TTL Script Reference — ETTerms

> ETTerms 的 TTL（Tera Term Language）腳本引擎移植自 MyTeraTerm，改為驅動原生
> `ISessionChannel`（SSH / Serial / Shell 皆可）。在分頁上按 **▶ Script** 載入 `.ttl`
> 對該分頁執行；或用 toolbar 的 **▶ Run All** / **▶ Group1-3** 批次執行。
>
> v0.5.0 起大幅對齊 [TeraTerm macro 指令集](https://teratermproject.github.io/manual/5/en/macro/command/index.html)。
> 本文**前段是 ETTerms 獨有指令**，**後段是與 TeraTerm 共有的指令**。

執行於背景執行緒，可隨時按 **Stop** 中止；`wait` / `pause` 期間皆可取消。
腳本的進度訊息（`[wait]`、`dispstr`、錯誤等）會以灰色顯示在該分頁的終端機裡。

---

## 語法規則

- 一行一個指令；前後空白會被去除。
- 註解：`;` 之後到行尾（**引號內的 `;` 不算**）。
- 字串引號 `'...'` 或 `"..."` 皆可。
- Label：`:名稱` 一行，供 `goto` / `call` 跳轉。
- 變數以 `名稱 = 運算式` 指派；名稱須符合 `[a-zA-Z_][a-zA-Z0-9_]*`，大小寫不分。
- 運算式支援：整數（十進位 / `0x1F` / `$1F`）、字串、括號、`+ - * / %`、
  比較 `= == <> != > < >= <=`、邏輯 `and or xor not`（同義 `&& || !`）。
  比較時兩邊都是數字用數值比較，否則字串比較；未定義變數視為 `0`。
- 單行 if：`if <條件> <指令>`（如 `if result = 0 goto retry`）；區塊 if 用 `then ... endif`。

### 系統變數

| 變數 | 說明 |
|------|------|
| `result` | 多數指令的結果碼（各指令說明）。 |
| `inputstr` | `waitln` / `recvln` / `inputbox` / `sprintf` 的結果字串。 |
| `matchstr` | `waitregex` / `strmatch` 命中的整段文字。 |
| `groupmatchstr1`〜`9` | regex 群組（`waitregex` / `strmatch`）或 `strsplit` 的分段。 |
| `timeout` | wait 家族的逾時（秒），`timeout = 10`；0 = 無限等待。 |
| `mtimeout` | 逾時的毫秒部分，與 `timeout` 相加（`mtimeout = 500`）。 |

---

# 一、ETTerms 獨有指令

## Group 同步（多分頁協同）

以下指令**只能在 Run Group 模式**下使用（toolbar 的 `▶ Group1-3`）。
`▶ Script` 和 `▶ Run All` 會拒絕含這些指令的腳本。
Group 內的成員依序編為 **A, B, C...**（顯示在 cell footer，如 `[Group1-A]`）。

> ⚠ 刻意設計：group 同步時**一個成員停止（Stop / 逾時 / 錯誤），其他成員會停在
> barrier 等**——整組一起停下來，避免半組繼續跑造成狀態不一致。

| 指令 | 語法 | 說明 |
|------|------|------|
| `waitall` | `waitall '字串'` | 各成員各自 `wait` 到字串出現，再等其他成員到齊才繼續。 |
| `sendlnall` | `sendlnall '文字'` | 等所有成員到達此行後，每人各自 `sendln` 同一段文字。 |
| `sendlngroup` | `sendlngroup A '文字'` | 只有指定 member（A/B/C...）`sendln`，其他成員跳過。 |

```ttl
; Group1 有 A=SW1, B=SW2, C=SW3 — 同步升級
waitall '#'
sendlngroup A 'copy tftp://10.0.0.1/sw1.bin flash:'
sendlngroup B 'copy tftp://10.0.0.1/sw2.bin flash:'
sendlngroup C 'copy tftp://10.0.0.1/sw3.bin flash:'
waitall '#'
sendlnall 'reload'
```

## PDU 電源控制（iPoMan II/III，SNMP）

| 指令 | 語法 | 說明 |
|------|------|------|
| `pduconnect` | `pduconnect <device> <ip>` | 連 PDU 並驗證，`result` 1/0。device 為自訂編號。 |
| `pductrl` | `pductrl <device> <port> <0\|1>` | 指定插座 OFF(0)/ON(1)，`result` 1/0。 |

```ttl
pduconnect 1 192.168.1.21
if result = 0 goto fail
pductrl 1 3 0        ; DUT 斷電
pause 5
pductrl 1 3 1        ; DUT 上電
wait 'login:'
:fail
```

## 行為與 TeraTerm 不同之處（重要）

| 項目 | ETTerms 行為 |
|------|--------------|
| `wait`（**單字串**） | 命中後需裝置**安靜 300ms**（無新資料）才接受，並取「最後一次」出現——排除輸出中途的指令回顯（如 `SVOS> help`）造成腳本搶跑。**逾時會中止腳本**（TeraTerm 是 `result=0` 繼續）。 |
| `wait`（**多字串**） | TeraTerm 相容：任一命中即繼續，`result` = 第幾個字串（1 起算）；逾時 `result=0` **繼續執行**、無 settle。 |
| `goto` / 跨區塊跳轉 | `goto` 跳出 `if`/`while` 區塊後，該區塊的迴圈控制即結束（同層繼續直行）。避免 goto 跳「進」區塊中間。 |
| `call` | 可以在迴圈 / if 內使用（行內執行，返回後迴圈續跑）。 |
| `include` | 路徑須為絕對路徑，或相對於 ETTerms 的工作目錄。 |
| 浮點數 | TTL 無浮點型別；`sprintf/sprintf2` 的浮點引數以字串傳入（`'3.14'`）。 |

---

# 二、與 TeraTerm 共有指令

## 通訊

| 指令 | 語法 | 說明 |
|------|------|------|
| `send` | `send '文字'` | 送出文字（不加換行）。 |
| `sendln` | `sendln '文字'` | 送出文字 + `\r\n`。 |
| `sendfile` | `sendfile '路徑'` | 把整個檔案內容原樣送出（`result` 1/0）。 |
| `wait` | `wait '字串' ['字串2' ...]` | 等待字串出現（行為差異見上表）。 |
| `waitln` | `waitln '字串' ['字串2' ...]` | 等**包含**任一字串的完整一行；該行存入 `inputstr`，`result`=第幾個；逾時 0。 |
| `waitregex` | `waitregex '樣式' ['樣式2' ...]` | 等 regex 命中；`matchstr` / `groupmatchstr1-9` 設定，`result`=第幾個；逾時 0。 |
| `recvln` | `recvln` | 收下一行到 `inputstr`；`result` 1 成功 / 0 逾時。 |
| `flushrecv` | `flushrecv` | 清空接收緩衝。 |
| `dispstr` | `dispstr '文字' [更多...]` | 在終端機顯示訊息（灰色，不送出到裝置）。 |
| `sendbreak` | `sendbreak` | 送 serial break（**Serial 限定**，約 300ms）。 |
| `setbaud` | `setbaud 115200` | 執行中改 baud rate（**Serial 限定**）。 |
| `setdtr` / `setrts` | `setdtr 1` / `setrts 0` | 控制 DTR / RTS 腳位（**Serial 限定**）。 |

## 控制流

| 指令 | 語法 | 說明 |
|------|------|------|
| `if` | `if <條件> <指令>` 或 `if <條件> then ... [elseif] [else] endif` | 單行或區塊，可巢狀。 |
| `while` / `endwhile` | `while <條件>` | 條件為真時重複。 |
| `until` / `enduntil` | `until <條件>` | 條件為**假**時重複。 |
| `for` / `next` | `for i 1 10` | i 從 1 到 10（含），自動 ±1。 |
| `do` / `loop` | `do [while\|until <條件>]` ... `loop [while\|until <條件>]` | 前測或後測迴圈；都不帶條件時為無限迴圈（用 `break` 離開）。 |
| `break` / `continue` | | 跳出 / 提前進入下一輪（while / until / for / do 皆可）。 |
| `goto` | `goto 標籤` | 跳到 `:標籤`。 |
| `call` / `return` | `call 標籤` | 呼叫副程式（`:標籤` 起，`return` 返回；可在迴圈內用）。 |
| `include` | `include '檔案.ttl'` | 執行另一個腳本檔（可巢狀 8 層；檔內 `exit` 只離開該檔）。 |
| `pause` | `pause 秒` | 暫停（可 Stop 取消）。 |
| `mpause` | `mpause 毫秒` | 毫秒級暫停。 |
| `end` | `end` | 結束腳本（成功）。 |
| `exit` | `exit` | include 檔內＝離開該檔；主檔＝同 `end`。 |
| `timeout` / `mtimeout` | `timeout = 10` | wait 家族逾時（秒 / 毫秒，兩者相加）。 |

## 字串

| 指令 | 語法 | 說明 |
|------|------|------|
| `strlen` | `strlen <str>` | `result` = 長度。 |
| `strcompare` | `strcompare <s1> <s2>` | `result` = -1 / 0 / 1。 |
| `strconcat` | `strconcat <strvar> <str>` | strvar += str。 |
| `strcopy` | `strcopy <str> <pos> <len> <strvar>` | 取子字串（pos 1 起算）。 |
| `strinsert` / `strremove` | `strinsert <strvar> <pos> <str>` / `strremove <strvar> <pos> <len>` | 插入 / 刪除。 |
| `strscan` | `strscan <str> <substr>` | `result` = 位置（1 起算，0 = 沒找到）。 |
| `strmatch` | `strmatch <str> <regex>` | regex 比對：`result` = 位置，`matchstr` / `groupmatchstr1-9`。 |
| `strreplace` | `strreplace <strvar> <pos> <regex> <newstr>` | 自 pos 起 regex 全部取代，`result` 1/0。 |
| `strtrim` | `strtrim <strvar> ['字元集']` | 去頭尾字元（預設空白）。 |
| `strsplit` | `strsplit <str> <sep> [count]` | 切成 `groupmatchstr1-9`，`result` = 個數。 |
| `strjoin` | `strjoin <strvar> <sep> [count]` | 把 `groupmatchstr1..count` 接回一串。 |
| `tolower` / `toupper` | `tolower <strvar> <str>` | 轉小寫 / 大寫。 |
| `str2int` / `int2str` | `str2int <intvar> <str>` / `int2str <strvar> <int>` | 字串 ↔ 整數（str2int 的 `result` 1/0）。 |
| `code2str` / `str2code` | `code2str <strvar> 65` / `str2code <intvar> 'A'` | 字元碼 ↔ 字元。 |
| `sprintf` | `sprintf <格式> [引數...]` | C printf 格式化 → **`inputstr`**。 |
| `sprintf2` | `sprintf2 <strvar> <格式> [引數...]` | 同上但存到指定變數（詳見下節）。 |
| `expandenv` | `expandenv <strvar> '%USERPROFILE%\x'` | 展開環境變數。 |

## 檔案 / 資料夾

| 指令 | 語法 | 說明 |
|------|------|------|
| `fileopen` | `fileopen <fhvar> <路徑> <append 0\|1> [readonly 0\|1]` | 開檔；fh 存入變數（-1 失敗）。readonly=1 開來讀。 |
| `filecreate` | `filecreate <fhvar> <路徑>` | 建新檔（覆寫）供寫入。 |
| `filereadln` | `filereadln <fh> <strvar>` | 讀一行；`result` **1 = EOF**、0 = 成功（TeraTerm 相容）。 |
| `filewrite` / `filewriteln` | `filewrite <fh> <str>` | 寫入（ln 版加換行）。 |
| `fileclose` | `fileclose <fh>` | 關檔（腳本結束會自動關）。 |
| `filedelete` | `filedelete <路徑>` | 刪檔，`result` 1/0。 |
| `filesearch` | `filesearch <路徑>` | `result` 1 = 檔案存在。 |
| `basename` / `dirname` | `basename <strvar> <路徑>` | 取檔名 / 取目錄。 |
| `makepath` | `makepath <strvar> <dir> <file>` | 合成路徑。 |
| `foldercreate` / `folderdelete` / `foldersearch` | `foldercreate <路徑>` | 建 / 刪（空）/ 查資料夾。 |
| `getdir` / `setdir` | `getdir <strvar>` / `setdir <路徑>` | 取得 / 變更工作目錄。 |
| `logopen` / `logwrite` / `logclose` | `logopen '檔名'` | 腳本專屬 log 檔（`send` 與 `logwrite` 會寫入）。 |

## 對話框 / 雜項

| 指令 | 語法 | 說明 |
|------|------|------|
| `messagebox` | `messagebox '訊息' ['標題']` | 訊息框。 |
| `inputbox` | `inputbox '提示' ['標題'] [預設值]` | 輸入框 → `inputstr`（取消 `result=0`）。 |
| `yesnobox` | `yesnobox '訊息' ['標題']` | Yes/No → `result` 1/0。 |
| `beep` | `beep` | 系統提示音。 |
| `getdate` / `gettime` | `getdate <strvar> ['%Y%m%d']` | 日期 / 時間字串（strftime 子集：`%Y %y %m %d %H %M %S %j %a %A %b`）。 |
| `getenv` / `setenv` | `getenv 'PATH' <strvar>` | 讀 / 寫環境變數（行程內）。 |
| `random` | `random <intvar> <max>` | 0〜max（含）亂數。 |
| `exec` | `exec '記事本.exe 檔案' ['show'\|'hide'] [wait 0\|1]` | 啟動外部程式；wait=1 時 `result` = exit code。 |
| `getver` | `getver <strvar>` | ETTerms 版本字串。 |
| `getttdir` | `getttdir <strvar>` | ETTerms 執行檔目錄。 |
| `uptime` | `uptime <intvar>` | 系統開機至今毫秒數。 |
| `ifdefined` | `ifdefined <var>` | `result`：0 未定義 / 1 整數 / 2 字串。 |
| `clipb2var` / `var2clipb` | `clipb2var <strvar>` / `var2clipb <str>` | 剪貼簿 ↔ 變數。 |
| `crc32` | `crc32 <intvar> <str>` | CRC-32。 |
| `checksum8/16/32` | `checksum8 <intvar> <str>` | byte 加總（8/16/32 bit）。 |

### 未支援（節錄）

檔案傳輸協定（`xmodem*` / `zmodem*` / `kmt*` / `scp*`）、連線管理（`connect` / `disconnect` /
`closett`）、密碼系列（`getpassword` 等——ETTerms 密碼一律走 Windows Credential Manager）、
陣列（`intdim` / `strdim`）、`waitevent` / `waitn` / `setecho` / `settitle` / `listbox` / `statusbox`。

---

## sprintf2 格式化

`sprintf2 變數 格式字串 [引數 ...]` 以 C `printf` 規則格式化，與 Tera Term 一致。

```ttl
sprintf2 ver 'Tera Term 4.%d' 51                  ; ver = "Tera Term 4.51"
sprintf2 test '%s=%d %s=0x%x' 'dec' 10 'hex' 33   ; test = "dec=10 hex=0x21"
```

- **轉換型別**：`c d i o u x X e E f g G a A s`；**旗標**：`- + 0 #` 與空白；寬度/精度支援 `*`
- 浮點數以**字串**傳入：`sprintf2 s '%.2f' '3.14159'`
- 格式字串不展開變數（保持字面值），引數會展開，故 `sprintf2 s '%s,' s` 可累加自身
- `result`：0 成功、1 缺格式、2 格式無效、3 引數無效、4 目的變數無效

---

## 範例

### 自動登入 + 失敗重試（goto / 單行 if）

```ttl
timeout = 15
retry = 0

:login
sendln ''
wait 'login:'
sendln 'admin'
wait 'Password:'
sendln 'secret'
wait 'Login incorrect' '$'
if result = 2 goto ok        ; 第 2 個字串（$ 提示）命中 → 成功
retry = retry + 1
if retry < 3 goto login
messagebox '登入失敗 3 次' 'Login'
end

:ok
dispstr 'login ok'
```

### waitln + strmatch 解析輸出

```ttl
sendln 'show environment'
timeout = 10
waitln 'Temperature'                       ; 例如 "Temperature: 47 C"
if result = 0 goto notfound
strmatch inputstr 'Temperature:\s*(\d+)'
if result > 0 then
    str2int temp groupmatchstr1
    if temp > 60 then
        messagebox '過溫！' 'ALERT'
    endif
endif
:notfound
```

### for 迴圈 + 檔案輸出

```ttl
getdate today '%Y%m%d'
sprintf 'report_%s.txt' today
filecreate fh inputstr

for i 1 5
    sendln 'cat /proc/loadavg'
    recvln                       ; 回顯
    recvln                       ; 資料行
    filewriteln fh inputstr
    pause 2
next
fileclose fh
```

### call 副程式（迴圈內可用）

```ttl
for i 1 3
    call powercycle
    wait 'login:'
next
end

:powercycle
pductrl 1 3 0
pause 5
pductrl 1 3 1
return
```

### do-loop 等裝置就緒

```ttl
; 注意：單字串 wait 逾時會「中止腳本」，輪詢請用 waitln（逾時 result=0 繼續）
timeout = 2
do
    sendln ''
    waitln 'SVOS>'
loop until result = 1      ; 每 2 秒敲一次直到提示出現
```