etwen
7b8f04e1dd
- Add TeraTerm-compatible sprintf2 (C printf formatting into a string var) - Fix SVOS power-cycle script racing ahead by gating prompt waits behind output-completion markers - Bump version to 0.1.2; docs and README updates
179 lines
6.1 KiB
Markdown
179 lines
6.1 KiB
Markdown
# TTL Script Reference — ETTerms
|
||
|
||
> ETTerms 的 TTL（Tera Term Language）腳本引擎移植自 MyTeraTerm，改為驅動原生
|
||
> `ISessionChannel`（SSH / Serial 皆可）。在 **Scripts 檢視**載入 `.ttl` 腳本，對
|
||
> **目前 active session** 執行（先在 Terminal 檢視開好連線）。
|
||
|
||
執行於背景執行緒，可隨時按 **Stop** 中止；`wait` / `pause` 期間皆可取消。
|
||
|
||
---
|
||
|
||
## 語法規則
|
||
|
||
- 一行一個指令；前後空白會被去除。
|
||
- 註解：`;` 之後到行尾視為註解。
|
||
- 字串引號 `'...'` 或 `"..."` 皆可，送出時引號會被去除。
|
||
- 變數以 `名稱 = 值` 指派；名稱須符合 `^[a-zA-Z_][a-zA-Z0-9_]*$`。
|
||
- 內建變數 `result`：`wait` 命中為 `1`、逾時為 `0`。
|
||
- 換行：`sendln` 自動附加 `\r\n`。
|
||
|
||
---
|
||
|
||
## 指令對照表
|
||
|
||
| 指令 | 語法 | 說明 |
|
||
|------|------|------|
|
||
| `send` | `send '文字'` | 送出文字（不加換行）到 active session。 |
|
||
| `sendln` | `sendln '文字'` | 送出文字並附加 `\r\n`。 |
|
||
| `wait` | `wait '字串'` | **一直等到**接收緩衝出現指定字串才往下；預設無限等待（可按 Stop 取消）。命中後 `result=1` 並清掉緩衝中該字串（含）之前的內容。 |
|
||
| `pause` | `pause 秒數` | 暫停指定秒數（可被 Stop 中止）。 |
|
||
| `timeout` | `timeout = 秒數` | 設定 `wait` 的逾時秒數。預設 `0`＝無限等待；若設為 `N>0`，`wait` 超過 N 秒仍未命中會**中止整個腳本並報錯**（不會略過 `wait` 往下做）。 |
|
||
| `flushrecv` | `flushrecv` | 清空接收緩衝區。 |
|
||
| `logopen` | `logopen '檔名'` | 開啟 log 檔（覆寫）；`send` 與 `logwrite` 會寫入。 |
|
||
| `logwrite` | `logwrite '文字'` | 寫一行到 log 檔。 |
|
||
| `logclose` | `logclose` | 關閉 log 檔（腳本結束時自動關閉）。 |
|
||
| `messagebox` | `messagebox '訊息'` | 跳出訊息對話框。 |
|
||
| `sprintf2` | `sprintf2 變數 格式 [引數 ...]` | C `printf` 風格格式化，結果存入字串變數。詳見下方說明。 |
|
||
| `if` / `elseif` / `else` / `endif` | 見下 | 條件分支（可巢狀）。 |
|
||
| `while` / `endwhile` | 見下 | 迴圈（可巢狀，可被 Stop 中止）。 |
|
||
| `名稱 = 值` | `idx = 0` | 變數指派，支援 `+ - * /` 整數運算與字串。 |
|
||
|
||
> **注意：** PDU 控制指令（`pductrl` / `pduconnect`）屬 Phase 7，本階段尚未提供。
|
||
|
||
---
|
||
|
||
## Group 同步指令
|
||
|
||
以下指令**只能在 Run Group 模式**下使用（toolbar 的 `▶ Group1` / `▶ Group2` / `▶ Group3`）。
|
||
若在 `▶ Script`（分頁個別執行）或 `▶ Run All` 使用，會跳 Warning 並拒絕執行。
|
||
|
||
Group 內的成員依加入順序編為 **A, B, C, D...**，顯示在 cell footer（如 `[Group1-A]`）。
|
||
|
||
| 指令 | 語法 | 說明 |
|
||
|------|------|------|
|
||
| `waitall` | `waitall '字串'` | 各成員各自 `wait` 到指定字串出現後，再等其他成員也完成，全員到齊才繼續下一步。 |
|
||
| `sendlnall` | `sendlnall '文字'` | 等所有成員到達此行後，每人各自對自己的 channel `sendln` 同一段文字。 |
|
||
| `sendlngroup` | `sendlngroup A '文字'` | 只有指定 member（A/B/C...）會 `sendln`，其他成員跳過。用於 Group 內各設備需送不同指令的情境。 |
|
||
|
||
### Group 範例：同步升級多台交換機
|
||
|
||
```ttl
|
||
; Group1 有 A=SW1, B=SW2, C=SW3
|
||
; 每台各自等到 prompt 再同步
|
||
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 '#'
|
||
|
||
; 全員一起 reload
|
||
sendlnall 'reload'
|
||
waitall 'confirm'
|
||
sendlnall 'y'
|
||
```
|
||
|
||
### Group 設定方式
|
||
|
||
1. 在分頁 Tab 上**右鍵** → 選擇 `Group 1` / `Group 2` / `Group 3`（或 `No Group` 取消）
|
||
2. 設定後 cell footer 會顯示 `[Group1-A]`、`[Group1-B]` 等標籤
|
||
3. 點 toolbar 的 `▶ Group1` 載入 `.ttl` 檔，Group 內所有成員平行執行同一份腳本
|
||
|
||
---
|
||
|
||
## 條件運算子
|
||
|
||
`if` / `elseif` / `while` 條件支援：
|
||
|
||
| 運算子 | 類型 | 範例 |
|
||
|--------|------|------|
|
||
| `>=` `<=` `>` `<` | 數值 | `if idx >= 3 then` |
|
||
| `==` `!=` | 字串 / 數值 | `if result == 1 then` |
|
||
| `=` | 數值或字串相等 | `if result = 0 then` |
|
||
| （無運算子） | 非零為真 | `if result then` |
|
||
|
||
`then` 關鍵字可省略。
|
||
|
||
---
|
||
|
||
## sprintf2 格式化
|
||
|
||
`sprintf2 變數 格式字串 [引數 ...]` 以 C 語言 `printf` 規則格式化，結果存入指定字串變數，與
|
||
Tera Term 的 `sprintf2` 行為一致。
|
||
|
||
```ttl
|
||
sprintf2 ver 'Tera Term 4.%d' 51 ; ver = "Tera Term 4.51"
|
||
sprintf2 win 'Windows %d (+%s)' 2000 'SP4' ; win = "Windows 2000 (+SP4)"
|
||
sprintf2 test '%s=%d %s=0x%x' 'dec' 10 'hex' 33 ; test = "dec=10 hex=0x21"
|
||
messagebox test
|
||
```
|
||
|
||
- **轉換型別**：`c d i o u x X e E f g G a A s`
|
||
- **旗標**：`-`（靠左）、`+`（顯示正負號）、`0`（補零）、`#`（替代格式，如 `0x`）、空白（正數前空格）
|
||
- **寬度／精度**：十進位整數，或用 `*` 從引數動態取得（如 `%*d`、`%.*f`）
|
||
- 浮點數須以**字串**傳入（TTL 無浮點型別），例 `sprintf2 s '%.2f' '3.14159'`
|
||
- **格式字串不展開變數**（保持字面值），僅各引數會展開變數，故可累加自身：
|
||
`sprintf2 s '%s,' s` 會把 `s` 接上 `,`
|
||
|
||
執行後設定系統變數 `result`：
|
||
|
||
| 值 | 狀態 |
|
||
|----|------|
|
||
| 0 | 格式化成功 |
|
||
| 1 | 缺少格式字串 |
|
||
| 2 | 格式無效 |
|
||
| 3 | 引數無效（缺少或無法解析） |
|
||
| 4 | 目的變數名稱無效 |
|
||
|
||
---
|
||
|
||
## 範例：SSH 自動登入 + 收 log
|
||
|
||
```ttl
|
||
; 等提示字元，逐步登入並收集輸出
|
||
timeout = 15
|
||
|
||
wait 'login:'
|
||
sendln 'admin'
|
||
wait 'Password:'
|
||
sendln 'secret'
|
||
wait '$'
|
||
|
||
logopen 'session.log'
|
||
sendln 'uname -a'
|
||
wait '$'
|
||
sendln 'uptime'
|
||
wait '$'
|
||
logclose
|
||
|
||
messagebox 'Done'
|
||
```
|
||
|
||
## 範例：while 迴圈下命令
|
||
|
||
```ttl
|
||
idx = 0
|
||
while idx < 5
|
||
sendln 'echo loop'
|
||
wait '$'
|
||
idx = idx + 1
|
||
endwhile
|
||
```
|
||
|
||
## 範例：if / elseif / else
|
||
|
||
```ttl
|
||
sendln 'whoami'
|
||
wait '$'
|
||
if result == 1 then
|
||
logwrite 'prompt matched'
|
||
elseif result == 0 then
|
||
logwrite 'timed out'
|
||
else
|
||
logwrite 'unknown'
|
||
endif
|
||
```
|