gu

gu

Gu is a streaming bot makers library that you can pipe your transports to and from.

It has three main features:

• regular expression handlers in a style similar to hubot (but without all those annoying environment variables and coffee-script..)
• hot code reloading of specified files (without the bot having to leave the server)
• streaming input and output allows for easy control, extensibility and transport-less testing of handlers

Usage

Find a library that does the transport you want, say irc-stream:

Create a main file; bot.js:

var gu = require('gu')(scriptPath, files);
var ircStream = require('ircStream')(name, server, {chan: [chan]});

ircStream.pipe(gu).pipe(ircStream);

The script path and the files (relative to the scriptpath) will be watched for changes, and is assumed to contain handlers exported behind a function.

Then, put a file in your scriptpath, love.js, say, and add handlers therein:

module.exports = function (gu) {
  gu.handle(/^what is (\w*)$/, function (say, match) {
    if (match === 'love') {
      say("baby don't hurt me");
    }
  });
};

Then fire up the bot with node bot.js, navigate to the specified server and channel (in ircOpts), and try saying botName: what is love in the channel.

Changing the handler in love.js will result in different behaviour without having to restart bot.js.

A more extensive example is avaiable in the example directory.

Complete examples

The following bots are built on gu:

• cleverbot-irc
• wolfram-irc
• curvefever-bot

Stream Specification

A gu instance expects to have objects written to it, and will new objects readable on the other end.

Therefore, the sensible interface (unless you are doing some weird asymmetrical connection setup), is a Duplex stream in objectMode.

Inputs & Outputs

Expected input objects:

{
  user: String, // unique identifier of user
  channel: String, // unique group chat identifier (if relevant)
  message: String, // raw message to be matched by gu
}

Output objects are identical. As an example an example message from/to irc-stream can look like this { user: 'clux', channel: '#quake', message: 'hi' } for a private message, the channel key is unset.

An optional name property may be set for the convenience of the stream handler (such as xmpp-stream). It is used when doing group chat highlighting without having to necessarily use the larg UID. For IRC it is unused.

Compatible Transports

Best tested: irc-stream.

Early prototype of xmpp-stream also available.

Caveats

What files are reloaded

The script path you specify to gu should only contain the handler functions. If you point the path at your lib dir, then it may reload all the files in that directory when you change one of your handlers.

If you have multiple handler files in your scriptdir, then if one changes, all these files will be reloaded, and any internal state in them will be cleared. To get around this, persist important state elsewhere.

When things can still go wrong

If you save one of the reload-watched files, and there's a syntax error, we will catch this error for you. An exception and a stack trace will be logged and all the handlers from the file with the error will be inactive.

However, it is possible to save a file that looks valid but will have a runtime error, for instance referencing an undefined variable. This we will not guard on (otherwise we'd have to try-catch everything), and your bot will crash. Thus, you should use a fast-response linter to prevent this from happening.

Options

A few options can be passed along to the gu instance as the third parameter, these are:

{
  noReload: Boolean, // disable the hot-reload module (a must for handler tests)
  hotLogging: Boolean, // enable logging from the hot-reload module
  verbose: Boolean // enable regex match log when gu receives messages
}

Logging

Emitted logs are available on the instance as gu.log. They are emitted in the form of smell.

To actually print them out, you should use sulfur as such:

var sulfur = require('sulfur');
sulfur.absorb(gu.log, 'gu');

You can also log from gu handlers by calling the log methods error, warn, or info on gu.log:

gu.handle(/^(.*)$/, function (say, match) {
  gu.log.info("matched the everything handler with", match);
});

Installation

$ npm install gu

Running tests

Install development dependencies and run test command

$ npm install
$ npm test

License

MIT-Licensed. See LICENSE file for details.