bbslua.lua

Run BBS-Lua on LuaJIT

./bbslua.lua <program-path>

Prerequisite

• x86-64 Linux
  For other platform, you may need to change the constant definition (termio and clock) in bbslua.lua to make it work correctly.
• LuaJIT >= 2.1.0-beta3
  Older versions may work, but their are not tested.

Implemented BBS-Lua API

All functions and constants specified in BBS-Lua API level 0.201 are implemented, with some extensions.

Table legend:

• with extensions
• bbslua.lua extensions
• Incompatible with C implementation

Library availability

Library	Description	Availability	Note
Basic	Lua standard library	- print aliases bbs.print - dofile, load, loadfile, loadstring are disabled
coroutine	Sub-library of basic library	Full
package	Lua standard library	- Import from file is disabled - Only available standard/builtin modules and user-defined modules can be imported	Not in BBS-Lua
string	Lua standard library	Full
table	Lua standard library	Full
math	Lua standard library	Full
io	Lua standard library	Disabled
os	Lua standard library	Disabled
debug	Lua standard library	- All setters are disabled - debug.getregistry and debug.getupvalue are disabled	Not in BBS-Lua
bit	Lua BitOp LuaJIT builtin library	Full - bit.cast aliases to bit.tobit	Older C implementations use bitlib, which is deprecated.
ffi	LuaJIT builtin library	Disabled
jit	LuaJIT builtin library	Disabled
bbs	BBS-Lua library	Full, with extension	Cannot be imported
toc	BBS-Lua library	Full	Cannot be imported
store	BBS-Lua library	Full, with extension	Cannot be imported

bbs library

Function	Parameter ↦ Return Value	Description	Note
bbs.addstr	(...) ↦ ()	Concatenate arguments and print it on the cursor with graphic attribute of the cursor.
bbs.outs	(...) ↦ ()	An alias to bbs.addstr
bbs.title	(ttl) ↦ ()	Move the cursor to position (0, 0) and print ttl with implementation-defined appearance for title.	ttl cannot be omitted.
bbs.print	(...) ↦ ()	Concatenate arguments, print it on the cursor with graphic attribute of the cursor, and then print a newline.
print	(...) ↦ ()	An alias to bbs.print
bbs.getyx	() ↦ (y: number, x: number)	Get the internal cursor position (y, x) (not the physical cursor). - y is the vertical offset (0-indexed) from the topmost row of the screen. - x is the horizontal offset (0-indexed) from the leftmost column of the screen.
bbs.getmaxyx	() ↦ (row: number, col: number)	Get the screen size row × col.
bbs.move	(y=0, x=0) ↦ ()	Move the cursor to position (y, x). - Given the screen size row × col, both 0 ≤ y ≤ row - 1 and 0 ≤ x ≤ col - 1 should hold, otherwise the effect is implementation-defined.
bbs.moverel	(dy, dx=0) ↦ ()	Relative cursor move - Given the screen size row × col and the cursor position (y, x), both 0 ≤ y + dy ≤ row - 1 and 0 ≤ x + dx ≤ col - 1 should hold, otherwise the effect is implementation-defined.	dy cannot be omitted.
bbs.clear	() ↦ ()	Clear screen with default graphic attribute and move the cursor to position (0, 0)
bbs.clrtoeol	() ↦ ()	- Clear from the cursor to the line end with default graphic attribute. - The cursor is kept at the original position.
bbs.clrtobot	() ↦ ()	- Clear from the cursor to the line end of the bottom line of screen with default graphic attribute. - The cursor is kept at the original position.
bbs.rect	(r, c, ttl=nil) ↦ ()	- Draw a rectangle of size r × c with the graphic attribute of the cursor. - Print ttl, if presents, with the graphic attribute of the cursor at the center of the rectangle. - Whether ttl is truncated to fit inside the rectangle is implementation-defined. - The cursor is kept at the original position. - ttl can span over multiple lines.	- r, c cannot be omitted. - ttl is always printed.
bbs.refresh	() ↦ ()	Flush buffered outputs to screen.
bbs.attrset	(...) ↦ ()	Change the graphic attribute of the cursor.
bbs.color	(...) ↦ ()	An alias to bbs.attrset
bbs.ANSI_COLOR	(...) ↦ (str: string)	Get an ANSI escape string for changing the graphic attribute of the cursor.
bbs.strip_ansi	(str) ↦ (stripped: string)	Get a copy of str with all ANSI escapes removed.	str cannot be omitted.
bbs.str_width	(str) ↦ (w: number)	Get displayed width of string (assume UTF-8)
bbs.getch	() ↦ (key: string)	Wait for a key from user input. Return that key.
bbs.getdata	(w, echo=bbs.DOECHO, str="") ↦ (data: string)	- Open an input field at the cursor and wait for the input to complete. - Return the input. - echo controls how the input is displayed and processed. - 0 causes the input text to be invisible. - Other values have implementation-defined effects. - str is the initial text in the input field.	See the constant table for available echo values in bbslua.lua.
bbs.getstr	(w, echo=bbs.DOECHO, str="") ↦ (data: string)	An alias to bbs.getdata
bbs.pause	(msg=nil) ↦ (key: string)	- Display a pause message msg with implementation-defined appearance. The message can be dismissed with any key. - Whether different appearances are used regarding the presence of msg is implementation-defined. - Return the key used to dismiss the message.
bbs.kbhit	(sec=0) ↦ (hit: boolean)	- Wait for a key from user input for at most sec seconds (can be a decimal). - Return whether any key is pressed. - The key, if any, remains unprocessed.
bbs.kbreset	() ↦ ()	Ignore all unprocessed buffered inputs.
bbs.kball	(sec=0) ↦ (keys: string...)	Wait for sec seconds (can be a decimal) and then return all keys pressed during the waiting.
bbs.time	(table=nil) ↦ (time: number)	Get a number representing the time. - table can be used to specify a time different from now.	Aliases to os.time(table) in bbslua.lua
bbs.now	(table=nil) ↦ (time: number)	An alias to bbs.time
bbs.ctime	(format: string?=nil, time: number?=nil) ↦ (time: string)	Get the formatted time. - format can be used to specify the format to use. - time can be used to specify the time to format.	Aliases to os.date(format, time) in bbslua.lua
bbs.clock	() ↦ (time: number)	Get the current time from a timer with higher resolution than bbs.time.
bbs.sleep	(sec) ↦ ()	Sleep for sec seconds (can be a decimal).	sec cannot be omitted.

Constant	Value	Description	Note
bbs.ANSI_RESET	"\x1b[m": string	An ANSI escape string for resetting the graphic attribute of the cursor.
bbs.ESC	"\x1b": string	The ESC character
bbs.userid	<Defaults to "guest">: string	The identifier string of the user
bbs.usernick	<Defaults to "夢之大地訪客">: string	The display name of the user
bbs.sitename	<Defaults to "DreamBBS": string	The name of the site
bbs.interface	"0.201": string	The BBS-Lua API level of the implementation	number in the C implementation.
bbs.NOECHO	0x0: number	The echo value for instructing bbs.getdata to make the input text invisible	Has the same effect as bbs.HIDEECHO in bbslua.lua.
bbs.DOECHO	0x1: number	The default echo value for bbs.getdata	Not a flag, but can be combined with other echo flags.
bbs.LCECHO	0x2: number	The echo flag for instructing bbs.getdata to convert input into lowercase	Can be combined with other echo flags.
bbs.NUMECHO	0x4: number	Instruct bbs.getdata to accept only number digits	Can be combined with others.
bbs.PASSECHO	0x10: number	Instruct bbs.getdata to draw the input text as asterisks.	Can be combined with others.
bbs.HIDEECHO	0x20: number	Instruct bbs.getdata to not drawing the input field at all.	Can be combined with others.

toc library

Constant	Type	Description	Note
toc.interface	string	The required BBS-Lua API level
toc.title	string	Program title
toc.notes	string	Additional notes for the program
toc.author	string	Author information
toc.version	string	Version string assigned by author
toc.date	string	Last modified date
toc.latestref	string	Reference to the file with the latest version of the program	No effect in bbslua.lua

store library

Function	Parameter ↦ Return Value	Description	Note
store.load	(cate: string) ↦ (res: string?, err: string?)	- Load the file for given category as a string. Return nil if fails - When operation fails, err is a string explaining the reason - Otherwise, err is a string containing a file size warning if presents
store.save	(cate: string, str: string) ↦ (res: boolean, err: string?)	- Save a string as the file for given category. Return whether the operation success - The string is truncated to the maximum permitted file size if exceeds - When operation fails, err is a string explaining the reason - Otherwise, err is a string containing a file size warning if presents
store.limit	(cate: string) ↦ (bytes: number)	Get the maximum permitted file size for given category, in bytes
store.iolimit	() ↦ (max: number)	Get the maximum permitted number of times that store.load and store.save may open files

Constant	Value	Description	Note
store.USER	"user": string	The category for per user storage of the program
store.GLOBAL	"global": string	The category for site-wide storage of the program

bit library (Lua BitOp with extension)

Function	Parameter ↦ Return Value	Description	Note
bit.tobit	(x: number) ↦ (res: number)	- Get a range-normalized copy of a number - Not necessary for other bitwise operations	Not in bitlib
bit.cast	(x: number) ↦ (res: number)	An alias to bit.tobit for compatibility with bitlib	Not in BitOp
bit.tohex	(x: number, n: number=8) ↦ (res: string)	- Get an n-digit hexadecimal number string of x - Negative n produces an uppercase hexadecimal number string	Not in bitlib
bit.bnot	(x: number) ↦ (res: number)	Bitwise not
bit.bor	(x1: number, x2: number...) ↦ (res: number)	Bitwise or of all arguments
bit.band	(x1: number, x2: number...) ↦ (res: number)	Bitwise and of all arguments
bit.bxor	(x1: number, x2: number...) ↦ (res: number)	Bitwise xor of all arguments
bit.lshift	(x: number, n: number) ↦ (res: number)	Bitwise left-shift. Use only the lowest 5 bits of n
bit.rshift	(x: number, n: number) ↦ (res: number)	Bitwise logical right-shift. Use only the lowest 5 bits of n
bit.arshift	(x: number, n: number) ↦ (res: number)	Bitwise arithmetic right-shift. Use only the lowest 5 bits of n
bit.rol	(x: number, n: number) ↦ (res: number)	Bitwise left rotation. Use only the lowest 5 bits of n	Not in bitlib
bit.ror	(x: number, n: number) ↦ (res: number)	Bitwise right rotation. Use only the lowest 5 bits of n	Not in bitlib
bit.bswap	(x: number) ↦ (res: number)	Get a copy of x with byte order reversed	Not in bitlib