docs.md

Documentation

Table of Contents

1. API
   • Events
   • Client
2. Writing Plugins
3. Debugging

1. API

---

Events

• data (msg) parsed IRC message
• message (event) on PRIVMSG
• notice (event) on NOTICE
• invite (event) on INVITE
• names (event) on RPL_NAMREPLY
• topic (event) on TOPIC
• away (event) on RPL_AWAY
• quit (event) on QUIT
• join (event) on JOIN
• part (event) on PART
• kick (event) on KICK
• mode (event) on MODE
• motd (event) on RPL_ENDOFMOTD
• nick (event) on NICK
• welcome (nick) on RPL_WELCOME
• whois (event) on RPL_ENDOFWHOIS
• errors (event) on ERR*_
• pong (event) on PONG

Client

Given a stream from net or tls or another network source, construct an IRC client.

var client = irc(stream);

.pass(pass)

Used at the beginning of connection to specify a 'connection password' for servers requiring a auth.

.nick(nick)

Specify an string irc nick for the user.

.user(username, realname)

Used at the beginning of connection to specify the username and realname of a new user.

.invite(name, channel)

Send an invite to name, for a channel.

.send(target, msg)

Send a msg to the target user or channel.

.action(target, msg)

Send an ACTION msg to the target user or channel. Example output: * erming slaps tj around a bit with a large trout

.notice(target, msg)

Send a NOTICE msg to the target user or channel.

.ctcp(target, msg)

Send a CTCP notice to the target user.

.join(channel, key)

Send a JOIN command for the user to join channel with optional key.

.part(channel, msg)

Send a PART command for the user to part channel with optional msg.

.names(channel, callback)

List names of users in channel, calling callback with (error, names).

.away(message)

Set the user's away message to message.

.topic(channel, topic)

Get channel topic or set the topic to topic.

.kick(channels, nicks, msg)

Kick nick(s) from channel(s) with optional msg.

.oper(name, password)

Used to obtain operator privileges. The combination of name and password are required to gain Operator privileges. Upon success, a 'mode' event will be emitted.

.mode(target, flags, params)

Used to set a user's mode or channel's mode for a user.

client.mode('cmilhench', '-o');
// cmilhench 'deopping' himself.

client.mode('#channel', '+o', 'name');
// give 'chanop' privileges to name on channel #channel.

.quit(msg)

Disconnect from the server with optional msg.

.whois(target, mask, callback)

Used to query information about particular user.

2. Writing Plugins

---

Plugins are simply functions that accept the IRC client as an argument. With this you can define methods, listen on events and interact with the client. For example here's a logger plugin that outputs to stdout:

function logger() {
  return function(irc){
    irc.stream.pipe(process.stdout);
  }
}

Then .use() it like so:

var client = irc(stream);
client.use(logger());

Returning a function like logger() instead of logger is optional, however it's useful to use a closure when passing options, and to keep the interface consistent with plugins that do accept options, for example:

function logger(stream) {
  return function(irc){
    irc.stream.pipe(stream);
  }
}

client.use(logger(process.stdout));

Here's a slightly more complex example of a PONG plugin responding to PING messages:

function pong(){
  return function(irc){
    irc.on('data', function(msg){
      if ('PING' != msg.command) return;
      irc.write('PONG :' + msg.trailing);
    });
  }
}

3. Debugging

---

Enable debug output:

$ DEBUG=qbirc node script.js
  qbirc message NOTICE :asimov.freenode.net NOTICE * :*** Looking up your hostname... +0ms
  qbirc message NOTICE :asimov.freenode.net NOTICE * :*** Checking Ident +119ms
  qbirc message NOTICE :asimov.freenode.net NOTICE * :*** Couldn't look up your hostname +1ms
  ...

Enable debug output for a specific plugin:

$ DEBUG=qbirc:names node test.js
  qbirc:names add #luna-lang ["tjholowaychuk","ramitos","zehl","yawnt","juliangruber"] +0ms
  qbirc:names emit "names" for #luna-lang +3ms

Enable output of "raw" slate-irc-parser level debug info:

$ DEBUG=slate-irc-parser node test.js
  slate-irc-parser line ':rothfuss.freenode.net NOTICE * :*** Looking up your hostname...' +0ms
  slate-irc-parser message {"prefix":"rothfuss.freenode.net","command":"NOTICE","params":"*","trailing":"*** Looking up your hostname...","string":":rothfuss.freenode.net NOTICE * :*** Looking up your hostname..."} +2ms
  slate-irc-parser line ':rothfuss.freenode.net NOTICE * :*** Checking Ident' +450ms
  slate-irc-parser message {"prefix":"rothfuss.freenode.net","command":"NOTICE","params":"*","trailing":"*** Checking Ident","string":":rothfuss.freenode.net NOTICE * :*** Checking Ident"} +0ms