mwjs.rst 5.04 KB
Newer Older
Andrew Price's avatar
Andrew Price committed
1
==================================
2
Milliways JavaScript API reference
Andrew Price's avatar
Andrew Price committed
3
==================================
4

Andrew Price's avatar
Andrew Price committed
5
Description
6 7 8 9
===========

This document describes the JavaScript scripting API provided by the Milliways
client, ``mw``. The standard interfaces specified by the ECMAscript standards
Andrew Price's avatar
Andrew Price committed
10 11 12 13 14 15 16 17 18
are also available in ``mwjs`` scripts but are not documented here.

Note that everything that isn't defined under the ``mw`` namespace is
considered deprecated.

Loading Scripts
===============

``mwjs`` scripts can be loaded by adding::
19

Andrew Price's avatar
Andrew Price committed
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
    include path/to/file.js

to your ``~/.mwrc``. The path is relative to your home directory.

The `mw` Namespace
==================

The following symbols are defined in the `mw` namespace for ``mwjs`` scripts:

Functions
---------

`mw.print(args...)`
  Takes a variable number of arguments. Coerces them to strings, concatenates
  them and displays them locally.

`mw.exec(str)`
37
  Takes a string argument and executes it as a talker command. Preceeding '.' not needed.
Andrew Price's avatar
Andrew Price committed
38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67

`mw.say(str)`
  Takes an argument which it sends as a message in the talker.

`mw.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`.

`mw.urlget(url)`
  Takes a URL string, fetches it, and returns the contents of the response.

`mw.beep(n)`
  Beeps (sends the BEL character to stdout) `n` times (max 5).

`mw.input(prompt)`
  Displays the string `prompt` and accepts a line of input from the user, which
  is returned.
68

Andrew Price's avatar
Andrew Price committed
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
`mw.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

`mw.whoami()`
   Accepts no arguments. Returns the user's current username.

Special Objects
---------------

`mw.onevent`
   This is an array which event handler functions can be added to using
   ``mw.onevent.push(handler)``. The handler must accept an event object with a
   `data` property containing the properties relating to the particular event
   type. Event handlers can suppress the default output for events by returning
   ``false``.

`mw.command`
   This object allows user commands to be defined. To define the command
   ``,boop`` with handler function ``boopCmd()`` use ``mw.command.boop =
   boopCmd;``

`mw.store`
   This object allows easy persistent storage and lookup of basic key-value
   pairs in a database. To store value "bar" with key "foo", either use
   ``mw.store.foo = "bar";`` or ``mw.store["foo"] = "bar";``
98

Andrew Price's avatar
Andrew Price committed
99 100 101 102 103 104 105 106 107 108
Deprecated Interfaces
=====================

The interfaces described in this section are deprecated. They were direct
translations of the old mwscript API and do not support idiomatic javascript.
In all cases there should be an easier-to-use equivalent interface in the new
API documented above.

Constants
---------
109 110 111

`whoami`

Andrew Price's avatar
Andrew Price committed
112 113
  A string containing the name of the current ``Milliways`` user. This doesn't
  change even if the user's username changes. Use `mw.whoami()` instead.
114

Andrew Price's avatar
Andrew Price committed
115 116
Bind Types
----------
117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144

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_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_ALIAS`

  ``bind(K_BIND_ALIAS, )`` - To be documented.

`K_BIND_INPUT`

  ``bind(K_BIND_INPUT, )`` - To be documented.

Andrew Price's avatar
Andrew Price committed
145 146
Functions
---------
147 148 149 150 151 152

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
Andrew Price's avatar
Andrew Price committed
153
  them and displays them (locally). Use `mw.print()` instead.
154 155 156

`exec(str)`

Andrew Price's avatar
Andrew Price committed
157 158
  Takes a string argument and executes it as a talker command. Use `mw.exec()`
  instead.
159 160 161

`say(str)`

Andrew Price's avatar
Andrew Price committed
162 163
  Takes an argument which it sends as a message in the talker. Use `mw.say()`
  instead.
164 165 166 167

`wholist()`

  Accepts no arguments. Returns an array of objects representing the users
Andrew Price's avatar
Andrew Price committed
168
  currently on the talker. Use `mw.wholist()` instead.
169 170 171

`urlget(url)`

Andrew Price's avatar
Andrew Price committed
172 173
  Takes a URL string, fetches it, and returns the contents of the response. Use
  `mw.urlget()` instead.
174 175 176

`beep(n)`

Andrew Price's avatar
Andrew Price committed
177 178
  Beeps (sends the BEL character to stdout) `n` times (max 5). Use `mw.beep()`
  instead.
179 180 181 182

`input(prompt)`

  Displays the string `prompt` and accepts a line of input from the user, which
Andrew Price's avatar
Andrew Price committed
183
  is returned. Use `mw.input()` instead.
184 185 186 187

`termsize()`

  Accepts no arguments. Returns an object representing the dimensions of the
Andrew Price's avatar
Andrew Price committed
188
  terminal window that ``mw`` is occupying. Use `mw.termsize()` instead.
189 190 191

`bind()`

Andrew Price's avatar
Andrew Price committed
192
  Use `mw.command` and `mw.onevent` instead.
193 194 195

`unbind()`

Andrew Price's avatar
Andrew Price committed
196
  Use `delete mw.command.<name>` instead.