Scripting

Sysops can add their own screens and features to the BBS in JavaScript. A script draws the same kinds of screen as the rest of the BBS (menus, tables, forms, panels, messages and the editor), so it works on every terminal: a text terminal in ANSI, ASCII or PETSCII, a RIP terminal (where menus become buttons), and a 3270. A script acts as its caller, with the caller's access.

; bbs.conf
[general]
scripts_dir = /etc/bbs/scripts

[menu main]
o = script:oneliners One-liners
p = script:poll Today's poll

A menu item script:NAME runs NAME.js from scripts_dir (names are lower-case letters, digits, _ and -). A logon.js there runs after every login, before the menus. bbs check compiles every script, and refuses a configuration if a script does not compile or a menu names a script that does not exist. A script changed while the BBS runs is compiled again the next time it runs. scripts.sample has two scripts to start from: one-liners and a poll.

What a script is¶

Scripts run in goja, which supports ECMAScript 5.1 and much of ECMAScript 6 (let, arrow functions, classes, Map, template strings), in strict mode. A script cannot reach files, the network, processes or timers; it has only the objects described below.

A script may compute for up to two seconds between one screen and the next (time the caller spends at a screen does not count). Beyond that it is stopped and the caller is told. A script that fails is logged and the caller is told (a sysop is also told why). If the caller hangs up or goes idle, the script ends, whatever it catches. exit() ends a script early.

// a guestbook in eight lines
var lines = data.get("lines") || [];
var k = ui.menu({title: "Guestbook", intro: lines.slice(-10),
    items: [{key: "s", label: "Sign it"}, {key: "q", label: "Quit"}]});
if (k === "S") {
    var v = ui.form({title: "Sign", fields: [{name: "line", label: "Your words", width: 60}]});
    if (v && v.line) data.set("lines", lines.concat(user.name + ": " + v.line).slice(-100));
}

ui: the screens¶

Function	Returns	Notes
`ui.menu({title, intro, items: [{key, label}], prompt, screen})`	the key chosen (upper case), `""`, or `ui.BACK` (a 3270's PF3)	`intro`: lines before the items; `screen`: a display file in their place
`ui.table({title, note, columns: [{title, width, right, wide}], rows, empty, pick, prompt, actions, more, less})`	`{action, row, num, text}`	`rows`: arrays of cells, or `{num, cells, mark, hot}`; `pick` makes rows choosable (`action` is `ui.PICK`, `row` the index, -1 for a number not shown, `num` what was typed); `wide` columns only on screens of 60 columns or more; `more`/`less` say there are pages after and before (`ui.MORE`, `ui.LESS`)
`ui.message({where, from, to, subject, date, body, actions, default, quit})`	the action chosen
`ui.form({title, intro, fields: [{name, label, prompt, width, secret, value}], submit})`	the values by name, or `null` if the caller gave up	one question a field on a text terminal, one screen on a 3270
`ui.panel({title, lines, actions})`	the action chosen, `ui.BACK`, or `""`
`ui.edit({title, to, subject, body, quote})`	`{to, subject, body}`, or `null`	the full-screen editor, the line editor or the 3270's; `quote` is for the quote window
`ui.confirm(question, default)`	true or false
`ui.say(text, tone)`		a line now (a 3270: on the next screen's message line)
`ui.show(title, lines)`		lines until read
`ui.screen(name)`	whether there was one	a display file of `screens_dir`
`ui.kind`, `ui.pageSize`, `ui.narrow`		`"text"` or `"3270"`; rows a table shows; under 60 columns

Lines are strings (\n starts a new line) or objects {label, text, tone, bar}, which give a label and its value, a tone (plain, dim, bright, good, bad or warn), and a bar from 0 to 1. Actions are {id, label, key, pf, short}: key is the key on a text terminal, pf is the PF key on a 3270 (an action without one does not appear on a 3270), and short is its name on the 3270's key line. On a text terminal, Q (or Enter at an empty prompt) goes back; on a 3270, PF3 goes back.

The BBS¶

Object	What it gives
`bbs.name`, `bbs.sysop`, `bbs.location`, `bbs.log(text)`	the system; a line in its log
`user.id`, `.name`, `.location`, `.level`, `.flags`, `.sysop`, `.calls`, `.posts`, `.since`, `.lastCall`, `user.has(require)`	the caller; `has` takes an access requirement such as `"20 A"` (level 20 or more, and flag A)
`node.number`, `node.doing(text)`, `node.who()`, `node.message(n, text)`	the caller's node: what Who's online says they are doing; the nodes; a line to a node
`msg.areas()`, `msg.list(area, after, limit)`, `msg.get(id)`	the message areas the caller reads, their messages (up to 200 at a time, from after an id), one message (`null` if not theirs to read)
`msg.post(area, {to, subject, body, replyTo})`, `msg.mail({to, subject, body})`	post (the message's id) and mail, as the caller: refusals are thrown
`data.get(name)`, `data.set(name, value)`, `data.remove(name)`, `data.keys(prefix)`	what the script keeps for everyone: any JSON value up to 64 KB under a name of up to 100 characters, 1000 names
`data.user.get` ...	the same, for the caller alone (100 names)
`console.log(...)`	the BBS's log

A script's data is kept in the database (script_data) under the script's name, so a renamed script starts afresh. A user's data is deleted with their account.

See also: Customization, Development