Add the beginnings of an mwjs scripting reference

====

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.