rhuidean 0.2.1

data/README

@@ -0,0 +1,17 @@
+#
+# rhuidean: a small IRC client library
+# README: at-a-glance documentation
+#
+# Copyright (c) 2004-2009 Eric Will <rakaur@malkier.net>
+# Copyright (c) 2003-2004 shrike development team
+#
+
+This repository contains a simple, quick IRC client library. If you have a
+decent understanding of IRC and want to control most of the IRC events
+yourself this is very easy and quick to pick up. The library handles all of
+the socket code and sets up a simple event handling system for IRC events.
+
+It's not very well documented yet, but I'm still working on it.
+
+The code itself is documented. Run `rake rdoc` and check out the doc/ directory.
+

data/lib/rhuidean.rb

@@ -0,0 +1,11 @@
+#
+# rhuidean: a small, lightweight IRC client library
+# lib/rhuidean.rb: IRC client library
+#
+# Copyright (c) 2003-2010 Eric Will <rakaur@malkier.net>
+#
+
+# Import required rhuidean modules.
+%w(client event methods numeric timer).each do |m|
+    require 'rhuidean/' + m
+end

data/lib/rhuidean/client.rb

@@ -0,0 +1,445 @@
+#
+# rhuidean: a small, lightweight IRC client library
+# lib/rhuidean/client.rb: IRC::Client class
+#
+# Copyright (c) 2003-2010 Eric Will <rakaur@malkier.net>
+#
+
+# Import required Ruby modules.
+%w(logger socket).each { |m| require m }
+
+module IRC
+
+# The IRC::Client class acts as an abstract interface to the IRC protocol.
+class Client
+    ##
+    # constants
+    VERSION = '0.2.1'
+
+    ##
+    # instance attributes
+    attr_accessor :server,  :port,      :password, :debug,
+                  :nickname, :username, :realname, :bind_to
+
+    # Our TCPSocket.
+    attr_reader   :socket, :channels
+
+    # A simple Exeption class.
+    class Error < Exception
+    end
+
+    #
+    # Creates a new IRC::Client object. If there is a block given, passes
+    # itself to the block for pretty attribute setting.
+    # ---
+    # <tt>client = IRC::Client.new do |c|
+    #     c.server   = 'irc.malkier.net'
+    #     c.port     = 6667
+    #     c.password = 'partypants'
+    #     c.nickname = 'rakaur'
+    #     c.username = 'rakaur'
+    #     c.realname = 'watching the weather change'
+    #     c.bind_to  = '10.0.1.20'
+    #
+    #     c.logger    = Logger.new($stderr)
+    #     c.debug     = false
+    # end
+    #
+    # t = Thread.new { client.io_loop }
+    # Thread.list.each { |t| t.join unless t == Thread.main } # or similar...
+    # [...]
+    # client.quit("IRC quit message!")
+    # client.exit
+    # ---
+    # returns:: +self+
+    #
+    def initialize
+        # Is our socket dead?
+        @dead      = false
+        @connected = false
+
+        # List of channels we're on
+        @channels = []
+
+        # Received data waiting to be parsed.
+        @recvq = []
+
+        # Data waiting to be sent.
+        @sendq = []
+
+        # Our event queue.
+        @eventq = EventQueue.new
+
+        # Our Logger object.
+        @logger  = Logger.new($stderr)
+        @debug   = false
+
+        # If we have a block let it set up our instance attributes.
+        yield(self) if block_given?
+
+        # Set up event handlers.
+        set_default_handlers
+
+        self
+    end
+
+    #######
+    private
+    #######
+
+    #
+    # Sets up some default event handlers to track various states and such.
+    # ---
+    # returns:: +self+
+    #
+    def set_default_handlers
+        on(:read_ready)  { read  }
+        on(:write_ready) { write }
+        on(:recvq_ready) { parse }
+        on(:dead) { self.dead = true }
+
+        on(Numeric::RPL_WELCOME) { log("connected to #@server:#@port") }
+
+        on(:PING) { |m| raw("PONG :#{m.target}") }
+
+        on(:JOIN) do |m|
+            @channels << m.target if m.origin =~ /^(#{@nickname})\!(.+)\@(.+)$/
+        end
+
+        on(:PART) do |m|
+            if m.origin =~ /^(#{@nickname})\!(.+)\@(.+)$/
+                @channels.delete(m.target)
+            end
+        end
+
+        on(:KICK) do |m|
+            @channels.delete(m.target) if m.params[0] == @nickname
+        end
+
+        on(:exit) do |from|
+            log("exiting via #{from}...")
+            Thread.exit
+        end
+
+        self
+    end
+
+    #
+    # Verifies all required attributes are set.
+    # ---
+    # raises:: IRC::Client::Error if tests fail
+    # returns:: +self+ if tests pass
+    #
+    def verify_attributes
+        raise(Error, 'need a server to connect to')     unless server
+        raise(Error, 'need a port to connect to')       unless port
+        raise(Error, 'need a nickname to connect with') unless nickname
+        raise(Error, 'need a username to connect with') unless username
+        raise(Error, 'need a realname to connect with') unless realname
+
+        self
+    end
+
+    #
+    # Takes care of setting some stuff when we die.
+    # ---
+    # bool:: +true+ or +false+
+    # returns:: +nil+
+    #
+    def dead=(bool)
+        if bool == true
+            log("lost connection to #@server:#@port")
+            @dead      = Time.now.to_i
+            @socket    = nil
+            @connected = false
+        end
+    end
+
+    #
+    # Called when we're ready to read.
+    # ---
+    # returns:: +self+
+    #
+    def read
+        begin
+            ret = @socket.readpartial(8192)
+        rescue Errno::EAGAIN
+            retry
+        rescue EOFError
+            ret = nil
+        end
+
+        unless ret
+            @eventq.post(:dead)
+            return
+        end
+
+        # This passes every "line" to our block, including the "\n".
+        ret.scan(/(.+\n?)/) do |line|
+            line = line[0]
+
+            # If the last line had no \n, add this one onto it.
+            if @recvq[-1] and @recvq[-1][-1].chr != "\n"
+                @recvq[-1] += line
+            else
+                @recvq << line
+            end
+        end
+
+        if @recvq[-1] and @recvq[-1][-1].chr == "\n"
+            @eventq.post(:recvq_ready)
+        end
+
+        self
+    end
+
+    #
+    # Called when we're ready to write.
+    # ---
+    # returns:: +self+
+    #
+    def write
+        begin
+            # Use shift because we need it to fall off immediately.
+            while line = @sendq.shift
+                line += "\r\n"
+                debug(line)
+                @socket.write(line)
+            end
+        rescue Errno::EAGAIN
+            retry
+        end
+    end
+
+    # Note that this doesn't match *every* IRC message,
+    # just the ones we care about. It also doesn't match
+    # every IRC message in the way we want. We get what
+    # we need. The rest is ignored.
+    #
+    # Here's a compact version if you need it:
+    #     ^(?:\:([^\s]+)\s)?(\w+)\s(?:([^\s\:]+)\s)?(?:\:?(.*))?$
+
+    IRC_RE = /
+             ^              # beginning of string
+             (?:            # non-capturing group
+                 \:         # if we have a ':' then we have an origin
+                 ([^\s]+)   # get the origin without the ':'
+                 \s         # space after the origin
+             )?             # close non-capturing group
+             (\w+)          # must have a command
+             \s             # and a space after it
+             (?:            # non-capturing group
+                 ([^\s\:]+) # a target for the command
+                 \s         # and a space after it
+             )?             # close non-capturing group
+             (?:            # non-capturing group
+                 \:?        # if we have a ':' then we have freeform text
+                 (.*)       # get the rest as one string without the ':'
+             )?             # close non-capturing group
+             $              # end of string
+             /x
+
+    #
+    # Parse any incoming data and generate IRC events.
+    # ---
+    # returns:: +self+
+    #
+    def parse
+        @recvq.each do |line|
+            line.chomp!
+
+            debug(line)
+
+            m = IRC_RE.match(line)
+
+            origin  = m[1]
+            command = m[2]
+            target  = m[3]
+            params  = m[4]
+
+            if params and not target
+                target = params
+                params = nil
+            end
+
+            params = params.split if params
+
+            msg = Message.new(self, line, origin, target, params)
+
+            @eventq.post(command.upcase.to_sym, msg)
+        end
+
+        @recvq.clear
+
+        self
+    end
+
+    ######
+    public
+    ######
+
+    #
+    # Registers Event handlers with our EventQueue.
+    # ---
+    # <tt>c.on(:PRIVMSG) do |m|
+    #     if m.params =~ /\.die/ and m.origin == my_master
+    #         c.quit(params)
+    #         c.exit
+    #     end</tt>
+    # ---
+    # event:: name of the event as a Symbol
+    # block:: block to call when Event is posted
+    # returns:: self
+    #
+    def on(event, &block)
+        @eventq.handle(event, &block)
+
+        self
+    end
+
+    #
+    # Schedules input/output and runs the EventQueue.
+    # ---
+    # returns:: never, thread dies on +:exit+
+    #
+    def io_loop
+        loop do
+            if dead?
+                sleep(30)
+                connect
+                next
+            end
+
+            connect unless connected?
+
+            # Run the event loop. These events will add IO, and possibly other
+            # events, so we keep running until it's empty.
+            @eventq.run while @eventq.needs_ran?
+
+            next if dead?
+
+            writefd = [@socket] unless @sendq.empty?
+
+            ret = IO.select([@socket], writefd, [], 10)
+
+            next unless ret
+
+            @eventq.post(:read_ready)  unless ret[0].empty?
+            @eventq.post(:write_ready) unless ret[1].empty?
+        end
+    end
+
+    #
+    # Is the socket dead?
+    # ---
+    # returns:: +true+ or +false+
+    #
+    def dead?
+        @dead
+    end
+
+    #
+    # Are we connected?
+    # ---
+    # returns:: +true+ or +false+
+    #
+    def connected?
+        @connected
+    end
+
+    #
+    # Creates and connects our socket.
+    # ---
+    # returns:: +self+
+    #
+    def connect
+        verify_attributes
+
+        log("connecting to #@server:#@port")
+
+        begin
+            @socket = TCPSocket.new(@server, @port, @bind_to)
+        rescue Exception => err
+            @eventq.post(:dead)
+        end
+
+        @dead      = false
+        @connected = true
+
+        pass(@password) if @password
+        nick(@nickname)
+        user(@username, @server, @server, @realname)
+    end
+
+    #
+    # Logs a regular message.
+    # ---
+    # message:: the string to log
+    # returns:: +self+
+    #
+    def log(message)
+        @logger.info(caller[0].split('/')[-1]) { message } if @logger
+    end
+
+    #
+    # Logs a debug message.
+    # ---
+    # message:: the string to log
+    # returns:: +self+
+    #
+    def debug(message)
+        return unless @logger
+
+        @logger.debug(caller[0].split('/')[-1]) { message } if @debug
+    end
+
+    #
+    # Sets the logging object to use.
+    # If it quacks like a Logger object, it should work.
+    # ---
+    # logger:: the Logger to use
+    # returns:: +self+
+    #
+    def logger=(logger)
+        @logger = logger
+
+        # Set to false/nil to disable logging...
+        return unless @logger
+
+        @logger.progname        = 'irc'
+        @logger.datetime_format = '%b %d %H:%M:%S '
+
+        # We only have 'logging' and 'debugging', so just set the
+        # object to show all levels. I might change this someday.
+        @logger.level = Logger::DEBUG
+    end
+
+    #
+    # Forces the Client's Thread to die. If it's the main thread, the
+    # application goes with it.
+    # ---
+    # returns:: nope!
+    #
+    def exit(from = 'exit')
+        @eventq.post(:exit, from)
+        @eventq.run
+    end
+end
+
+# A simple data-holding class.
+class Message
+    ##
+    # instance attributes
+    attr_reader :client, :raw, :origin, :target, :params
+
+    #
+    # Creates a new Message. We use these to represent the old
+    # style of (char *origin, char *target, char *parv[]) in C.
+    #
+    def initialize(client, raw, origin, target, params)
+        @client, @raw, @origin = client, raw, origin
+        @target, @params       = target, params
+    end
+end
+
+end # module IRC

data/lib/rhuidean/event.rb

@@ -0,0 +1,113 @@
+#
+# rhuidean: a small, lightweight IRC client library
+# lib/rhuidean/event.rb: IRC events
+#
+# Copyright (c) 2003-2010 Eric Will <rakaur@malkier.net>
+#
+
+module IRC
+
+# Contains information about a posted event.
+class Event
+    attr_reader :event, :args
+
+    #
+    # Creates a new Event.
+    # ---
+    # event:: event name as a Symbol
+    # args:: list of arguments to pass to handler
+    # returns:: +self+
+    #
+    def initialize(event, *args)
+        @event = event
+        @args  = args
+    end
+end
+
+# A queue of events, with handlers. One per object.
+class EventQueue
+    attr_reader :queue, :handlers
+
+    #
+    # Create a new EventQueue.
+    # ---
+    # returns:: +self+
+    #
+    def initialize
+        @queue    = []
+        @handlers = {}
+    end
+
+    ######
+    public
+    ######
+
+    #
+    # Post a new event to the queue to be handled.
+    # ---
+    # event:: event name as a Symbol
+    # args:: list of arguments to pass to handler
+    # returns:: +self+
+    #
+    def post(event, *args)
+        # Only one post per event per loop, otherwise we end up trying
+        # to read from a socket that has no data, or stuff like that.
+        return if m = @queue.find { |q| q.event == event }
+
+        @queue << Event.new(event, *args)
+
+        self
+    end
+
+    #
+    # Register a handler for an event.
+    # ---
+    # event:: event name as a Symbol
+    # block:: block to call to handle event
+    # returns:: +self+
+    #
+    def handle(event, &block)
+        (@handlers[event] ||= []) << block
+
+        self
+    end
+
+    #
+    # Does the event queue have anything in it?
+    # ---
+    # returns:: +true+ or +false+
+    #
+    def needs_ran?
+        @queue.empty? ? false : true
+    end
+
+    #
+    # Goes through the event queue and runs the handlers.
+    # ---
+    # returns:: +self+
+    #
+    def run
+        needs_exit = false
+
+        while e = @queue.shift
+            next unless @handlers[e.event]
+
+            # If there's an :exit event in the queue wait until we're
+            # all the way done before we handle it.
+            if e.event == :exit
+                needs_exit = e
+                next
+            end
+
+            @handlers[e.event].each { |block| block.call(*e.args) }
+        end
+
+        # Now we can exit... any events that got added by handling routines
+        # just don't happen. This is arguably a bug.
+        @handlers[:exit].each { |b| b.call(*needs_exit.args) } if needs_exit
+
+        self
+    end
+end
+
+end # module IRC

data/lib/rhuidean/methods.rb

@@ -0,0 +1,71 @@
+#
+# rhuidean: a small, lightweight IRC client library
+# lib/rhuidean/client.rb: IRC::Client class
+#
+# Copyright (c) 2003-2010 Eric Will <rakaur@malkier.net>
+#
+
+module IRC
+
+class Client
+    ######
+    public
+    ######
+
+    # Sends text directly to the server.
+    def raw(message)
+        @sendq << message
+    end
+
+    # Sends an IRC NICK command.
+    def nick(nick)
+        @sendq << "NICK #{nick}"
+    end
+
+    # Sends an IRC USER command.
+    def user(username, server, host, realname)
+        @sendq << "USER #{username} #{server} #{host} :#{realname}"
+    end
+
+    # Sends an IRC PASS command.
+    def pass(password)
+        @sendq << "PASS #{password}"
+    end
+
+    # Sends an IRC PRIVMSG command.
+    def privmsg(to, message)
+        @sendq << "PRIVMSG #{to} :#{message}"
+    end
+
+    # Sends an IRC NOTICE command.
+    def notice(to, message)
+        @sendq << "NOTICE #{to} :#{message}"
+    end
+
+    # Sends an IRC JOIN command.
+    def join(channel, key = '')
+        @sendq << "JOIN #{channel} #{key}"
+    end
+
+    # Sends an IRC PART command.
+    def part(channel, message = '')
+        @sendq << "PART #{channel} :#{message}"
+    end
+
+    # Sends an IRC MODE command.
+    def umode(mode)
+        @sendq << "MODE #@nickname #{mode}"
+    end
+
+    # Sends an IRC MODE command.
+    def mode(target, mode)
+        @sendq << "MODE #{target} #{mode}"
+    end
+
+    # Send an IRC QUIT command.
+    def quit(message = '')
+        @sendq << "QUIT :#{message}"
+    end
+end
+
+end # module IRC

data/lib/rhuidean/numeric.rb

@@ -0,0 +1,178 @@
+#
+# rhuidean: a small, lightweight IRC client library
+# lib/rhuidean/numeric.rb: IRC numeric list
+#
+# Copyright (c) 2003-2010 Eric Will <rakaur@malkier.net>
+#
+
+module IRC
+
+#
+# A list of all IRC numerics, as per RFC 1459.
+# Stolen from GStage by Stephen Belcher <sycobuny@malkier.net>.
+#
+module Numeric
+
+# WELCOME
+RPL_WELCOME           = :'001'
+RPL_YOURHOST          = :'002'
+RPL_CREATED           = :'003'
+RPL_MYINFO            = :'004'
+RPL_BOUNCE            = :'005'
+
+# ERRORS
+ERR_NOSUCHNICK        = :'401'
+ERR_NOSUCHSERVER      = :'402'
+ERR_NOSUCHCHANNEL     = :'403'
+ERR_CANNOTSENDTOCHAN  = :'404'
+ERR_TOOMANYCHANNELS   = :'405'
+ERR_WASNOSUCHNICK     = :'406'
+ERR_TOOMANYTARGETS    = :'407'
+ERR_NOORIGIN          = :'409'
+ERR_NORECIPIENT       = :'411'
+ERR_NOTEXTTOSEND      = :'412'
+ERR_NOTOPLEVEL        = :'413'
+ERR_WILDTOPLEVEL      = :'414'
+ERR_UNKNOWNCOMMAND    = :'421'
+ERR_NOMOTD            = :'422'
+ERR_NOADMININFO       = :'423'
+ERR_FILEERROR         = :'424'
+ERR_NONICKNAMEGIVEN   = :'431'
+ERR_ERRONEOUSNICKNAME = :'432'
+ERR_NICKNAMEINUSE     = :'433'
+ERR_NICKCOLLISION     = :'436'
+ERR_USERNOTINCHANNEL  = :'441'
+ERR_NOTONCHANNEL      = :'442'
+ERR_USERONCHANNEL     = :'443'
+ERR_NOLOGIN           = :'444'
+ERR_SUMMONDISABLED    = :'445'
+ERR_USERSDISABLED     = :'446'
+ERR_NOTREGISTERED     = :'451'
+ERR_NEEDMOREPARAMS    = :'461'
+ERR_ALREADYREGISTERED = :'462'
+ERR_NOPERFORMHOST     = :'463'
+ERR_PASSWDMISTMATCH   = :'464'
+ERR_YOUREBANNEDCREEP  = :'465'
+ERR_KEYSET            = :'467'
+ERR_CHANNELISFULL     = :'471'
+ERR_UNKNOWNMODE       = :'472'
+ERR_INVITEONLYCHAN    = :'473'
+ERR_BANNEDFROMCHAN    = :'474'
+ERR_BADCHANNELKEY     = :'475'
+ERR_NOPRIVILEGES      = :'481'
+ERR_CHANOPRIVSNEEDED  = :'482'
+ERR_CANTKILLSERVER    = :'483'
+ERR_NOOPERHOST        = :'491'
+ERR_UMODEUNKNOWNFLAG  = :'501'
+ERR_USERSDONTMATCH    = :'502'
+
+# COMMAND REPLIES
+RPL_NONE            = :'300'
+RPL_USERHOST        = :'302'
+RPL_ISON            = :'303'
+RPL_AWAY            = :'301'
+RPL_UNAWAY          = :'305'
+RPL_NOWAWAY         = :'306'
+RPL_WHOISUSER       = :'311'
+RPL_WHOISSERVER     = :'312'
+RPL_WHOISOPERATOR   = :'313'
+RPL_WHOISIDLE       = :'317'
+RPL_ENDOFWHOIS      = :'318'
+RPL_WHOISCHANNELS   = :'319'
+RPL_WHOWASUSER      = :'314'
+RPL_ENDOFWHOWAS     = :'369'
+RPL_LISTSTART       = :'321'
+RPL_LIST            = :'322'
+RPL_LISTEND         = :'323'
+RPL_CHANNELMODEIS   = :'324'
+RPL_NOTOPIC         = :'331'
+RPL_TOPIC           = :'332'
+RPL_INVITING        = :'341'
+RPL_SUMMONING       = :'342'
+RPL_VERSION         = :'351'
+RPL_WHOREPLY        = :'352'
+RPL_ENDOFWHO        = :'315'
+RPL_NAMEREPLY       = :'353'
+RPL_ENDOFNAMES      = :'366'
+RPL_LINKS           = :'364'
+RPL_ENDOFLINKS      = :'365'
+RPL_BANLIST         = :'367'
+RPL_ENDOFBANLIST    = :'368'
+RPL_INFO            = :'371'
+RPL_ENDOFINFO       = :'374'
+RPL_MOTDSTART       = :'375'
+RPL_MOTD            = :'372'
+RPL_ENDOFMOTD       = :'376'
+RPL_YOUREOPER       = :'381'
+RPL_REHASHING       = :'382'
+RPL_TIME            = :'391'
+RPL_USERSSTART      = :'392'
+RPL_USERS           = :'393'
+RPL_ENDOFUSERS      = :'394'
+RPL_NOUSERS         = :'395'
+RPL_TRACELINK       = :'200'
+RPL_TRACECONNECTING = :'201'
+RPL_TRACEHANDSHAKE  = :'202'
+RPL_TRACEUNKNOWN    = :'203'
+RPL_TRACEOPERATOR   = :'204'
+RPL_TRACEUSER       = :'205'
+RPL_TRACESERVER     = :'206'
+RPL_TRACENEWTYPE    = :'208'
+RPL_TRACELOG        = :'261'
+RPL_STATSLINKINFO   = :'211'
+RPL_STATSCOMMANDS   = :'212'
+RPL_STATSCLINE      = :'213'
+RPL_STATSNLINE      = :'214'
+RPL_STATSILINE      = :'215'
+RPL_STATSKLINE      = :'216'
+RPL_STATSYLINE      = :'218'
+RPL_ENDOFSTATS      = :'219'
+RPL_STATSLLINE      = :'241'
+RPL_STATSUPTIME     = :'242'
+RPL_STATSOLINE      = :'243'
+RPL_STATSHLINE      = :'244'
+RPL_UMODEIS         = :'221'
+RPL_LUSERCLIENT     = :'251'
+RPL_LUSEROP         = :'252'
+RPL_LUSERUNKNOWN    = :'253'
+RPL_LUSERCHANNELS   = :'254'
+RPL_LUSERME         = :'255'
+RPL_ADMINME         = :'256'
+RPL_ADMINLOC1       = :'257'
+RPL_ADMINLOC2       = :'258'
+RPL_ADMINEMAIL      = :'259'
+
+# RESERVED
+RPL_TRACECLASS      = :'209'
+RPL_STATSQLINE      = :'217'
+RPL_SERVICEINFO     = :'231'
+RPL_ENDOFSERVICES   = :'232'
+RPL_SERVICE         = :'233'
+RPL_SERVLIST        = :'234'
+RPL_SERVICELISTEND  = :'235'
+RPL_WHOISCHANOP     = :'316'
+RPL_KILLDONE        = :'361'
+RPL_CLOSING         = :'362'
+RPL_CLOSEEND        = :'363'
+RPL_INFOSTART       = :'373'
+RPL_MYPORTIS        = :'384'
+ERR_YOUWILLBEBANNED = :'466'
+ERR_BADCHANMASK     = :'476'
+ERR_NOSERVICEHOST   = :'492'
+
+@@table = {}
+constants.each { |c| @@table[const_get(c)] = c }
+
+#
+# Given a symbol, returns the constant name.
+# ---
+# num:: Symbol
+# returns:: constant
+#
+def Numeric.num2const(num)
+    @@table[num]
+end
+
+end # module Numeric
+
+end # module IRC

data/lib/rhuidean/timer.rb

@@ -0,0 +1,103 @@
+#
+# rhuidean: a small, lightweight IRC client library
+# lib/rhuidean/timer.rb: timed code execution
+#
+# Copyright (c) 2003-2010 Eric Will <rakaur@malkier.net>
+#
+
+module IRC
+
+# Allows for code to be executed on a timed basis.
+class Timer
+    ##
+    # class attributes
+    @@timers = []
+
+    ##
+    # instance attributes
+    attr_reader :time, :repeat
+
+    #
+    # Creates a new timer to be executed within +10 seconds of +time+.
+    # ---
+    # time:: time in seconds
+    # repeat:: +true+ or +false+, keep executing +block+ every +time+?
+    # block:: execute the given block
+    # returns:: +self+
+    #
+    def initialize(time, repeat = false, &block)
+        @time   = time.to_i
+        @repeat = repeat
+        @block  = block
+
+        @@timers << self
+
+        @thread = Thread.new { start }
+
+        self
+    end
+
+    ######
+    public
+    ######
+
+    #
+    # A wrapper for initialize. Sets up the block to repeat.
+    # --
+    # time:: repeat how often, in seconds?
+    # returns:: +self+
+    #
+    def Timer.every(time, &block)
+        new(time, true, &block)
+    end
+
+    #
+    # A wrapper for initialize. Sets up so the block doesn't repeat.
+    # ---
+    # time:: execute block after how long, in seconds?
+    # returns:: self
+    #
+    def Timer.after(time, &block)
+        new(time, false, &block)
+    end
+
+    #
+    # Stops all timers.
+    # ---
+    # returns:: nothing
+    #
+    def Timer.stop
+        @@timers.each { |t| t.stop }
+    end
+
+    #
+    # Kills the thread we're in.
+    # ---
+    # returns:: nothing
+    #
+    def stop
+        @@timers.delete(self)
+        @thread.exit
+    end
+
+    #######
+    private
+    #######
+
+    #
+    # Starts the loop, always in a thread.
+    # ---
+    # returns:: nothing
+    #
+    def start
+        loop do
+            sleep(@time)
+            @block.call
+            break unless @repeat
+        end
+
+        @@timers.delete(self)
+    end
+end
+
+end # module IRC

data/rakefile

@@ -0,0 +1,70 @@
+#
+# rhuidean: a small, lightweight IRC client library
+# rakefile: ruby makefile
+#
+# Copyright (c) 2003-2010 Eric Will <rakaur@malkier.net>
+#
+
+# Import required Ruby modules.
+%w(rdoctask testtask gempackagetask packagetask).each do |m|
+    require 'rake/' + m
+end
+
+#
+# Default task - unit tests.
+#
+# $ rake
+#
+task :default => [:test]
+
+Rake::TestTask.new do |t|
+    t.libs << 'test'
+    t.test_files = %w(test/ts_rhuidean.rb)
+end
+
+#
+# Documentation generation.
+#
+# $ rake rdoc
+#
+Rake::RDocTask.new do |r|
+    r.rdoc_dir = 'doc/rdoc'
+    r.options << '--line-numbers' << '--inline-source'
+    r.rdoc_files.include('lib/rhuidean.rb lib/rhuidean/**/*')
+end
+
+#
+# Package generation.
+#
+# $ rake package
+#
+PKG_FILES = FileList['README', 'rakefile',
+                     'lib/rhuidean.rb', 'lib/rhuidean/**/*.rb',
+                     'test/*.rb']
+
+Rake::PackageTask.new('package') do |p|
+    p.name          = 'rhuidean'
+    p.version       = '0.2.1'
+    p.need_tar      = false
+    p.need_zip      = false
+    p.package_files = PKG_FILES
+end
+
+spec = Gem::Specification.new do |s|
+    s.name     = 'rhuidean'
+    s.version  = '0.2.1'
+    s.author   = 'Eric Will'
+    s.email    = 'rakaur@malkier.net'
+    s.homepage = 'http://github.com/rakaur/rhuidean/'
+    s.platform = Gem::Platform::RUBY
+    s.summary  = 'a small, lightweight IRC client library'
+    s.files    = PKG_FILES.to_a
+
+    s.require_paths = %w(lib)
+    s.test_file     = 'test/ts_rhuidean.rb'
+    s.has_rdoc      = true
+end
+
+Rake::GemPackageTask.new(spec) do
+end
+

data/test/tc_client.rb

@@ -0,0 +1,73 @@
+#
+# rhuidean: a small, lightweight IRC client library
+# test/tc_client.rb: unit testing
+#
+# Copyright (c) 2003-2010 Eric Will <rakaur@malkier.net>
+#
+
+warn <<-end
+    WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING!
+
+    You have 15 seconds to cancel (CTRL+C).
+
+    These tests connect to irc.malkier.net:6667 and join #malkier for a brief
+    period of time (a few seconds), and posts the client version and platform.
+    If you do not want your machine to do this, do not run these tests!
+
+    You have 15 seconds to cancel (CTRL+C).
+
+    WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING!
+end
+
+$stdout.sync = true
+print "."*16
+15.downto(0) do
+    print "\b \b"
+    sleep(1)
+end
+puts
+$stdout.sync = false
+
+class TestClient < Test::Unit::TestCase
+    def test_001_connect
+        c = nil
+
+        assert_nothing_raised do
+            c = IRC::Client.new do |c|
+                c.server   = 'irc.malkier.net'
+                c.port     = 6667
+
+                c.nickname = "rhuidean#{rand(9999)}"
+                c.username = 'rhuidean'
+                c.realname = 'rhuidean unit tester'
+
+                c.logger   = nil
+                c.debug    = false
+            end
+        end
+
+        assert_equal(6667,              c.port)
+        assert_equal('irc.malkier.net', c.server)
+        assert_match(/^rhuidean\d+$/,   c.nickname)
+        assert_equal('rhuidean',        c.username)
+
+        welcome = false
+        str     = "rhuidean-#{IRC::Client::VERSION} [#{RUBY_PLATFORM}]"
+
+        assert_nothing_raised do
+            c.on(IRC::Numeric::RPL_WELCOME) { welcome = true  }
+
+            c.on(IRC::Numeric::RPL_ENDOFMOTD) do
+                c.join('#malkier')
+                c.privmsg('#malkier', str)
+            end
+        end
+
+        assert_nothing_raised { c.connect }
+
+        t = Thread.new { c.io_loop }
+
+        sleep(1) until welcome
+        assert(true, welcome)
+    end
+end

data/test/ts_rhuidean.rb

@@ -0,0 +1,14 @@
+#
+# rhuidean: a small, lightweight IRC client library
+# test/ts_rhuidean.rb: unit testing
+#
+# Copyright (c) 2003-2010 Eric Will <rakaur@malkier.net>
+#
+
+$: << 'lib'
+
+require 'test/unit'
+
+require 'rhuidean'
+
+require 'test/tc_client.rb'

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: rhuidean
+version: !ruby/object:Gem::Version 
+  hash: 21
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  - 1
+  version: 0.2.1
+platform: ruby
+authors: 
+- Eric Will
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-09-08 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: 
+email: rakaur@malkier.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README
+- rakefile
+- lib/rhuidean.rb
+- lib/rhuidean/methods.rb
+- lib/rhuidean/numeric.rb
+- lib/rhuidean/client.rb
+- lib/rhuidean/timer.rb
+- lib/rhuidean/event.rb
+- test/tc_client.rb
+- test/ts_rhuidean.rb
+has_rdoc: true
+homepage: http://github.com/rakaur/rhuidean/
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: a small, lightweight IRC client library
+test_files: 
+- test/ts_rhuidean.rb