circus

An event driven IRC gem without a DSL or any EOF magick

Author

Tim Sjoberg (bedlamp AT gmail.com)

Quick How-to

Install the gem

gem install circus

How to connect

require 'circus'

irc = Circus::IRC.new
irc.connect

IRC#connect is a blocking call. It will only return when you’re disconnected

IRC#new takes a bunch of config parameters in the form of a hash, their names should be self explanatory

:server
:port
:nick
:username
:realname
:sendspeed #length of time between messages. this is for flood protection. default is 0.5 seconds
:timeout #If this amount of time, in seconds, is reached, circus considers itself disconnected
:eol #the line delimiter. you should hopefully never need to change this
:debug #if this is set to true, circus will output everything it does in stdout
:password #this is the password for the irc server if there is one. default is unset

For example

irc = Circus::IRC.new :server => "irc.freenode.org", :nick => "Circus-IRC"

Alternatively, you can set the values after instantiation by calling #config_value=, for example

irc = Circus::IRC.new
irc.nick = "NewNick"
irc.server = "another.server.com"

To send stuff, you have a bunch of methods at your disposal. Each given with example parameters

irc.action "#circus", "jumps up and down" #does a ctcp ACTION, or /me in your irc client
irc.ctcp "user", "VERSION" #does a normal ctcp and puts in the \001s for you
irc.ctcp_reply "user", "VERSION Ruby using Circus-IRC 0.0.0"
irc.join "#circus"
irc.kick "#circus", "user", "no noobs allowed" #third parameter can be left out
irc.mode "#circus", "+o", "awesome_user" #third parameter optional. For example
irc.mode "Circus-IRC", "+B"
irc.nick "Circus-IRC"
irc.notice "user", "message"
irc.part "#circus"
irc.pass "password" #you shouldn't need to use this. use the password config value
irc.pong "value" #you also never need to use this. this is already handled
irc.privmsg "#circus", "Hello"
irc.quit "reason"
irc.raw "DCCALLOW +user" #for all those pesky additions
irc.topic "#circus", "New topic for channel #circus"
irc.user "user 0 * realname" #again, you shouldn't need this. use the config values

As previously mentioned, it is event driven. Before calling connect, you can subscribe to any number of events, or multiple times to the same event. For a full list look in lib/irc/commands.rb. You can pass subscribe the string or the symbol version, for example

irc.subscribe(:ENDOFMOTD) do
  irc.join "#circus"
end

or

irc.subscribe("376") do
  irc.join "#circus"
end

You are going to need to know how many arguments a block is expecting if you are going to use them. Unfortunately the only way to this is to know the irc protocol, or trial and error. As an example, to create an echo bot (in channels only):

irc.subscribe(:PRIVMSG) do |message, sender, receiver|
  if receiver =~ /^#/
    irc.privmsg receiver, message
  end
end

Disclaimer

This gem is not designed to make it really easy to write irc bots, its designed to make it really easy to build a framework to create irc bots. This gem has been tested working in ruby 1.9

License

This software is distributed under the BEER-WARE license. See LICENSE for details.