net-yail 1.0.0

data/IRCBot.rb

@@ -0,0 +1,132 @@
+require 'rubygems'
+gem 'net-yail'
+
+# My abstraction from adapter to a real bot.
+#
+# At the moment this only supports single-channel joining.  It's just a very
+# basic example, kids.  Deal with it.
+class IRCBot
+  attr_reader :irc
+
+  public
+
+  # Creates a new bot yay.  Note that due to my laziness, the options here
+  # are almost exactly the same as those in Net::YAIL.  But at least there
+  # are more defaults here.
+  #
+  # Options:
+  # * <tt>:irc_network</tt>: Name/IP of the IRC server
+  # * <tt>:channel</tt>: Channel name to join
+  # * <tt>:port</tt>: Port number, defaults to 6667
+  # * <tt>:username</tt>: Username reported to server
+  # * <tt>:realname</tt>: Real name reported to server
+  # * <tt>:nicknames</tt>: Array of nicknames to cycle through
+  # * <tt>:silent</tt>: Silence a lot of reports
+  # * <tt>:loud</tt>: Lots more verbose reports
+  def initialize(options = {})
+    @channel = options[:channel]
+    @irc_network = options[:irc_network]
+    @port = options[:port] || 6667
+    @username = options[:username] || 'IRCBot'
+    @realname = options[:realname] || 'IRCBot'
+    @nicknames = options[:nicknames] || ['IRCBot1', 'IRCBot2', 'IRCBot3']
+    @silent = options[:silent] || false
+    @loud = options[:loud] || false
+  end
+
+  # Creates the socket connection and registers the (very simple) default
+  # welcome handler.  Subclasses should build their hooks in
+  # add_custom_handlers to allow auto-creation in case of a restart.
+  def connect_socket
+    @irc = Net::YAIL.new(
+      :address    => @irc_network,
+      :port       => @port,
+      :username   => @username,
+      :realname   => @realname,
+      :nicknames  => @nicknames,
+      :silent     => @silent,
+      :loud       => @loud
+    )
+
+    # Simple hook for welcome to allow auto-joining of the channel
+    @irc.prepend_handler :incoming_welcome, self.method(:welcome)
+
+    add_custom_handlers
+  end
+
+  # To be subclassed - this method is a nice central location to allow the
+  # bot to register its handlers before this class takes control and hits
+  # the IRC network.
+  def add_custom_handlers
+    raise "You must define your handlers in add_custom_handlers, or else " +
+        "explicitly override with an empty method."
+  end
+
+  # Enters the socket's listening loop(s)
+  def start_listening
+    @irc.start_listening
+  end
+
+  # Tells us the main app wants to just wait until we're done with all
+  # thread processing, or get a kill signal, or whatever.  For now this is
+  # basically an endless loop that lets the threads do their thing until
+  # the socket dies.  If a bot wants, it can handle :irc_loop to do regular
+  # processing.
+  def irc_loop
+    while true
+      until @irc.dead_socket || @irc.socket.eof?
+        sleep 15
+        @irc.handle(:irc_loop)
+        Thread.pass
+      end
+
+      # Disconnected?  Wait a little while and start up again.
+      sleep 30
+      @irc.stop_listening
+      self.connect_socket
+      start_listening
+    end
+  end
+
+  private
+  # Basic handler for joining a single channel upon successful registration
+  def welcome
+    @irc.join(@channel)
+    # Let the default welcome stuff still happen
+    return false
+  end
+
+  ################
+  # Helpful wrappers
+  ################
+
+  # Wraps Net::YAIL.me
+  def bot_name
+    @irc.me
+  end
+
+  # Wraps Net::YAIL.msg
+  def msg(*args)
+    @irc.msg(*args)
+  end
+
+  # Wraps Net::YAIL.act
+  def act(*args)
+    @irc.act(*args)
+  end
+
+  # Wraps Net::YAIL.join
+  def join(*args)
+    @irc.join(*args)
+  end
+
+  # Wraps Net::YAIL.report
+  def report(*args)
+    @irc.report(*args)
+  end
+
+  # Wraps Net::YAIL.nick
+  def nick(*args)
+    @irc.nick(*args)
+  end
+end

data/README

@@ -0,0 +1,66 @@
+Rubyforge page: http://rubyforge.org/projects/ruby-irc-yail
+
+Net::YAIL is a library built for dealing with IRC communications in Ruby.
+This is a project I've been building for about three years, based
+originally on the very messy initial release of IRCSocket (back when I first
+started, that was the only halfway-decent IRC lib I found).  I've put a lot
+of time and effort into cleaning it up to make it better for my own uses,
+and now it's almost entirely my code.
+
+Some credit should also be given to Ruby-IRC, as I stole its eventmap.yml
+file with very minor modifications.
+
+This library may not be useful to everybody (or anybody other than myself,
+for that matter), and Ruby-IRC or another lib may work for your situation
+far better than this thing will, but the general design I built here has
+just felt more natural to me than the other libraries I've looked at since
+I started my project.
+
+Features of YAIL:
+
+* Allows event handlers to be specified very easily for all known IRC events,
+  and except in a few rare cases one can choose to override the default
+  handling mechanisms.
+* Allows handling outgoing messages, such as when privmsg is called.  The API
+  won't allow you to stop the outgoing message (though I may offer this if
+  people want it), but you can filter data before it's sent out.  This is one
+  thing I didn't see anywhere else.
+* Threads for input and output are persistent.  This is a feature, not a bug.
+  Some may hate this approach, but I'm a total n00b to threads, and it seemed
+  like the way to go, having thread loops responsible for their own piece of
+  the library.  I'd *love* input here if anybody can tell me why this is a bad
+  idea....
+* "Stacked" event handling is possible if you want to provide a very modular
+  framework of your own.  When you prepend a handler, its return determines if
+  the next handler will get called.  This isn't useful for a simple bot most
+  likely, but can have some utility in bigger projects where a single event
+  may need to be dispatched to several handlers.
+* Easy to build a simple bot without subclassing anything.  One gripe I had
+  with IRCSocket was that it was painful to do anything without subclassing
+  and overriding methods.  No need here.
+* Lots of built-in reporting.  You may hate this part, but for a bot, it's
+  really handy to have most incoming data reported on some level.  I may make
+  this optional at some point, but only if people complain, since I haven't
+  yet seen a need to do so....
+* Built-in PRIVMSG buffering!  You can of course choose to not buffer, but by
+  default you cannot send more than one message to a given target (user or
+  channel) more than once per second.  Additionally, this buffering method is
+  ideal for a bot that's trying to be chatty on two channels at once, because
+  buffering is per-target, so queing up 20 lines on <tt>##foo</tt> doesn't mean waiting
+  20 seconds to spit data out to <tt>##bar</tt>.  The one caveat here is that if your
+  app is trying to talk to too many targets at once, the buffering still won't
+  save you from a flood-related server kick.  If this is a problem for others,
+  I'll look into building an even more awesome buffering system.
+* The included IRCBot is a great starting point for building your own bot,
+  but if you want something even simpler, just look at Net::YAIL's documentation
+  for the most basic working examples.
+
+I still have a lot to do, though.  The output API is definitely not fully
+fleshed out - there are many commands I haven't yet built a shortcut for, such
+as KICK or TOPIC.  I believe that the library is also missing a lot for people
+who just have a different approach than me, since this was purely designed for
+my own benefit, and then released almost exclusively to piss off the people
+whose work I stole to get where I'm at today.  (Just kiddin', Pope)
+
+This code is released under the MIT license.  I hear it's all the rage with
+the kids these days.

data/lib/net/yail.rb

@@ -0,0 +1,525 @@
+require 'socket'
+require 'thread'
+require 'yaml'
+
+# To make this library seem smaller, a lot of code has been split up and put
+# into semi-logical files.  I don't really like this hacky solution, but I
+# cannot figure out a nicer way to keep the code as clean as I like.
+require 'net/yail/magic_events'
+require 'net/yail/default_events'
+require 'net/yail/output_api'
+
+# TODO:
+# * Extract all pattern matching into an external file - store both the
+#   pattern and the event handle's symbol.
+# * Build a system to allow numeric events to get sent post-processed data
+#   if it makes sense (converting the text to specific parts instead of all
+#   handlers having to regex it themselves, for instance)
+
+# If a thread crashes, I want the app to die.  My threads are persistent, not
+# temporary.
+Thread.abort_on_exception = true
+
+module Net
+
+# This library is based on the initial release of IRCSocket with a tiny bit
+# of plagarism of Ruby-IRC.
+#
+# My aim here is to build something that is still fairly simple to use, but
+# powerful enough to build a decent IRC program.
+#
+# This is far from complete, but it does successfully power a relatively
+# complicated bot, so I believe it's solid and "good enough" for basic tasks.
+#
+# =Events
+#
+# * Register handlers by calling prepend_handler(symbol, method)
+# * Events based on incoming data are represented by :incoming_*, while
+#   outgoing are :outgoing_*
+# * I'm still using the names from IRCSocket dev(s), so this means an incoming
+#   message would call the :incoming_msg handler, and a message being sent
+#   would call the :outgoing_msg handler.
+#
+# ==Incoming Events
+#
+# Current list of incoming events and the parameters sent to the handler:
+# * :incoming_msg(fullactor, actor, target, text) - Normal message from actor to target
+# * :incoming_act(fullactor, actor, target, text) - CTCP "action" (emote) from actor to target
+# * :incoming_ctcp(fullactor, actor, target, text) - CTCP other than "action" from actor to target
+# * :incoming_ctcpreply(fullactor, actor, target, text) - CTCP NOTICE from actor to target
+# * :incoming_notice(fullactor, actor, target, text) - other NOTICE from actor to target
+# * :incoming_mode(fullactor, actor, target, modes, objects) - actor sets modes on objects in target channel
+# * :incoming_join(fullactor, actor, target) - actor joins target channel
+# * :incoming_part(fullactor, actor, target, text) - actor leaves target with message in text
+# * :incoming_kick(fullactor, actor, target, object, text) - actor kicked object from target with reason 'text'
+# * :incoming_quit(fullactor, actor, text) - actor left server completely with reason 'text'
+# * :incoming_nick(fullactor, actor, nickname) - actor changed to nickname
+# * :incoming_ping(text) - ping from server with given text
+# * :incoming_miscellany(line) - text from server didn't match anything known
+# * :incoming_welcome(text, args) - raw 001 from server, means we successfully logged in
+# * :incoming_bannedfromchan(text, args) - banned from channel
+# * Anything else in the eventmap.yml file with params(text, args).
+#
+# Common parameter elements:
+# * fullactor: Rarely needed, full text of origin of an action
+# * actor: Nickname of originator of an action
+# * target: Nickname for private actions, channel name for public
+# * text: Actual message/emote/notice/etc
+# * args: For numeric handlers, this is a hash of :fullactor, :actor, and
+#   :target.  Most numeric handlers I've built don't need this, so I made it
+#   easier to just get what you specifically want.
+#
+# ==Outgoing Events
+#
+# Generally speaking, you won't need these very often, but they're here for
+# the edge cases all the same.  Note that the socket output cannot be skipped
+# (see Return value from events below), so this is truly just to allow
+# modifying things before they go out (filtering speech, converting or
+# stripping markup, etc) or just general stats-type logic.
+#
+# Events:
+# * :outgoing_begin_connection(username, address, realname) - called when the
+#   start_listening method has set up all threading and such.  Default behavior
+#   is to call user() and nick()
+# * :outgoing_privmsg(target, text) - Any kind of PRIVMSG output is about to
+#   get sent out
+# * :outgoing_msg(target, text) - Hit by a direct call to msg, which is
+#   normally used for "plain" messages, but a "clever" user could do their own
+#   CTCP messages here as well.  Shoot them if they do.
+# * :outgoing_ctcp(target, text) - All CTCP messages hit here eventually
+# * :outgoing_act(target, text) - ACTION CTCP messages should go through this,
+#   not manually use ctcp.
+# * :outgoing_notice(target, text) - All NOTICE messages hit here
+# * :outgoing_ctcpreply(target, text) - CTCP NOTICE messages
+# * :outgoing_mode(target, modes, objects) - Sets or queries mode.  If modes is
+#   present, sends mode list to target.  Objects would be users.
+# * :outgoing_join(target) - The given target channel is about to be joined
+# * :outgoing_part(target, text) - The given target channel is about to be
+#   left, with optional text reason.
+# * :outgoing_quit(text) - The client is about to quit, with optional text
+#   reason.
+# * :outgoing_nick(new_nick) - The client is about to change nickname
+# * :outgoing_user(username, myaddress, address, realname) - We're about to
+#   send a USER command.
+#
+# Note that a single output call can hit multiple handlers, so you must plan
+# carefully.  A call to act() will hit the act handler, then ctcp (since act
+# is a type of ctcp message), then privmsg.
+#
+# ==Custom Events
+#
+# Yes, you can register your own wacky event handlers if you like, and have
+# your code call them.  Just register a handler with some funky name of
+# your own design (avoid the prefixes :incoming and :outgoing for obvious
+# reasons), and so long as something calls that handler, your handler method
+# will get its data.
+#
+# This isn't likely useful for a simple program, but for a subclass or wrapper
+# of the IRC class, having the ability to give *its* users new events without
+# mucking up this class can be helpful.  For instance, see IRCBot#irc_loop
+# and the :irc_loop event.  If one wants their bot to do something regularly,
+# they just handle that event and get frequent calls.
+#
+# ==Return value from events
+#
+# The return can be *critical* - a true value tells the handlers to stop
+# their chain (true = "yes, I handled this event, stay the frak away you
+# other, lesser handlers!), so no other handlers will be called.  
+# 
+# Note that critical handlers (incoming ping, welcome, and nick change) cannot
+# be overwritten as they actually run *before* user-defined handlers, and
+# output handlers are just for filtering and cannot stop the socket from
+# sending its data.  If you want to change that low-level stuff, you should
+# subclass, modify the code directly, monkey-patch, or just write your own
+# library.
+#
+# When should you return false from an event?  Generally any time you have a
+# handler that really needs to report itself.  Unless you have multiple
+# layers of handlers for a given event, there's little reason to worry about
+# breaking the chain of events.  Since handlers are *prepended* to the list,
+# anybody subclassing your code can override your events, not the other way
+# around.  The main use is if you have multiple handlers for a single complex
+# event, where you want each handler to do its own set process and pass on the
+# event if it isn't resposible for that particular situation.  Allows complex
+# interactions to be made a bit cleaner, theoretically.
+#
+# =Simple example
+#
+# For a program to do anything useful, it must instantiate an object with
+# useful data and register some handlers:
+#
+#   require 'rubygems'
+#   require 'net/yail'
+#
+#   irc = Net::YAIL.new(
+#     :address    => 'irc.someplace.co.uk',
+#     :username   => 'Frakking Bot',
+#     :realname   => 'John Botfrakker',
+#     :nicknames  => ['bot1', 'bot2', 'bot3']
+#   )
+#
+#   irc.prepend_handler :incoming_welcome, proc {
+#     irc.join('#foo')
+#     return false
+#   }
+#
+#   irc.start_listening
+#   while irc.dead_socket == false
+#     # Avoid major CPU overuse by taking a very short nap
+#     sleep 0.05
+#   end
+#
+# Now we've built a simple IRC listener that will connect to a (probably
+# invalid) network, identify itself, and sit around waiting for the welcome
+# message.  After this has occurred, we join a channel and return false.
+#
+# One could also define a method instead of a proc:
+#
+#   require 'rubygems'
+#   require 'net/yail'
+#
+#   def welcome
+#     @irc.join('#channel')
+#     return false
+#   end
+#
+#   irc = Net::YAIL.new(
+#     :address    => 'irc.someplace.co.uk',
+#     :username   => 'Frakking Bot',
+#     :realname   => 'John Botfrakker',
+#     :nicknames  => ['bot1', 'bot2', 'bot3']
+#   )
+#
+#   irc.prepend_handler :incoming_welcome, method(:welcome)
+#   irc.start_listening
+#   while irc.dead_socket == false
+#     # Avoid major CPU overuse by taking a very short nap
+#     sleep 0.05
+#   end
+#
+# =Better example
+#
+# See the included IRCBot for a basic bot base class example.
+class YAIL 
+  include Net::IRCEvents::Magic
+  include Net::IRCEvents::Defaults
+  include Net::IRCOutputAPI
+
+  attr_reader(
+    :me,                # Nickname on the IRC server
+    :registered,        # If true, we've been welcomed
+    :nicknames,         # Array of nicknames to try when logging on to server
+    :dead_socket,       # True if we have no data after a read operation
+    :socket             # TCPSocket instance
+  )
+  attr_accessor(
+    :silent,
+    :loud
+  )
+
+  # Makes a new instance, obviously.
+  #
+  # Note: I haven't done this everywhere, but for the constructor, I felt
+  # it needed to have hash-based args.  It's just cleaner to me when you're
+  # taking this many args.
+  #
+  # Options:
+  # * <tt>:address</tt>: Name/IP of the IRC server
+  # * <tt>:port</tt>: Port number, defaults to 6667
+  # * <tt>:username</tt>: Username reported to server
+  # * <tt>:realname</tt>: Real name reported to server
+  # * <tt>:nicknames</tt>: Array of nicknames to cycle through
+  # * <tt>:silent</tt>: Don't report output messages from this object,
+  #   defaults to false
+  # * <tt>:loud</tt>: Report a whole lot of stuff that's normally silenced and
+  #   is generally very annoying.  Defaults to false, thankfully.
+  # * <tt>:throttle_seconds</tt>: Seconds between a cycle of privmsg sends.
+  #   Defaults to 1.  One "cycle" is defined as sending one line of output to
+  #   *all* targets that have output buffered.
+  def initialize(options = {})
+    @me                 = ''
+    @nicknames          = options[:nicknames]
+    @registered         = false
+    @username           = options[:username]
+    @realname           = options[:realname]
+    @address            = options[:address]
+    @port               = options[:port] || 6667
+    @silent             = options[:silent] || false
+    @loud               = options[:loud] || false
+    @throttle_seconds   = options[:throttle_seconds] || 1
+
+    # Read in map of event numbers and names.  Yes, I stole this event map
+    # file from RubyIRC and made very minor changes....  They stole it from
+    # somewhere else anyway, so it's okay.
+    eventmap = "#{File.dirname(__FILE__)}/yail/eventmap.yml"
+    @event_number_lookup = File.open(eventmap) { |file| YAML::load(file) }.invert
+
+    # Build our socket
+    @socket = TCPSocket.new(@address, @port)
+
+    # We're not dead... yet...
+    @dead_socket = false
+
+    # Shared resources for threads to try and coordinate....  I know very
+    # little about thread safety, so this stuff may be a terrible disaster.
+    # Please send me better approaches if you are less stupid than I.
+    @input_buffer = []
+    @input_buffer_mutex = Mutex.new
+    @privmsg_buffer = {}
+    @privmsg_buffer_mutex = Mutex.new
+
+    # Buffered output is allowed to go out right away.
+    @next_message_time = Time.now
+
+    # Setup handlers
+    @handlers = Hash.new
+    setup_default_handlers
+  end
+
+  # Starts listening for input and builds the perma-threads that check for
+  # input, output, and privmsg buffering.
+  def start_listening
+    # We don't want to spawn an extra listener
+    return if Thread === @ioloop_thread
+
+    # Build forced / magic logic - welcome setting @me, ping response, etc.
+    # Since we do these here, nobody can skip them and they're always first.
+    setup_magic_handlers
+
+    # Begin the listening thread
+    @ioloop_thread = Thread.new {io_loop}
+    @input_processor = Thread.new {process_input_loop}
+    @privmsg_processor = Thread.new {process_privmsg_loop}
+
+    # Let's begin the cycle by telling the server who we are.  This should
+    # start a TERRIBLE CHAIN OF EVENTS!!!
+    handle(:outgoing_begin_connection, @username, @address, @realname)
+  end
+
+  # Kills and clears all threads.  See note above about my lack of knowledge
+  # regarding threads.  Please help me if you know how to make this system
+  # better.  DEAR LORD HELP ME IF YOU CAN!
+  def stop_listening
+    @ioloop_thread.terminate
+    @input_processor.terminate
+    @privmsg_processor.terminate
+
+    @ioloop_thread = nil
+    @input_processor = nil
+    @privmsg_processor = nil
+  end
+
+  private
+
+  # Reads incoming data - should only be called by io_loop, and only when
+  # we've already ensured that data is, in fact, available.
+  def read_incoming_data
+    line = @socket.gets
+
+    # If we have no data, the socket closed.  Nothing to do but set a
+    # status and return
+    if !line
+      @dead_socket = true
+      return
+    end
+
+    line.chomp!
+
+    report "+++INCOMING: #{line}" if @loud
+
+    # Only synchronize long enough to push our incoming string onto the
+    # input buffer
+    @input_buffer_mutex.synchronize do
+      @input_buffer.push(line)
+    end
+  end
+
+  # This should be called from a thread only!  Does nothing but listens
+  # forever for incoming data, and calling handlers due to this listening
+  def io_loop
+    while true
+      # if no data is coming in, don't block the socket!
+      read_incoming_data if Kernel.select([@socket], nil, nil, 0)
+      sleep 0.05
+    end
+  end
+
+  # This again is a thread-only method.  Loops forever, handling input
+  # whenever the @input_buffer var has any.
+  def process_input_loop
+    lines = nil
+    while true
+      # Only synchronize long enough to copy and clear the input buffer.
+      @input_buffer_mutex.synchronize do
+        lines = @input_buffer.dup
+        @input_buffer.clear
+      end
+
+      if (lines)
+        # Now actually handle the data we copied, secure in the knowledge
+        # that our reader thread is no longer going to wait on us.
+        while lines.empty? == false
+          process_input(lines.shift)
+        end
+
+        lines = nil
+      end
+
+      sleep 0.05
+    end
+  end
+
+  # Grabs one message for each target in the private message buffer, removing
+  # messages from @privmsg_buffer.  Returns a hash array of target -> text
+  def pop_privmsgs
+    privmsgs = {}
+
+    # Only synchronize long enough to pop the appropriate messages.  By
+    # the way, this is UGLY!  I should really move some of this stuff....
+    @privmsg_buffer_mutex.synchronize do
+      for target in @privmsg_buffer.keys
+        # Clean up our buffer to avoid a bunch of empty elements wasting
+        # time and space
+        if @privmsg_buffer[target].nil? || @privmsg_buffer[target].empty?
+          @privmsg_buffer.delete(target)
+          next
+        end
+
+        privmsgs[target] = @privmsg_buffer[target].shift
+      end
+    end
+
+    return privmsgs
+  end
+
+  # Checks for new private messages, and outputs all that are gathered from
+  # pop_privmsgs, if any
+  def check_privmsg_output
+    privmsgs = pop_privmsgs
+    @next_message_time = Time.now + @throttle_seconds unless privmsgs.empty?
+
+    for (target, out_array) in privmsgs
+      report(out_array[1]) unless out_array[1].to_s.empty?
+      raw("PRIVMSG #{target} :#{out_array.first}", false)
+    end
+  end
+
+  # Our final thread loop - grabs the first privmsg for each target and
+  # sends it on its way.
+  def process_privmsg_loop
+    while true
+      check_privmsg_output if @next_message_time <= Time.now && !@privmsg_buffer.empty?
+
+      sleep 0.05
+    end
+  end
+
+  # Gets some input, sends stuff off to a handler.  Yay.
+  def process_input(line)
+    case line
+      when /^:((.+?)(?:!.+?)?) PRIVMSG (\S+?) :?\001ACTION (.+?)\001$/i
+        handle :incoming_act, $1, $2, $3, $4
+      when /^:((.+?)(?:!.+?)?) PRIVMSG (\S+?) :?\001(.+?)\001$/i
+        handle :incoming_ctcp, $1, $2, $3, $4
+      when /^:((.+?)(?:!.+?)?) PRIVMSG (\S+?) :?(.+?)$/i
+        handle :incoming_msg, $1, $2, $3, $4
+      when /^:((.+?)(?:!.+?)?) NOTICE (\S+?) :?\001(.+?)\001$/i
+        handle :incoming_ctcpreply, $1, $2, $3, $4
+      when /^:((.+?)(?:!.+?)?) NOTICE (\S+?) :?(.+?)$/i
+        handle :incoming_notice, $1, $2, $3, $4
+      when /^:((.+?)(?:!.+?)?) MODE (\S+?) :?(\S+?)(?: (.+?))?$/i
+        handle :incoming_mode, $1, $2, $3, $4, $5
+      when /^:((.+?)(?:!.+?)?) JOIN :?(\S+?)$/i
+        handle :incoming_join, $1, $2, $3
+      when /^:((.+?)(?:!.+?)?) PART (\S+?)(?: :?(\S+?)?)?$/i
+        handle :incoming_part, $1, $2, $3, $4
+      when /^:((.+?)(?:!.+?)?) KICK (\S+?) (\S+?) :?(.+?)$/i
+        handle :incoming_kick, $1, $2, $3, $4, $5
+      when /^:((.+?)(?:!.+?)?) QUIT :?(.+?)$/i
+        handle :incoming_quit, $1, $2, $3
+      when /^:((.+?)(?:!.+?)?) NICK :?(\S+?)$/i
+        handle :incoming_nick, $1, $2, $3
+      when /^PING :?(.+?)$/i
+        handle :incoming_ping, $1
+      when /^:((.+?)(?:!.+?)?) (\d{3})\s+(\S+?) (.+?)$/i
+        handle_numeric($3.to_i, $1, $2, $4, $5)
+      else
+        handle :incoming_miscellany, line
+    end
+  end
+
+  ##################################################
+  # EVENT HANDLING ULTRA SUPERSYSTEM DELUXE!!!
+  ##################################################
+
+  public
+  # Event handler hook.  Kinda hacky.  Calls your event(s) before the default
+  # event.  Default stuff will happen if your handler doesn't return true.
+  def prepend_handler(event, *procs)
+    raise "Cannot change handlers while threads are listening!" if @ioloop_thread
+
+    # See if this is a word for a numeric - only applies to incoming events
+    if (event.to_s =~ /^incoming_(.*)$/)
+      number = @event_number_lookup[$1].to_i
+      event = :"incoming_numeric_#{number}" if number > 0
+    end
+
+    @handlers[event] ||= Array.new
+    until procs.empty?
+      @handlers[event].unshift(procs.pop)
+    end
+  end
+
+  # Handles the given event (if it's in the @handlers array) with the
+  # arguments specified.
+  #
+  # The @handlers must be a hash where key = event to handle and value is
+  # a Proc object (via Class.method(:name) or just proc {...}).
+  # This should be fine if you're setting up handlers with the prepend_handler
+  # method, but if you get "clever," you're on your own.
+  def handle(event, *arguments)
+    # Don't bother with anything if there are no handlers registered.
+    return unless Array === @handlers[event]
+
+    report "+++EVENT HANDLER: Handling event #{event} via #{@handlers[event].inspect}:" if @loud
+
+    # To allow others to modify args without messing up potentially important
+    # internal data, dupe the array using a deep copy.  Hacky for sure, but
+    # effective.
+    new_args = Marshal.load(Marshal.dump(arguments))
+
+    # Call all hooks in order until one breaks the chain.  For incoming
+    # events, we want something to break the chain or else it'll likely
+    # hit a reporter.  For outgoing events, we tend to report them anyway,
+    # so no need to worry about ending the chain except when the bot wants
+    # to take full control over them.
+    result = false
+    for handler in @handlers[event]
+      result = handler.call(*new_args)
+      break if result == true
+    end
+  end
+
+  # Since numerics are so many and so varied, this method will auto-fallback
+  # to a simple report if no handler was defined.
+  def handle_numeric(number, fullactor, actor, target, text)
+    # All numerics share the same args, and rarely care about anything but
+    # text, so let's make it easier by passing a hash instead of a list
+    args = {:fullactor => fullactor, :actor => actor, :target => target}
+    base_event = :"incoming_numeric_#{number}"
+    if Array === @handlers[base_event]
+      handle(base_event, text, args)
+    else
+      # No handler = report and don't worry about it
+      report "Unknown raw #{number.to_s} from #{fullactor}: #{text}"
+    end
+  end
+
+  # Reports may not get printed in the proper order since I scrubbed the
+  # IRCSocket report capturing, but this is way more straightforward to me.
+  def report(*lines)
+    lines.each {|line| $stdout.puts "(#{Time.now.strftime('%H:%M.%S')}) #{line}"}
+  end
+end
+
+end