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');
};

API

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

setName(name)

####Send a command####

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

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

send('hook_server', 'joined')

The first argument is the type of event (either hook_server, hook_message or hook_command). The second argument is the is the subtype of the event. For example, if the type is hook_command, then the subtype might be kick or msg.

####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 or subtype 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 connected to a server or got kicked from a room)
* **message** - anything that gets printed on the screen (e.g. the MOTD)

For example, an event triggered by a private message being displayed might look like this:
```javascript
event = {
  type: 'message',
  name: 'privmsg',
  context: {
    server: 'irc.freenode.net',
    channel: '#circ'
  }
  args: [
    'noah', // from
    'events are exciting!' //message
  ]
}
```

A full list of message events can be found in the `_handlers` object of [irc_message_handler](https://github.com/flackr/circ/blob/master/src/chat/irc_message_handler.coffee).

A full list of server events can be found in the `onServerEvent()` function of [chat](https://github.com/flackr/circ/blob/master/src/chat/chat.coffee).

A full list of command events can be found in the `_init` function of [user_command_handler](https://github.com/flackr/circ/blob/master/src/chat/user_command_handler.coffee).

## 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. Because the script runs in an iframe, it communicates with the application asynchronously using window.postMessage(). This complicates the code slightly, but has no effect on performance.