Erlbot
======
A project to teach me erlang, coincidentially also an IRC bot!
Config
======
The bot can be started with erlbot:start/1 which expects a property list of config terms.
If the bot is started with erlbot:start/0 then the file config.erl will be consulted and
it's contents will be used as the configuration property list for erlbot:start/1. Note
that in config.erl you don't enclose the terms in a list: [ ...terms... ]. Simply delimit
terms with a full stop ".".
The config syntax is standard Erlang term notation. All config terms are tuples of two elements, the first being an atom identifying the key, the second being the value: { key, Value }.
Options
-------
IRC Server Address: { host, "example.com" }. Or with a port: { host, { "example.com", 6667 } }.
Bot Owner: { owner, "OwnerNickname" }.
Bot Nickname: { nick, "BotNickname" }.
Default Channels: { channels, [ "#channel1", "#channel2" ] }.
Bot Commands
============
Bot commands are PRIVMSGs sent directly from the Bot Owner to the Bot.
Echo:
-echo foobar
Says foobar back to you. Mainly used as a quick test so see if the bot is still alive.
Join Channel:
-channel join #channel
Joins a channel.
Part Channel:
-channel part #channel
Parts a channel.
List Channels:
-channel list
Returns a list of running channel processes.
Register Plugin:
-plugin register #channel <gen_server callback module>
Spawns a gen_server callback module and registers it with
the channel process.
Raw:
-raw PRIVMSG user :Message
Manually inject IRC protocol into the stream.
Vaguely How it Works
====================
A 'server' process is spawned, this is responsible for handling the socket to the server. Currently it also handles logging in to the IRC server by spawning a login process. This just waits a few seconds then sends the USER/NICK commands. The 'server' reads data from the socket, splits it into lines, then sends those lines individually to the 'bot' process.
On receiving a line, the bot spawns a process to parse it. If the line can't be parsed then the parse process crashes. If the line is successfully parsed then a message is sent back to the bot process containing the parsed packet as an erlang term.
Upon receiving an IRC packet containing a PRIVMSG sent directly from the bot owner to the bot, a bot:handle_command/2 process is spawned and given the packet. If the packet doesn't contain a bot command, then the bot:handle_command/2 process will crash and no action will be taken.
A bot command to join a channel will spawn a new 'channel' process and send a cast to it telling it to join. A channel process will stay alive after you part the channel, letting you keep any registered plugins.
When the bot receives a PRIVMSG sent to a channel then that packet will be relayed to the process handling that channel.
At the moment, all the channel process do is relay the IRC event to the plugins, but the IRC packet isn't sent, instead a simpler, more concise term structure is used.
There is a seperate process per plugin, per channel. Currently they're only spawned through the IRC -plugin register <#channel> <module> command.
Plugins
=======
Plugins are gen_server processes that accept a cast of:
{ ChannelPid, privmsg, FromNick, Message }
Messages can be sent to a channel using:
channel:say( ChannelPid, "message" ).