Commit 5f0e093c authored by Andrew Price's avatar Andrew Price

Add the beginnings of an mwjs scripting reference

This can be processed into various formats, e.g. a manpage using

  $ rst2man mwjs.rst mwjs.7
parent d9f1ebb9
Pipeline #371 passed with stage
in 7 minutes and 28 seconds
====
MWJS
====
Milliways JavaScript API reference
----------------------------------
:Manual section: 7
DESCRIPTION
===========
This document describes the JavaScript scripting API provided by the Milliways
client, ``mw``. The standard interfaces specified by the ECMAscript standards
are also available in ``MWJS`` scripts but are not documented here.
CONSTANTS
=========
The following symbols are defined in the global scope for ``MWJS`` scripts:
`whoami`
A string containing the name of the current ``Milliways`` user.
`K_BROADCAST`
A type specifier to be used in `rpc()` and `ipc()` calls (see below).
BIND TYPES
==========
The following constants can be used with the `bind` and `unbind` functions (see below).
`K_BIND_EVENT`
``bind(K_BIND_EVENT, handler)`` hooks a user-defined function named in the
string `handler` to be called when certain events occur.
`K_BIND_IPC`
``bind(K_BIND_IPC, )`` - To be documented.
`K_BIND_ONOFF`
``bind(K_BIND_ONOFF, )`` - To be documented.
`K_BIND_FORCE`
``bind(K_BIND_FORCE, )`` - To be documented.
`K_BIND_SHUTDOWN`
``bind(K_BIND_SHUTDOWN, )`` - To be documented.
`K_BIND_RPC`
``bind(K_BIND_RPC, )`` - To be documented.
`K_BIND_ALIAS`
``bind(K_BIND_ALIAS, )`` - To be documented.
`K_BIND_INPUT`
``bind(K_BIND_INPUT, )`` - To be documented.
FUNCTIONS
=========
The following functions are defined in the global scope of ``MWJS`` scripts.
`print(str, ...)`
Takes a variable number of arguments. Coerces them to strings, concatenates
them and displays them (locally).
`exec(str)`
Takes a string argument and executes it as a talker command.
`say(str)`
Takes an argument which it sends as a message in the talker.
`wholist()`
Accepts no arguments. Returns an array of objects representing the users
currently on the talker. The objects contain the following properties:
- username
- room
- idle
- chatmodes
- protection_level
- protection_power
- chatprivs
- doing
- since
Note that the wholist is currently not guaranteed to be available on joining
the talker and so the value returned from `wholist()` could be `undefined`.
`rpc()`
To be documented.
`ipc()`
To be documented.
`urlget(url)`
Takes a URL string, fetches it, and returns the contents of the response.
`beep(n)`
Beeps (sends the BEL character to stdout) `n` times (max 5).
`input(prompt)`
Displays the string `prompt` and accepts a line of input from the user, which
is returned.
`termsize()`
Accepts no arguments. Returns an object representing the dimensions of the
terminal window that ``mw`` is occupying. The object's properties are:
- width
- height
`bind()`
To be documented.
`unbind()`
To be documented.
BUGS
====
The current API is a naïve port of the old MWScript API and so does not reflect best practice design decisions.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment