分身機器人開發文檔

本頁面說明分身機器人簡易語言的語法規範、內置函數以及安全限制。
當前直譯器穩定版本為 v4.1.0+。

核心結構 (Core Structure)

#load <lib> // 載入內建庫
begin; // 主程式開始
  try; // 嘗試區塊
    // 變數賦值
    val = 100;
    // 輸出結果 (必填)
    output {"結果是: " + val};
  except {error}; // 將錯誤訊息放進error變數
    output {"Error" + error}; // 用輸出而非錯誤訊息回傳以免意外終止程式
  // except; 不進行變數賦值
  endtry;
end; // 主程式結束

指令/關鍵字	範例	說明
#load	#load <math>	加載外部擴充庫（如 math, message)
begin / end	begin; ... end;	定義程式執行的主區塊，需加分號
output	output {content};	設定程式最終回傳內容，僅執行一次
//	// 註解內容	單行註解，執行時會被忽略
;	res = a + b;	指令結尾必須加上分號（結構關鍵字除外）
try / except / endtry	try; ... except; ... endtry;	捕捉區塊內的錯誤且不使用意外終止程式

流程控制 (Control Flow)

支援條件判斷結構，讓腳本能根據不同情況做出反應。每個 if 區塊都必須以 endif 結尾。

if {條件1};
  output {"情況 A"};
elif {條件2};
  output {"情況 B"};
else;
  output {"其他情況"};
endif;

if {條件1 or 條件2}; // if {條件1 || 條件2};
  output {"情況 A"};
elif {條件3 and 條件4}; // elif {條件3 && 條件4};
  output {"情況 B"};
else;
  output {"其他情況"};
endif;

⚠️ 條件判斷注意事項：

if 與 elif 後方條件需要大括號包覆且結尾分號
必須確保 endif 存在，否則直譯器將無法正確解析區塊邊界。
條件運算支援變數值與比較運算 (==, !=, >, <) 。

函式 (Function Definition)

使用 func 封裝重複邏輯。所有自定義函式必須定義在 begin 區塊之前。

函式定義語法

func <名稱> {參數1 參數2};
  res = 參數1 + 參數2;
  sendback {res}; 
endfunc;

如何調用函式

begin;
  // 使用 call 關鍵字調用
  res = call <名稱>{10 20};
  output {res};
end;

⚠️ 函式規則與限制：

位置：必須寫在腳本上方（#load 之後，begin 之前）。
參數：置於 {} 中，彼此以空格分隔。
回傳：必須使用 sendback {值}; 傳回結果。
嚴格禁止：在 func 區塊內使用 wait 指令。

方法 (Method)

使用 method 封裝應用邏輯。不可由使用者自訂。

如何調用方法

begin;
  // 不須使用 call 關鍵字調用
  wait{0.2}; // 等待0.2秒
  val1 = min{1 2}; // 取兩者最小值
  val2 = max{1 2}; // 取兩者最大值
  val3 = abs{-5}; // 取數值之絕對值
  // output {};
end;

⚠️ 方法規則與限制：

參數：置於 {} 中，彼此以空格分隔。
回傳：依照各方法規定。
嚴格禁止：在 method 呼喚不可使用 call 。

內建庫與函數註冊

類別	函數/屬性	回傳型態	類型	說明
math lib	math.pi / math.e	float	variable	圓周率與自然常數
	math.add{a b}	float	function	回傳 a + b 的結果
	math.multiple{a b}	float	function	回傳 a * b 的結果
	math.subtruct{a b}	float	function	回傳 a - b 的結果
message lib	message.username	str	variable	訊息作者名稱
	message.userid	int	variable	訊息作者 ID
	message.id	int	variable	訊息 ID
	message.content	str	variable	觸發程式的訊息內容
	message.createat	float	variable	訊息發送時間
	message.prefix	str	variable	指令前綴字
	message.command	str	variable	指令名稱
requests lib	requests.get{url headers params}	data	function	進行get並附帶headers和params
requests lib	requests.post{url headers json}	data	function	進行post並附帶headers和json
time lib	time.timestamp	float	variable	取得目前的timestamp
time lib	time.asctime	str	variable	取得目前的asctime
list	list.add{list val}	none	method	在列表末尾新增一個元素
	list.pop{list idx}	none	method	移除並回傳指定索引的元素
	list.get{list idx}	any	method	取得指定索引的元素內容
	list.count{list str}	int	method	取得指定元素的數量
	list.length{list}	int	method	取得列表總長度
	list.random{list n}	list	method	隨機抽取 n 個元素 (n 可省略)
dict	dict.set{dict key item}	none	method	在字典設定 key: items
	dict.clear{dict}	none	method	清除整個字典
	dict.get{dict key}	any	method	回傳指定key的item
	dict.length{dict}	int	method	回傳字典長度
	dict.randomkeys{dict n}	any	method	隨機從key抽取 n 個元素 (n 可省略)
	dict.randomitems{dict n}	any	method	隨機從item抽取 n 個元素 (n 可省略)
	dict.del{dict key}	any	method	刪除指定key
string	str.upper{text}	str	method	轉為全大寫
	str.lower{text}	str	method	轉為全小寫
	str.replace{text a b}	list	method	以指定文字a取代文字b
	str.split{text sep}	list	method	以指定字串分割文字
system	turntype{val type}	any	method	轉換型態 (str, int, float, list)
	type{val}	str	method	確認變數型態
	wait{time}	none	method	暫停執行 (限制 0.1 ~ 0.5 秒)
	min{val val}	float	method	取兩者最小值
	max{val val}	float	method	取兩者最大值
	abs{val}	float	method	取數值之絕對值
	round{val val}	float	method	取數值val後五捨六入

運行安全性驗證 (Constraints)

⚠️ 資源與安全限制：

等待限制：單個程式內 wait 指令不得超過 4 次。
迴圈結構：for 總數上限 3 個，最大巢狀深度為 2 層。
迭代次數：單次 for 迴圈迭代次數上限為 5 次。
語法嚴謹：遺漏分號 ; 或關鍵字邊界將導致直譯器報錯並中止執行。
特殊語法：字串相加、列出lib內容(<lib>.variables <lib>.functions)、字串可用\n換行
嚴格賦值：某些語法僅接受在外側定義後再傳入。Dict type不可用預設值定義。

完整程式範例

#load <time>
#load <message>

func welcome {name};
  res = "你好, " + name;
  sendback {res};
endfunc;

begin;
  user = message.username;
  greet = call welcome{user};
      
  for i in 3;
    nowstamp = round{time.timestamp 0};
    output_msg = greet + " 第 " + i + " 次打招呼\n現在的timestamp是:" + nowtimestamp;
  endfor;
      
  output {output_msg};
end;