[mw-devel] [Git][arthur/mw][master] Add the beginnings of an mwjs scripting reference

[Andrew Price]

Andrew Price pushed to branch master at Justin Mitchell / mw


Commits:
5f0e093c by Andrew Price at 2017-11-16T23:23:27+00:00
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

- - - - -


1 changed file:

- + mwjs.rst


Changes:

=====================================
mwjs.rst
=====================================
--- /dev/null
+++ b/mwjs.rst
@@ -0,0 +1,144 @@
+====
+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.
+



View it on GitLab: https://projects.sucs.org/arthur/mw/commit/5f0e093c24f2326e122268b28bedbf4991533a63

---
View it on GitLab: https://projects.sucs.org/arthur/mw/commit/5f0e093c24f2326e122268b28bedbf4991533a63
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/20171116/8cade2e0/attachment-0001.html>