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, like.js, say, and add handlers therein:

module.exports = function (gu) {
  gu.handle(/^i like your (\w*)$/, function (say, what) {
    say('i has ' + what + ' :O');
  });
};

Then fire up the bot with node bot.js, navigate to the specified server and channel (in ircOpts), and try saying botName: i like your charisma in the channel.

Changing the handler in like.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 personal bots are all 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
  message: String, // raw message to be matched by gu
}

Output objects are identical. The user property is passed stright through and is can be anything as long as it can be used to again identify the user to send the response to on the other end. For irc-stream it is either the string: "#chan:user" for a channel message or "user" for a personal message.

An optional name property may be set on the input for the convenience of gu handlers - this name will be passed through to the handlers as the last argument and is assumed to be human readable.

Future

Alternative transport modules.

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 lint on save 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
}

Installation

$ npm install gu --save

Running tests

Install development dependencies

$ npm install

Run the tests

$ npm test

License

MIT-Licensed. See LICENSE file for details.