etwenandClaude Fable 5
98fbd310d2
Search (Ctrl+F): - in-terminal search bar over full scrollback + screen; all hits highlighted, current hit emphasized; Enter searches upward, Shift+Enter downward, F3/Esc shortcuts - hits anchored via ScreenBuffer.DroppedLines so positions stay correct as the ring buffer drops old lines Keyword highlighting & tab alerts: - new Settings -> Highlight page: user-defined keyword list with per-rule enable and a global toggle (AppSettings.KeywordRules) - keywords highlighted red in every terminal (visible rows only, case-insensitive); background tabs flash a red dot when a keyword appears, cleared when the tab is opened TTL engine (TeraTerm macro compatibility): - new TtlExpression parser: parens, and/or/xor/not, comparisons, * / % + -, hex literals (0x/$), string/int values; legacy fallback keeps old scripts working - control flow: goto, call/return (inline, usable inside loops), for/next, do/loop [while|until], until/enduntil, break, continue, end, exit, include, mpause; one-line "if <expr> <statement>" - waits: waitln, waitregex (matchstr/groupmatchstr1-9), recvln, multi-string wait (TeraTerm semantics), mtimeout - strings: strlen strcompare strconcat strcopy strinsert strremove strmatch strscan strreplace strtrim strsplit strjoin tolower toupper str2int int2str code2str str2code sprintf expandenv - files: fileopen filereadln filewrite(ln) fileclose filecreate filedelete filesearch basename dirname makepath foldercreate folderdelete foldersearch getdir setdir - misc: beep getdate gettime getenv setenv random exec getver getttdir uptime ifdefined clipb2var var2clipb inputbox yesnobox crc32 checksum8/16/32 dispstr - serial: sendbreak setbaud setdtr setrts sendfile (SerialChannel gains SendBreak/SetBaudRate/SetDtr/SetRts) - script Output (incl. dispstr) now echoed gray into the terminal - quote-aware comment stripping; case-insensitive variables Docs: - docs/ttl-script-reference.md rewritten: ETTerms-only commands first, then the TeraTerm-shared set, with examples Misc: - version 0.5.0; About changelog; CLAUDE.md v0.5.0 notes - restore ETTerms.PduCore ProjectReference in ETTerms/PduMcp csproj (was dropped in the working tree; required to compile) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
303 lines
14 KiB
Markdown
303 lines
14 KiB
Markdown
# 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 秒敲一次直到提示出現
|
||
```
|