Scripting

Scripting commands

/install installs a script from the local file system.
/scripts lists the names of all currently running scripts. The script name can be set with setName().
/uninstall <name> uninstalled the script with the given name.

Example

The following script creates a custom “/dance” command that outputs “(>'-')> <('-'<) ^(' - ')^ <('-'<) (>'-')>” when typed.

setName('/dance');
send('hook_command', 'dance');
onMessage = function(e) {
 dance = "(>'-')> <('-'<) ^(' - ')^ <('-'<) (>'-')>";
 send(e.context, 'command', 'say', dance);
 propagate(e, 'none');
};

Implementation

Loading

Scripts are loaded for the first time from the local file system using chrome.fileSystem. Once a script is loaded it is saved to a persistent local storage and automatically loaded each time the program starts.

Sandboxing

The script source code is passed to a sandboxed iframe, which calls eval(). This prevents the script from accessing the IRC window object and chrome.* APIs. See full details here.

Running

The script and IRC client communicate using window.postMessage(). The contents of the passed messages are described below.

API

####Set the script's name####

setName(name)

Commands

####Send a command####

send(opt_context, type, name, args...)

####Register to receive a notification on a certain event####

send('hook_server', 'joined')

####Send a command as if the user typed it####

send(context, 'command', 'say', 'hello world!')
```
This is treated as if the user typed "/say hello world!"

####Stop an event from being received by the client####
```javascript
propagate(receivedEvent, 'none')
```

####Allow an Event to be received by the client####
```javascript
propagate(receivedEvent, 'all')
```
Note: propagate should be called every time an event is received

### Events
To listen to events, define an onMessage function
```javascript
onMessage = function (event) { // code here };
```

Events have the following fields
* **type** - the kind of event (either “command”, “server” or “message”)
* **name** - the name of the event (e.g. “kick”, “joined”, “nickinuse”)
* **context** - where the event happened
  * **server** - (e.g. “irc.freenode.net”)
  * **channel** - (e.g. “#bash”)
* **args** - a variable length array of any arguments (e.g. the text to print on /say)

There are four types of events
* **command** - a command is entered (e.g. “/kick #sugarman”)
* **server** - server related activity (e.g. we got kicked from a room)
* **message** - anything that gets printed on the screen (e.g. the MOTD)
* **ui** - anything that relates to the user interface (e.g. a notification was clicked on)