pirc

πrc

("pie are sea")

A combination IRC daemon / client library for Node.js

WARNING:

πrc is still under development, and not ready for general use yet!

Table of Contents

• Installation
• Introduction
• Server config
• Client config
• Client scripting
• Todo

Installation

npm install pirc

Introduction

πrc is both an IRC daemon, and an IRC client, all rolled into one module. It's written in JavaScript.

Starting your own IRC server is easy:

var Pirc = require('pirc');

var server = new Pirc.Server();

server.listen();

// Server is now listening on port 6667!

So is spawning an IRC client:

var Pirc = require('pirc');

var client = new Pirc.Client('pachet');

client.connectToServer('irc.myserver.com', function(error) {
    if (error) {
        throw error;
    }

    // We're now successfully connected! Yay!

    client.joinChannel('#sysops', function(error) { // JOIN #sysops
        if (error) {
            throw error;
        }

        client.sendMessageToChannel('I have returned!', channel); // PRIVMSG #sysops :I have returned!
    });
});

Server Config

Technically, you don't need to supply any additional options when you create a new server instance:

(new Pirc.Server()).listen();

The above example creates a new server instance, using the default settings, and has it start listening on port 6667.

The default settings are as follows:

Setting name	Default value	Meaning
name	"Pirc"	Displayed to clients upon connecting
hostname	OS.hostname()	Identifies the server to clients and other servers
port	6667	The port the server should listen on
motd	null	The MOTD to show to connecting clients
channel_modes	"biklmnpstv"	The subset of supported channel modes that clients can set
user_modes	"iosw"	The subset of supported user modes that clients can set
max_channels	20	The maximum number of channels a client can join
max_targets	20	The maximum number of targets a client can specify for a message
max_bans	60	The maximum number of ban masks allowed for a given channel
max_parameters	32	The maximum number of parameters allowed for a given command
max_nick_length	32	The maximum allowed client nick length
max_topic_length	307	The maximum allowed channel topic length

You will probably want to override these settings. To do so, you can supply an options object to the Pirc.Server constructor:

var server = new Pirc.Server({
    name:          'πrc',
    hostname:      'irc.myserver.com',
    port:          1234,
    motd:          'Welcome to Burning Garden's IRC server. Be good, and don't be bad!'
    channel_modes: 'bmnpsq',
    user_modes:    'ars'
});

In addition to specifying the port in the options object, you can also just pass it to server.listen() directly:

server.listen(1234);

A list of πrc's supported channel modes, and their meanings, can be found here.

A list of πrc's supported user modes, and their meanings, can be found here.

Client Config

The amount of information needed when instantiating a new client is minimal. In fact, you could just instantiate a client directly, and call connectToServer() without supplying any additional information:

var client = new Pirc.Client(); // The default nick, "pirc", will be used.

client.connectToServer(function(error) { // Will attempt to connect to localhost:6667
    // Do something
});

But I'm guessing you want more flexibility than that. Not a problem. You can override the default nick for your client by passing it directly to the Pirc.Client constructor:

var client = new Pirc.Client('pachet'); // Now the nick "pachet" will be used when connecting to servers

You can also specify additional options when connecting to a specific server, in the form of an options object:

var client = new Pirc.Client();

var options = {
    hostname: 'irc.myserver.com',
    port:     6669,
    nick:     'pachet',
    username: 'pachet',
    realname: 'Pachet'
};

client.connectToServer(options, function(error) {
    // Do something
});

This makes it easy to specify different values for different server connections using the same client.

The default values for the options object when connecting to a server is as follows:

Setting name	Default value	Meaning
nick	"pirc"	Identifies your client on the network, unique to your user
username	"pirc"	Identifies your client on the network, not necessarily unique to you
realname	"Pirc"	Your favorite character on your favorite TV show
hostname	"localhost"	The remote hostname of the server to connect to
port	6667	The remote port of the server to connect to

Client scripting

If you're writing an IRC client using πrc, you probably want some way to programmatically interact with the IRC networks you're connecting to.

Here's an example of a simple bot written using Pirc.Client, just to serve as an illustration of what's possible. More comprehensive documentation can be found below.

var Pirc = require('pirc');

var client = new Pirc.Client();

client.connectToServer('irc.myserver.com', function(error) {
    if (error) {
        throw error;
    }

    // Connect to some initial channels:
    client.joinChannel('#sysops');
    client.joinChannel('#zeldafans');
    client.joinChannel('#seriousbusiness');
});

client.on('message', function(message) {
    var nick = message.getNick();

    if (!nick) {
        // Some messages don't have nicks; ie, server notice messages.
        return;
    }

    // Reply to the message we received:
    client.respondToMessage(message, 'What in the world are you talking about?');

    client.sendWhoisQueryForNick(nick, function(error, user) {
        if (error) {
            throw error;
        }

        // Crawl our way throughout the network:
        user.getChannelNames().forEach(client.joinChannel, client);
    });
});

Todo

There's still a fair amount of work I need to do. Namely:

• SSL support
• Services (ie, NickServe)
• Actual server <-> server connections
• Authentication