作者: piaip (piaip) 看板: BBSLua
─────────────────────────────────────
=====================================================================
本文件最後更新時間: 2008/01/07 14:00
v0.108
最新版本請至 PTT2 BBSLua 板取得
本文件為推廣說明用，轉錄不需通知原作者 (推文會被不定期刪除，請見諒)
但由於 BBS-Lua 目前變動非常頻繁，建議您附上原出處方便閱讀者取得最新版
=====================================================================
提醒您: BBS-Lua 系統還在初期開發中，所有的架構/API 都隨時可能大改！
請有您現在的作品可能忽然就跑不動的心理準備。
BBS-Lua 是在 BBS 裡面跑程式語言的機制，選用的程式語言是
Wow UI 所使用的 Lua。 關於此程式語言請見
http://www.lua.org/pil/
http://www.lua.org/manual/5.1/manual.html
這份文件說明了如何在 BBS 上使用 Lua (也就是 BBS-Lua 計畫)，
以及目前可使用的 API 相關說明。
2008 Jan, piaip
=====================================================================
● BBS-Lua 的格式
BBS-Lua 的程式使用一般文章發文即可。 程式碼要用特殊的標籤前後標起來。
這個標籤寫成: (須在行前，前面不可有空白)
--#BBSLUA
讓我們來看個最簡單的範例吧:
--#BBSLUA
print("Hello, world")
--#BBSLUA
這就是一個最簡單的 BBS-Lua 程式。
執行它的方法，目前是在閱讀文章時按下大寫 P 。
=====================================================================
● BBS-Lua 與標準 Lua 異同之處
目前的 BBS-Lua 使用的是標準 Lua 5.1，除了下列不同:
- print() 被轉換為 BBS 輸出
- os library 無法使用
- io library 無法使用
- debug library 無法使用
- load (package) library 無法使用
- 可使用 math library
- 可使用 string library
- 可使用 table library
- 內建 bitlib ( http://luaforge.net/projects/bitlib )
=====================================================================
● API 說明
目前 BBS-Lua 提供的專屬輸出入功能有:
[輸出]
bbs.addstr(str, ...) 畫字到目前位置
bbs.outs(str, ...) 畫字到目前位置 (同 addstr)
bbs.title(str) 移至左上角畫字
bbs.print(str, ...) 印完所印字串後再加上一個換行 (bbs.outs(str,...,"\n"))
print(str, ...) 同 bbs.print
* 全系列畫字函式都可以接受 ANSI 指令
* 注意: 輸出並不會立刻反應在畫面上，要等 refresh()
或其它輸入函式才會作全螢幕的更新。請見 refresh() 說明
[移動]
bbs.getyx() 傳回游標目前位置 (y, x)， y/x 由 (0,0)表左上角
bbs.getmaxyx() 傳回目前螢幕大小 (my,mx), 實際可移動範圍到(my-1,mx-1)
bbs.move(y,x) 移動到 (y,x) (也就是 ANSI 的 *[x;yH)
bbs.moverel(dy,dx) 移動到游標目前位置加上 (dy,dx)
[清除]
bbs.clear() 清除整個畫面+回到左上角
bbs.clrtoeol() 清至行尾
bbs.clrtobot() 清至螢幕底端
[更新畫面]
bbs.refresh() 呼叫此命令時才會真的更新畫面
(呼叫輸入指令如 getch/getstr/kbhit/sleep
時也會自動更新)
另外注意: 為了加速輸出，在使用者已有輸入資料且程式
尚未處理時，螢幕完全不會更新輸出。
[屬性]
bbs.color(c1,c2,...) 切換 ANSI 屬性 (也就是 *[c1;c2;....m)
bbs.color() = *[m
bbs.setattr(c1,c2,...) 同 color()
bbs.ANSI_COLOR(c1,...) 傳回 ANSI 屬性字串 (不馬上變屬性，要 outs 才會變)
bbs.ANSI_RESET 傳回 *[m 字串
bbs.ESC 傳回 ANSI 的 *
[輸入]
bbs.getch() 輸入單鍵
特殊按鍵為大寫名，如 UP DOWN LEFT RIGHT
ENTER BS HOME END INS DEL PGUP PGDN TAB
bbs.getdata(n,echo) 畫 n 個字元的輸入框並輸入字串
echo (可省略) = 0 時只輸入不畫字 (可作密碼輸入)
bbs.getstr(n,echo) 同 getdata
bbs.pause(msg) 在底部畫暫停訊息並等輸入單鍵
bbs.kbhit(wait) 傳回使用者是否有按鍵 (若無輸入則會等待最多 wait 秒)
bbs.kbreset() 清空輸入緩衝區 (吃掉所有已輸入的鍵)
[時間]
bbs.time() 現在時間 (以數字表示)，精準度到秒
bbs.now() 同 time()
bbs.ctime() 現在時間 (以字串表示)
bbs.clock() 高精準度的時間 (gettimeofday，可到秒的小數點以下)
bbs.sleep(sec) 停止執行 sec 秒 (可到小數點以下)
[BBS 資訊]
bbs.userid() 目前使用者的 id
[位元操作 (bitlib) ]
bit.cast(a) cast a to the internally-used integer type
bit.bnot(a) returns the one's complement of a
bit.band(w1, ...) returns the bitwise and of the w's
bit.bor(w1, ...) returns the bitwise or of the w's
bit.bxor(w1, ...) returns the bitwise exclusive or of the w's
bit.lshift(a, b) returns a shifted left b places
bit.rshift(a, b) returns a shifted logically right b places
bit.arshift(a, b) returns a shifted arithmetically right b places
=====================================================================
● 版本更新注意事項
=== 2008/01/06 2:03 前的作品昇級要注意: ===
1. -- BBSLUA 改前後加上 --#BBSLUA
2. stand_title 改 title
3. bbs.outs(bbs.ANSI_COLOR(1,33) .. "test" .. bbs.ANSI_RESET);
建議改成 bbs.color(1,33); bbs.outs("test"); bbs.color();
=== 2008/01/06 13:00 後有效: ===
1. 新增 getmaxyx(), moverel()
2. chattr() 改為 setattr()
3. igetch() 停止支援，請用 getch
4. getnstr() 停止支援，請用 getstr 或 getdata
5. vmsg() 停止支援，請用 pause
6. bbs.outs() / bbs.addstr() 可改為寫 print()，不用加前面的 bbs.
=== 2008/01/06 15:55 後有效: ===
1. 新增 bbs.userid() 為目前使用者 id
2. 新增 bbs.kbhit()
=== 2008/01/06 17:05 後有效: ===
1. print()/bbs.print() 現在會比 outs() 多印一個換行
2. 修正跑久會停住的問題
=== 2008/01/06 21:53 後有效: ===
1. 新增 bbs.clock()
=== 2008/01/07 10:50 後有效: ===
1. 新增 bbs.sleep()，暫時只開放最多 10 秒
=== 2008/01/07 11:50 後有效: ===
1. 修正 bbs.sleep() 未處理 Ctrl-C 的問題，重新開放上限
2. 新增 bbs.kbreset()
=== 2008/01/07 14:15 後有效: ===
1. 新增 bitlib ( http://luaforge.net/projects/bitlib ) 為標準之一，
方便移植用 C 寫的程式
沒有留言:
張貼留言