titanous-isaac

= Isaac - the smallish DSL for writing IRC bots

== Features

• Wraps parsing of incoming messages and raw IRC commands in simple constructs.
• Hides all the ugly regular expressions of matching IRC commands. Leaves only the essentials for you to match.
• Takes care of dull stuff such as replying to PING-messages and avoiding excess flood.

== Getting started An Isaac-bot needs a few basics: require 'isaac' configure do |c| c.nick = "AwesomeBot" c.server = "irc.freenode.net" c.port = 6667 end That's it. Run ruby bot.rb and it will connect to the specified server.

=== Connecting After the bot has connected to the IRC server you might want to join some channels: on :connect do join "#awesome_channel", "#WesternBar" end

=== Responding to messages Joining a channel and sitting idle is not much fun. Let's repeat everything being said in these channels:

on :channel do msg channel, message end

Notice the +channel+ and +message+ variables. Additionally +nick+ and +match+ is available for channel-events. +nick+ being the sender of the message, +match+ being an array of captures from the regular expression:

on :channel, /^quote this: (.*)/ do msg channel, "Quote: '#{match[0]}' by #{nick}" end

If you want to match private messages use the +on :private+ event:

on :private, /^login (\S+) (\S+)/ do username = match[0] password = match[1] # do something to authorize or whatevz. msg nick, "Login successful!" end

=== Defining helpers Helpers should not be defined in the top level, but instead using the +helpers+-constructor:

helpers do def rain_check(meeting) msg nick, "Can I have a rain check on the #{meeting}?" end end

on :private, /date/ do rain_check("romantic date") end

=== Errors, errors, errors Errors, as specified by RFC 1459, can be reacted upon as well. If you e.g. try to send a message to a non-existant nick you will get error 401: "No such nick/channel".

on :error, 401 do # Do something. end

Available variables: +nick+ and +channel+.

=== Send commands from outside an event (not implemented in Shaft atm) You might want to send messages, join channels etc. without it strictly being the result of an on()-event, e.g. send a message every time a RSS feed is updated or whatever. You can use +Isaac.execute+ for that, and all your normal commands, +msg+, +join+, +topic+ etc. will be available:

class K def smoke(brand) Isaac.execute { msg "harryjr", "you should smoke #{brand} cigarettes" } end end

on :connect do k = K.new k.smoke("Lucky Strike") end

== Contribute The source is hosted at GitHub: http://github.com/ichverstehe/isaac

== License The MIT. Google it.