[mw-devel] [Git][arthur/mw][master] Update mwjs documentation
Andrew Price
welshbyte at sucs.org
Sun Nov 4 12:52:02 GMT 2018
Andrew Price pushed to branch master at Justin Mitchell / mw
Commits:
61ee2be6 by Andrew Price at 2018-11-04T12:50:29+00:00
Update mwjs documentation
- - - - -
1 changed file:
- mwjs.rst
Changes:
=====================================
mwjs.rst
=====================================
--- a/mwjs.rst
+++ b/mwjs.rst
@@ -1,29 +1,119 @@
-====
-MWJS
-====
-
+==================================
Milliways JavaScript API reference
-----------------------------------
-:Manual section: 7
+==================================
-DESCRIPTION
+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.
+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::
+
+ 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)`
+ Takes a string argument and executes it as a talker command.
+
+`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.
-CONSTANTS
-=========
+`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";``
-The following symbols are defined in the global scope for ``MWJS`` scripts:
+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
+---------
`whoami`
- A string containing the name of the current ``Milliways`` user.
+ 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.
-BIND TYPES
-==========
+Bind Types
+----------
The following constants can be used with the `bind` and `unbind` functions (see below).
@@ -52,73 +142,55 @@ The following constants can be used with the `bind` and `unbind` functions (see
``bind(K_BIND_INPUT, )`` - To be documented.
-FUNCTIONS
-=========
+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).
+ them and displays them (locally). Use `mw.print()` instead.
`exec(str)`
- Takes a string argument and executes it as a talker command.
+ Takes a string argument and executes it as a talker command. Use `mw.exec()`
+ instead.
`say(str)`
- Takes an argument which it sends as a message in the talker.
+ Takes an argument which it sends as a message in the talker. Use `mw.say()`
+ instead.
`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`.
+ currently on the talker. Use `mw.wholist()` instead.
`urlget(url)`
- Takes a URL string, fetches it, and returns the contents of the response.
+ Takes a URL string, fetches it, and returns the contents of the response. Use
+ `mw.urlget()` instead.
`beep(n)`
- Beeps (sends the BEL character to stdout) `n` times (max 5).
+ Beeps (sends the BEL character to stdout) `n` times (max 5). Use `mw.beep()`
+ instead.
`input(prompt)`
Displays the string `prompt` and accepts a line of input from the user, which
- is returned.
+ is returned. Use `mw.input()` instead.
`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
+ terminal window that ``mw`` is occupying. Use `mw.termsize()` instead.
`bind()`
- To be documented.
+ Use `mw.command` and `mw.onevent` instead.
`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.
-
+ Use `delete mw.command.<name>` instead.
View it on GitLab: https://projects.sucs.org/arthur/mw/commit/61ee2be6a23107e10a1d35b993b57f43080c385d
--
View it on GitLab: https://projects.sucs.org/arthur/mw/commit/61ee2be6a23107e10a1d35b993b57f43080c385d
You're receiving this email because of your account on projects.sucs.org.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.sucs.org/pipermail/mw-devel/attachments/20181104/ee821983/attachment-0001.html>
More information about the mw-devel
mailing list