irc.sh

As you may have noticed, shazbot is written in bash. Yes that sounds utterly bonkers, but as with any shell script the important code is written in C. You just already have that code installed, even if you didn’t know it!

#!/bin/bash
source irc.sh

Your bot is also itself a bash script (not /bin/sh but bash!), and it uses the shazbot irc.sh library to give you some bot-building functions.

Currently the official location of these libraries is http://zork.net/~nick/shazbot and you can follow along by running:

$ bzr branch http://zork.net/~nick/shazbot

Building the bot has three basic steps

1. Connecting to the server
2. Speaking the IRC protocol
3. Reacting to IRC events with your own code

Connecting to the Server

To connect to the correct IRC port on an IRC server, we set up a bash coprocess. This is like running a command in the background, but getting special file descriptors to talk to its stdin and stdout.

coproc slashnet { socat - OPENSSL:irc.slashnet.org:6697,verify=0,keepalive; }

We’re even using SSL for this one, and if we wanted we could do user certs for OFTC to log in–it’s all in the socat man page.

What? You don’t have socat installed? Okay, well we can do it plain-text, but someone could sniff your traffic:

coproc slashnet { nc -w 300 -i 1 irc.slashnet.org 6667; }

There we go, and notice how we’ve set a timeout of 300 seconds and told it to rate-limit sends to one per second. The nc man page has all kinds of nice TCP options you can use!

You don’t have nc installed either? Wow, you’re not making this easy for me. How about telnet? Can we do telnet?

coproc slashnet { telnet eu.slashnet.org 6667; }

I mean telnet has been around for ages, and it’s not installed by default everywhere these days, but… You’re kidding. Really? You’ve got a modern bash but access to none of these programs? Well, we can do this without them, I suppose…

demobot () {
  # bot logic code goes here!
}

demobot <&${slashnet[0]} >&${slashnet[1]}

demobot () {
  # bot logic code goes here!
}

demobot 6<>/dev/tcp/irc.slashnet.org/6667 <&6 >&6

Speaking the IRC Protocol

To prevent our bot from just connecting and disconnecting, we need to make it speak the IRC protocol to this server. The first thing we need to do is try to log in:

demobot () {
  echo "NICK demobot"
  echo "USER demobot 0 * :I am an IRC bot written in bash!"
}

This bot will also connect and disconnect, but it will take longer. That’s because the server sends it a PING command to make sure it’s really an IRC client before continuing. We need to actually parse the text coming on stdin and send replies on stdout.

demobot () {
  echo "NICK demobot"
  echo "USER demobot 0 * :I am an IRC bot written in bash!"
  while read line; do
    echo "$line" >&2
    irc_parse "$line"
    irc_ping && continue
  done
}

Reacting to IRC events with your own code

Of course a bot that just connects to a server and sits quietly isn’t very interesting. We want to join channels and answer back when users speak to us!

while read line; do
  irc_parse "$line"
  irc_ping && continue
  [[ $IRC_COMMAND == $RPL_ENDOFMOTD ]] && echo "JOIN #shazbot"
done

while read line; do
  irc_parse "$line"
  irc_ping && continue
  case $IRC_COMMAND in
    PING)
      echo "PONG $IRC_TEXT";;
    $RPL_ENDOFMOTD)
      echo "JOIN #shazbot";;
    PRIVMSG)
      [[ $IRC_TEXT =~ 2[^[:digit:]]*4[^[:digit:]]*2 ]] && \
        echo "NOTICE $IRC_CHANNEL :242 sighting!"
      [[ $IRC_TEXT =~ political(ly)?\ correct ]] && \
        echo "PRIVMSG $IRC_CHANNEL :I think you mean \"not racist\", $IRC_SENDER."
      ;;
  esac
done

[[ $IRC_TEXT =~ 2[^[:digit:]]*4[^[:digit:]]*2 ]] && \
  irc_msg $IRC_CHANNEL "242 sighting!"
[[ $IRC_TEXT =~ political(ly)?\ correct ]] && \
  irc_msg -m $IRC_CHANNEL "I think you mean \"not racist\", $IRC_SENDER."

Potato Programming

In some projects, code is just piled on higgledy-piggledy, with everything happening at the top layer. It’s fun at first, but eventually adding features is a chore that nobody relishes.

“Ugh, you mean I have to dig through that mess and hope I put my code in the right place? Never mind.”

Ceremonial Modularity

In other projects, people try to protect against the mess by constructing byzantine module systems¹ with hooks and APIs and reams of standardized auto-generated documentation.

You can guess how fun it is to come to a system like that cold and try to write your first feature:

“Ugh, you mean I have to dig through all that text and hope I used your bits in the right way? Never mind.”

Convention over Configuration

All this talk of “Convention, not Configuration” you hear from Ruby on Rails advocates can sound like so much meaningless architecture-babble at first. But really all it means is that a useful library stays out of your way as much as possible.

At its core, the idea is that instead of giving you a big program that you configure, diving in head-first into dozens of mandatory choices, you’re given bits of code to use or ignore as you wish. So instead of default values, there’s just conventions on how people tend to use the tools provided.

So that’s how shazbot works:

You don’t want to use socat?

Fine, use whatever gets your stdio talking to the right port on the IRC server.

You don’t want to use irc_msg?

Sure, use echo or printf or whatever PRIVMSG construction works best for you.

You don’t want to use bash for responses?

Okay, have your pattern actions run external programs.

You don’t want to use case statements?

Yeah, use whatever flow control construct makes your code clear.

You don’t want to use bash for pattern-matching?

Great, pass the irc_parse info off to your awk or python script, or whatever.

Shazbot is more an approach to designing bots than it is anything in irc.sh. If you’re speaking the IRC protocol over stdio in a vaguely shell-scriptey aggregation of programs, that’s what we are trying to encourage.