net-yail 1.4.6 → 1.5.1

data/examples/logger/logger_bot.rb

@@ -42,29 +42,28 @@ class LoggerBot < IRCBot
   # Add hooks on startup (base class's start method calls add_custom_handlers)
   def add_custom_handlers
     # Set up hooks
-    @irc.prepend_handler(:incoming_msg,             self.method(:_in_msg))
-    @irc.prepend_handler(:incoming_act,             self.method(:_in_act))
-    @irc.prepend_handler(:incoming_invite,          self.method(:_in_invited))
-    @irc.prepend_handler(:incoming_kick,            self.method(:_in_kick))
-
-    @irc.prepend_handler(:outgoing_join,            self.method(:_out_join))
+    @irc.on_msg       self.method(:_in_msg)
+    @irc.on_act       self.method(:_in_act)
+    @irc.on_invite    self.method(:_in_invited)
+    @irc.on_kick      self.method(:_in_kick)
+    @irc.saying_join  self.method(:_out_join)
   end
 
   private
   # Incoming message handler
-  def _in_msg(fullactor, user, channel, text)
+  def _in_msg(event)
     # check if this is a /msg command, or normal channel talk
-    if channel =~ /#{bot_name}/
-      incoming_private_message(user, text)
+    if event.pm?
+      incoming_private_message(event.nick, event.message)
     else
-      incoming_channel_message(user, channel, text)
+      incoming_channel_message(event.nick, event.channel, event.message)
     end
   end
 
-  def _in_act(fullactor, user, channel, text)
+  def _in_act(event)
     # check if this is a /msg command, or normal channel talk
-    return if (channel =~ /#{bot_name}/)
-    log_channel_message(user, channel, "#{user} #{text}")
+    return if event.pm?
+    log_channel_message(event.nick, event.channel, "#{event.nick} #{event.message}")
   end
 
   # TODO: recalls the most recent logs for a given channel by reading from
@@ -136,23 +135,23 @@ class LoggerBot < IRCBot
 
   # Invited to a channel for logging purposes - simply auto-join for now.
   # Maybe allow only @master one day, or array of authorized users.
-  def _in_invited(fullactor, actor, target)
-    join target
+  def _in_invited(event)
+    join event.channel
   end
 
   # If bot is kicked, he must rejoin!
-  def _in_kick(fullactor, actor, target, object, text)
-    if object == bot_name
+  def _in_kick(event)
+    if event.target == bot_name
       # Rejoin almost immediately - logging is important.
-      join target
+      join event.channel
     end
 
     return true
   end
 
   # We're trying to join a channel - use key if we have one
-  def _out_join(target, pass)
-    key = @passwords[target]
-    pass.replace(key) unless key.to_s.empty?
+  def _out_join(event)
+    key = @passwords[event.channel]
+    event.password.replace(key) unless key.to_s.empty?
   end
 end

data/examples/loudbot/bot_runner.rb

@@ -0,0 +1,114 @@
+# This is a demonstration of net-yail just to see what a "real" bot could do without much work.
+# Chances are good that you'll want to put things in classes and/or modules rather than go this
+# route, so take this example with a grain of salt.
+#
+# Yes, this is a very simple copy of an existing "loudbot" implementation, but using YAIL to
+# demonstrate the INCREDIBLE POWER THAT IS Net::YAIL.  Plus, plagiarism is a subset of the cool
+# crime of stealing.
+#
+# Example of running this thing:
+#     ruby bot_runner.rb --network irc.somewhere.org --channel "#bots"
+
+require 'rubygems'
+
+# Want a specific version of net/yail?  Try uncommenting this:
+# gem 'net-yail', '1.x.y'
+
+require 'net/yail'
+require 'getopt/long'
+
+# Hacks Array#shuffle and Array#shuffle! for people not using the latest ruby
+require 'shuffle'
+
+# Pulls in all of loudbot's methods - filter/callback handlers for IRC events
+require 'loudbot'
+
+# User specifies network, channel and nick
+opt = Getopt::Long.getopts(
+  ['--network', Getopt::REQUIRED],
+  ['--channel', Getopt::REQUIRED],
+  ['--nick', Getopt::REQUIRED],
+  ['--debug', Getopt::BOOLEAN]
+)
+
+# Create bot object
+@irc = Net::YAIL.new(
+  :address    => opt['network'],
+  :username   => 'Frakking Bot',
+  :realname   => 'John Botfrakker',
+  :nicknames  => [opt['nick'] || "SUPERLOUD"]
+)
+
+# Loud messages can be newline-separated strings in louds.txt or an array or hash serialized in
+# louds.yml.  If messages are an array, we convert all of them to hash keys with a score of 1.
+@messages = FileTest.exist?("louds.yml") ? YAML.load_file("louds.yml") :
+            FileTest.exist?("louds.txt") ? IO.readlines("louds.txt") :
+            {"ROCK ON WITH SUPERLOUD" => 1}
+if Array === @messages
+  dupes = @messages.dup
+  @messages = {}
+  dupes.each {|string| @messages[string.strip] = 1}
+end
+
+@random_messages = @messages.keys.shuffle
+@last_message = nil
+@dirty_messages = false
+
+# If --debug is passed on the command line, we spew lots of filth at the user
+@irc.log.level = Logger::DEBUG if opt['debug']
+
+#####
+#
+# To learn the YAIL, begin below with attentiveness to commented wording
+#
+#####
+
+# This is a filter.  Because it's past-tense ("heard"), it runs after the server's welcome message
+# has been read - i.e., after any before-filters and the main hanler happen.
+@irc.heard_welcome { |e| @irc.join(opt['channel']) if opt['channel'] }
+
+# on_xxx means it's a callback for an incoming event.  Callbacks run after before-filters, and
+# replaces any existing incoming invite callback.  YAIL has very few built-in callbacks, so
+# this is a safe operation.
+@irc.on_invite { |e| @irc.join(e.channel) }
+
+# This is just another callback, using the do/end block form.  We auto-message the channel on join.
+@irc.on_join do |e|
+  @irc.msg(e.channel, "WHATS WRONG WITH BEING SEXY") if e.nick == @irc.me
+end
+
+# You should *never* override the on_ping callback unless you handle the PONG manually!!
+# Filters, however, are perfectly fine.
+#
+# Here we're using the ping filter to actually do the serialization of our messages hash.  Since
+# we know pings are regular, this is kind of a hack to serialize every few minutes.
+@irc.heard_ping do
+  unless @dirty_messages
+    File.open("louds.yml", "w") {|f| f.puts @messages.to_yaml}
+    @dirty_messages = false
+  end
+end
+
+# This is a before-filter - using the present tense means it's a before-filter, and using a tense
+# of "hear" means it's for incoming messages (as opposed to "saying" and "said", where we'd filter
+# our outgoing messages).  Here we intercept all potential commands and send them to a method.
+@irc.hearing_msg {|e| do_command($1, e) if e.message =~ /^!(.*)$/ }
+
+# Another filter, but in-line this time - we intercept messages directly to the bot.  The call to
+# +handled!+ tells the event not to run any more filters or the main callback.
+@irc.hearing_msg do |e|
+  if e.message =~ /^#{@irc.me}/
+    random_message(e.channel)
+    e.handled!
+  end
+end
+
+# This is our primary message callback.  We know our filters have caught people talking to us and
+# any command-style messages, so we don't need to worry about those situations here.  The decision
+# to make this the primary callback is pretty arbitrary - do what makes the most sense to you.
+#
+# Note that this is a proc-based filter - we handle the message entirely in incoming_message.
+@irc.on_msg self.method(:incoming_message)
+
+# Start the bot - the bang (!) calls the version of start_listening that runs an endless loop
+@irc.start_listening!

data/examples/loudbot/loudbot.rb

@@ -0,0 +1,87 @@
+# Stores a LOUD message into the hash and responds.
+def it_was_loud(message, channel)
+  @irc.log.debug "IT WAS LOUD!  #{message.inspect}"
+
+  @messages[message] ||= 1
+  random_message(channel)
+end
+
+# This is our main message handler.
+#
+# We store and respond if messages meet the following criteria:
+# * It is long (11 characters or more)
+# * It has at least one space
+# * It has no lowercase letters
+# * At least 60% of the characters are uppercase letters
+def incoming_message(e)
+  # We don't respond to "private" messages
+  return if e.pm?
+
+  text = e.message
+
+  return if text =~ /[a-z]/
+
+  # Count various exciting things
+  len = text.length
+  uppercase_count = text.scan(/[A-Z]/).length
+  space_count = text.scan(/\s/).length
+
+  if len >= 11 && uppercase_count >= (len * 0.60) && space_count >= 1
+    it_was_loud(e.message, e.channel)
+  end
+end
+
+# Pulls a random message from our messages array and sends it to the given channel.  Reshuffles
+# the main array if the randomized array is empty.
+def random_message(channel)
+  @random_messages = @messages.keys.shuffle if @random_messages.empty?
+  @last_message = @random_messages.pop
+  @irc.msg(channel, @last_message)
+end
+
+# Just keepin' the plagiarism alive, man.  At least in my version, size is always based on requester.
+def send_dong(channel, user_hash)
+  old_seed = srand(user_hash)
+  @irc.msg(channel, "8" + ('=' * (rand(20).to_i + 8)) + "D")
+  srand(old_seed)
+end
+
+# Adds +value+ to the score of the last message, if there was one.  If the score goes too low, we
+# remove that message forever.
+def vote(value)
+  return unless @last_message
+
+  @messages[@last_message] += value
+  if @messages[@last_message] <= -1
+    @last_message = nil
+    @messages.delete(@last_message)
+  end
+  @dirty_messages = true
+end
+
+# Reports the last message's score
+def score(channel)
+  if !@last_message
+    @irc.msg(channel, "NO LAST MESSAGE OR IT WAS DELETED BY !DOWNVOTE")
+    return
+  end
+
+  @irc.msg(channel, "#{@last_message}: #{@messages[@last_message]}")
+end
+
+# Handles a command (string begins with ! - to keep with the pattern, I'm making our loudbot only
+# respond to loud commands)
+def do_command(command, e)
+  case command
+    when "DONGME"         then send_dong(e.channel, e.msg.user.hash + e.msg.host.hash)
+    when "UPVOTE"         then vote(1)
+    when "DOWNVOTE"       then vote(-1)
+    when "SCORE"          then score(e.channel)
+    when "HELP"           then @irc.msg(e.channel, "I HAVE COMMANDS AND THEY ARE !DONGME !UPVOTE !DOWNVOTE !SCORE AND !HELP")
+  end
+
+  # Here we're saying that we don't want any other handling run - no filters, no handler.  For
+  # commands, I put this here because I know I don't want any other handlers having to deal with
+  # strings beginning with a bang.
+  e.handled!
+end

data/examples/loudbot/shuffle.rb

@@ -0,0 +1,17 @@
+# Dynamically adds Array shuffling as described in http://www.ruby-forum.com/topic/163649
+class Array
+  # Shuffle the array
+  def shuffle!
+    n = length
+    for i in 0...n
+      r = Kernel.rand(n-i)+i
+      self[r], self[i] = self[i], self[r]
+    end
+    self
+  end
+
+  # Return a shuffled copy of the array
+  def shuffle
+    dup.shuffle!
+  end
+end

data/examples/simple/dumbbot.rb

@@ -1,4 +1,8 @@
 require 'rubygems'
+
+# Want a specific version of net/yail?  Try uncommenting this:
+# gem 'net-yail', '1.x.y'
+
 require 'net/yail'
 require 'getopt/long'
 
@@ -13,13 +17,14 @@ irc = Net::YAIL.new(
   :address    => opt['network'],
   :username   => 'Frakking Bot',
   :realname   => 'John Botfrakker',
-  :nicknames  => [opt['nick']],
-  :loud       => opt['loud']
+  :nicknames  => [opt['nick']]
 )
 
+irc.log.level = Logger::DEBUG if opt['loud']
+
 # Register handlers
-irc.prepend_handler(:incoming_welcome) {|text, args| irc.join('#bots') }
-irc.prepend_handler(:incoming_invite) {|full, user, channel| irc.join(channel) }
+irc.heard_welcome { |e| irc.join('#bots') }       # Filter - runs after the server's welcome message is read
+irc.on_invite     { |e| irc.join(e.channel) }     # Handler - runs on an invite message
 
 # Start the bot and enjoy the endless loop
 irc.start_listening!

data/lib/net/yail.rb

@@ -9,6 +9,7 @@ require 'logger'
 require 'net/yail/magic_events'
 require 'net/yail/default_events'
 require 'net/yail/output_api'
+require 'net/yail/legacy_events'
 
 # This tells us our version info.
 require 'net/yail/yail-version'
@@ -25,215 +26,234 @@ module Net
 # This library is based on the initial release of IRCSocket with a tiny bit
 # of plagarism of Ruby-IRC.
 #
+# Need an example?  For a separate project you can play with that relies on Net::YAIL, check out
+# https://github.com/Nerdmaster/superloud.  This is based on the code in the examples directory,
+# but is easier to clone, run, and tinker with because it's a separate github project.
+#
 # 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_any(raw) - "global" handler that catches all events and may
-#   modify their data as necessary before the real handler is hit.  This should
-#   only be used in cases where it's necessary to grab a lot of events that
-#   also need to be processed elsewhere, such as doing input filtering for
-#   all events that have a "text" element.  Note that returning true from
-#   this handler will still break the entire chain of event handling.
-# * :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_invite(fullactor, actor, target) - INVITE to target channel from actor
-# * :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_topic_change(fullactor, actor, channel, text) - actor sets channel topic to given text string
-# * :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.
-#
-# Note that in all cases below, the client is *about* to perform an action.
-# Text can be filtered, things can be logged, but keep in mind that the action
-# has not yet happened.
-#
-# 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, pass) - About to attempt to join target channel with
-#   given password (pass is '' if not specified in the join() command)
-# * :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.
-# * :outgoing_pass(password) - The client is about to send a password to the
-#   server via PASS.
-# * :outgoing_oper(user, password) - The client is about to request ops from
-#   the server via OPER.
-# * :outgoing_topic(channel, new_topic) - If new_topic is blank (nil or ''),
-#   the client is requesting the channel's topic, otherwise setting it.
-# * :outgoing_names(channel) - Client is requesting a list of names in the
-#   given channel, or all channels and names if channel is blank.
-# * :outgoing_list(channel, server) - Client is querying channel information.
-#   I honestly don't know what server is for from RFC, but asking for a
-#   specific channel gives just data on that channel.
-# * :outgoing_invite(nick, channel) - Client is sending an INVITE message to
-#   nick for channel.
-# * :outgoing_kick(nick, channel, comment) - Client is about to kick the user
-#   from the channel with an optional comment.
-#
-# 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 {|text, args|
-#     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(text, args)
-#     @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 logger bot (under the examples directory of this project)
-# for use of the IRCBot base class.  It's a fully working bot example with
-# real-world use.
+# =Events overview
+#
+# YAIL at its core is an event handler with some logic specific to IRC socket messages.  BaseEvent
+# is the parent of all event objects.  An event is run through various pre-callback filters, a
+# single callback, and post-callback filters.  Up until the post-callback filters start, the handler
+# "chain" can be stopped by calling the event's .handled! method.  It is generally advised against
+# doing this, as it will stop things like post-callback stats gathering and similar plugin-friendly
+# features, but it does make sense in certain situations (an "ignore user" module, for instance).
+#
+# The life of a typical event, such as the one generated when a server message is parsed into a Net::YAIL::IncomingEvent object:
+#
+# * If the event hasn't been handled, the event's callback is run
+# * If the event hasn't been handled, legacy handlers are run if any are registered (TO BE REMOVED IN 2.0)
+#   * Legacy handlers can return true to end the chain, much like calling <tt>BaseEvent#handle!</tt> on an event object
+# * If the event hasn't been handled, all "after filters" are run (these cannot set an event as having been handled)
+#
+# ==Callbacks and Filters
+#
+# Callbacks and filters are basically handlers for a given event.  The difference in a callback
+# and filter is explained above (1 callback per event, many filters), but at their core they are
+# just code that handles some aspect of the event.
+#
+# All handlers require some block of code.  You can explicitly create a Proc object, use
+# Something.method, or just pass in a block.  The block yields the event object which will have
+# all relevant data for the event.  See the examples below for a basic idea.
+#
+# To register an event's callback, you have the following options:
+# * <tt>set_callback(event_type, method = nil, &block)</tt>: Sets the event type's callback, clobbering any
+#   existing callback for that event type.
+# * <tt>on_xxx(method = nil, &block)</tt>: For incoming events only, this is a shortcut for <tt>set_callback</tt>.
+#   The "xxx" must be replaced by the incoming event's short type name.  For example,
+#   <tt>on_welcome {|event| ...}</tt> would be used in place of <tt>set_callback(:incoming_welcome, xxx)</tt>.
+#
+# To register a before- or after-callback filter:
+# * <tt>before_filter(event_type, method = nil, &block)</tt>: Sets a before-callback filter, adding it to
+#   the current list of before-callback filters for the given event type.
+# * <tt>after_filter(event_type, method = nil, &block)</tt>: Sets an after-callback filter, adding it to
+#   the current list of after-callback filters for the given event type.
+# * <tt>hearing_xxx(method = nil, &block)</tt>: Adds a before-callback filter for the given incoming event
+#   type, such as <tt>hearing_msg {|event| ...}</tt>
+# * <tt>heard_xxx(method = nil, &block)</tt>: Adds an after-callback filter for the given incoming event
+#   type, such as <tt>heard_msg {|event| ...}</tt>
+# * <tt>saying_xxx(method = nil, &block)</tt>: Adds a before-callback filter for the given outgoing event
+#   type, such as <tt>saying_mode {|event| ...}</tt>
+# * <tt>said_xxx(method = nil, &block)</tt>: Adds an after-callback filter for the given outgoing event
+#   type, such as <tt>said_act {|event| ...}</tt>
+#
+# ==Incoming events
+#
+# *All* incoming events will have, at the least, the following methods:
+# * <tt>raw</tt>: The raw text sent by the IRC server
+# * <tt>msg</tt>: The parsed IRC message (Net::YAIL::MessageParser instance)
+# * <tt>server?</tt>: Boolean flag.  True if the message was generated by the server alone, false if it
+#   was generated by some kind of user action (such as a PRIVMSG sent from somebody else)
+# * <tt>from</tt>: Originator of message: user's nickname if a user message, server name otherwise
+#
+# Additionally, *all messages originated by another IRC user* will have these methods:
+# * <tt>fullname</tt>: The full username ("Nerdmaster!jeremy@nerdbucket.com", for instance)
+# * <tt>nick</tt>: The short nickname of a user ("Nerdmaster", for instance) - this will be the
+#   same as <tt>event.from</tt>, but obviously only for user-initiated events.
+#
+# Messages sent by the server that weren't initiated by a user will have <tt>event.servername</tt>,
+# which is merely the name of the server, and will be the same as <tt>event.from</tt>.
+#
+# When in doubt, you can always build a filter for a particular event that spits out all its
+# non-base methods:
+#     yail.hearing_xxx {|e| puts e.public_methods - Net::YAIL::BaseEvent.instance_methods}
+#
+# This should be a comprehensive list of all incoming events and what additional attributes the
+# object will expose.
+#
+# * <tt>:incoming_any</tt>: A catch-all handler useful for reporting or doing top-level filtering.
+#   Before- and after-callback filters can run for all events by adding them to :incoming_any, but
+#   you cannot register a callback, as the event's type determines its callback.  :incoming_any
+#   before-callback filters can stop an event from happening on a global scale, so be careful when
+#   deciding to do anything "clever" here.
+# * <tt>:incoming_error</tt>: A server error of some kind happened.  <tt>event.message</tt> gives you the message sent
+#   by the server.
+# * <tt>:incoming_ping</tt>: PING from server.  YAIL handles this by default, so if you override the
+#   handler, you MUST send a PONG response or the server will close your connection.  <tt>event.message</tt>
+#   may have a PING "message" in it.  The return PONG should send out the same message as the PING
+#   received.
+# * <tt>:incoming_topic_change</tt>: The topic of a channel was changed.  <tt>event.channel</tt> gives you the
+#   channel in which the change occurred, while <tt>event.message</tt> gives you the message, i.e. the new topic.
+# * <tt>:incoming_numeric_###</tt>: If you want, you can set up your handlers for numeric events by number,
+#   but you'll have a much easier time looking at the eventmap.yml file included in the lib/net/yail
+#   directory.  You can create an incoming handler for any event in that file.  The event names will
+#   be <tt>:incoming_xxx</tt>, where "xxx" is the text of the event.  For instance, you could use
+#   <tt>set_callback(:incoming_liststart) {|event| ...}</tt> to handle the 321 numeric message, or just
+#   <tt>on_liststart {|event| ...}</tt>.  Exposes <tt>event.target</tt>, <tt>event.parameters</tt>,
+#   <tt>event.message</tt>, and <tt>event.numeric</tt>.  You may have to experiment with different
+#   numerics to see what this data actually means for a given event.
+# * <tt>:incoming_invite</tt>: INVITE message sent from a user to request your presence in another channel.
+#   Exposes <tt>event.channel</tt>, the channel in question, and <tt>event.target</tt>, which should always be
+#   your nickname.
+# * <tt>:incoming_join</tt>: A user joined a channel.  <tt>event.channel</tt> tells you the channel.
+# * <tt>:incoming_part</tt>: A user left a channel.  <tt>event.channel</tt> tells you the channel, and
+#   <tt>event.message</tt> will contain a message if the user gave one.
+# * <tt>:incoming_kick</tt>: A user was kicked from a channel.  <tt>event.channel</tt> tells you
+#   the channel, <tt>event.target</tt> tells you the nickname of the kicked party, and
+#   <tt>event.message</tt> will contain a message if the kicking party gave one.
+# * <tt>:incoming_quit</tt>: A user quit the server.  <tt>event.message</tt> will have details, if the
+#   user provided a quit message.
+# * <tt>:incoming_nick</tt>: A user changed nicknames.  <tt>event.message</tt> will contain the new
+#   nickname.
+# * <tt>:incoming_mode</tt>: A user or server can initiate this, and this is the most screwy event
+#   in YAIL.  This needs an overhaul and will hopefully change by 2.0, but for now I take the raw
+#   mode strings, such as "+bivv" and put them in <tt>event.message</tt>.  All arguments of the
+#   mode strings get stored as individual records in the <tt>event.targets</tt> array.  For modes
+#   like "+ob", the first entry in targets will be the user given ops, and the second will be the
+#   ban string.  I hope to overhaul this prior to 2.0, so if you rely on mode parsing, be warned.
+# * <tt>:incoming_msg</tt>: A "standard" PRIVMSG event (i.e., not CTCP).  <tt>event.message</tt> will
+#   contain the message, obviously.  If the message is to a channel, <tt>event.channel</tt>
+#   will contain the channel name, <tt>event.target</tt> will be nil, and <tt>event.pm?</tt> will
+#   be false.  If the message is sent to a user (the client running Net::YAIL),
+#   <tt>event.channel</tt> will be nil, <tt>event.target</tt> will have the user name, and
+#   <tt>event.pm?</tt> will be true.
+# * <tt>:incoming_ctcp</tt>: The behavior of <tt>event.target</tt>, <tt>event.channel</tt>, and
+#   <tt>event.pm?</tt> will remain the same as for <tt>:incoming_msg</tt> events.
+#   <tt>event.message</tt> will contain the CTCP message.
+# * <tt>:incoming_act</tt>: The behavior of <tt>event.target</tt>, <tt>event.channel</tt>, and
+#   <tt>event.pm?</tt> will remain the same as for <tt>:incoming_msg</tt> events.
+#   <tt>event.message</tt> will contain the ACTION message.
+# * <tt>:incoming_notice</tt>: The behavior of <tt>event.target</tt>, <tt>event.channel</tt>, and
+#   <tt>event.pm?</tt> will remain the same as for <tt>:incoming_msg</tt> events.
+#   <tt>event.message</tt> will contain the NOTICE message.
+# * <tt>:incoming_ctcp_reply</tt>: The behavior of <tt>event.target</tt>, <tt>event.channel</tt>,
+#   and <tt>event.pm?</tt> will remain the same as for <tt>:incoming_msg</tt> events.
+#   <tt>event.message</tt> will contain the CTCP reply message.
+# * <tt>:incoming_unknown</tt>: This should NEVER happen, but just in case, it's there.  Enjoy!
+#
+# ==Output API
+#
+# All output API calls create a Net::YAIL::OutgoingEvent object and dispatch that event.  After
+# before-callback filters are processed, assuming the event wasn't handled, the callback will send
+# the message out to the IRC socket.  If you choose to override the callback for outgoing events,
+# rather than using filters, you will have to print the data to the socket yourself.
+#
+# The parameters for the API calls will match what the outgoing event object exposes as attributes,
+# so if there were an API call for "foo(bar, baz)", it would generate an outgoing event of type
+# :outgoing_foo.  The data you passed in as "bar" would be available via <tt>event.bar</tt> in a handler.
+#
+# There is also an :outgoing_any event type that can be used for global filtering much like the
+# :incoming_any filtering.
+#
+# The <tt>:outgoing_begin_connection</tt> event callback should never be overwritten.  It exists so
+# you can add filters before or after the initial flurry of messages to the server (USER, PASS, and
+# NICK), but it is really an internal "helper" event.  Overwriting it means you will need to write
+# your own code to log in to the server.
+#
+# This should be a comprehensive list of all outgoing methods and parameters:
+#
+# * <tt>msg(target, message)</tt>: Send a PRIVMSG to the given target (channel or nickname)
+# * <tt>ctcp(target, message)</tt>: Sends a PRIVMSG to the given target with its message wrapped in
+#   ASCII character 1, signifying use of client-to-client protocol.
+# * <tt>act(target, message)</tt>: Sends a PRIVMSG to the given target with its message wrapped in the
+#   CTCP "action" syntax.  A lot of IRC clients use "/me" to do this command.
+# * <tt>privmsg(target, message)</tt>: Sends a raw, unbuffered PRIVMSG to the given target - primarily
+#   useful for filtering, as msg, act, and ctcp all eventually call this handler.
+# * <tt>notice(target, message)</tt>: Sends a notice message to the given target
+# * <tt>ctcpreply(target, message)</tt>: Sends a notice message wrapped in ASCII 1 to signify a CTCP reply.
+# * <tt>mode(target, [modes, [objects]])</tt>: Sets or requests modes for the given target
+#   (channel or user).  The list of modes, if present, is applied to the target and objects if
+#   present.  Modes in YAIL need some work, but here are some basic examples:
+#   * <tt>mode("#channel", "+b", "Nerdmaster!*@*")</tt>: bans anybody with the nickname
+#     "Nerdmaster" from subsequently joining #channel.
+#   * <tt>mode("#channel")</tt>: Requests a list of modes on #channel
+#   * <tt>mode("#channel", "-k")</tt>: Removes the key for #channel
+# * <tt>join(channel, [password])</tt>: Joins the given channel with an optional password (channel key)
+# * <tt>part(channel, [message])</tt>: Leaves the given channel, with an optional message specified on part
+# * <tt>quit([message])</tt>: Leaves the server with an optional message.  Note that some servers will
+#   not display your quit message due to spam issues.
+# * <tt>nick(nick)</tt>: Changes your nickname, and updates YAIL @me variable if successful
+# * <tt>user(username, hostname, servername, realname)</tt>: Sets up your information upon joining
+#   a server.  YAIL should generally take care of this for you in the default :outgoing_begin_connection
+#   callback.
+# * <tt>pass(password)</tt>: Sends a server password, not to be confused with a channel key.
+# * <tt>oper(user, password)</tt>: Authenticates a user as an IRC operator for the server.
+# * <tt>topic(channel, [new_topic])</tt>: With no new_topic, returns the topic for a given channel.
+#   If new_topic is present, sets the topic instead.
+# * <tt>names([channel])</tt>: Gets a list of all users on the network or a specific channel if specified.
+#   The channel parameter can actually contain a comma-separated list of channels if desired.
+# * <tt>list([channel, [server]]</tt>: Shows all channels on the server.  <tt>channel</tt> can
+#   contain a comma-separated list of channels, which will restrict the list to the given channels.
+#   If <tt>server</tt> is present, the request is forwarded to the given server.
+# * <tt>invite(nick, channel)</tt>: Invites a user to the given channel.
+# * <tt>kick(nick, channel, [message])</tt>: "KICK :channel :nick", :nick, :channel, :reason, " ::reason"
+#
+# =Simple Example
+#
+# You should grab the source from github (https://github.com/Nerdmaster/ruby-irc-yail) and look at
+# the examples directory for more interesting (but still simple) examples.  But to get you started,
+# here's a really dumb, contrived example:
+#
+#     require 'rubygems'
+#     require 'net/yail'
+#     
+#     irc = Net::YAIL.new(
+#       :address    => 'irc.someplace.co.uk',
+#       :username   => 'Frakking Bot',
+#       :realname   => 'John Botfrakker',
+#       :nicknames  => ['bot1', 'bot2', 'bot3']
+#     )
+#     
+#     # Automatically join #foo when the server welcomes us
+#     irc.on_welcome {|event| irc.join("#foo") }
+#
+#     # Store the last message and person who spoke - this is a filter as it doesn't need to be
+#     # "the" definitive code run for the event
+#     irc.hearing_msg {|event| @last_message = {:nick => event.nick, :message => event.message} }
+#
+#     # Loops forever until CTRL+C
+#     irc.start_listening!
 class YAIL 
   include Net::IRCEvents::Magic
   include Net::IRCEvents::Defaults
   include Net::IRCOutputAPI
+  include Net::IRCEvents::LegacyEvents
 
   attr_reader(
     :me,                # Nickname on the IRC server
@@ -248,20 +268,20 @@ class YAIL
   )
 
   def silent
-    @log.warn '[DEPRECATED] - Net::YAIL#silent is deprecated as of 1.4.1'
+    @log.warn '[DEPRECATED] - Net::YAIL#silent is deprecated as of 1.4.1 - .log can be used instead'
     return @log_silent
   end
   def silent=(val)
-    @log.warn '[DEPRECATED] - Net::YAIL#silent= is deprecated as of 1.4.1'
+    @log.warn '[DEPRECATED] - Net::YAIL#silent= is deprecated as of 1.4.1 - .log can be used instead'
     @log_silent = val
   end
 
   def loud
-    @log.warn '[DEPRECATED] - Net::YAIL#loud is deprecated as of 1.4.1'
+    @log.warn '[DEPRECATED] - Net::YAIL#loud is deprecated as of 1.4.1 - .log can be used instead'
     return @log_loud
   end
   def loud=(val)
-    @log.warn '[DEPRECATED] - Net::YAIL#loud= is deprecated as of 1.4.1'
+    @log.warn '[DEPRECATED] - Net::YAIL#loud= is deprecated as of 1.4.1 - .log can be used instead'
     @log_loud = val
   end
 
@@ -309,6 +329,29 @@ class YAIL
     @password           = options[:server_password]
     @ssl                = options[:use_ssl] || false
 
+    #############################################
+    # TODO: DEPRECATED!!
+    #
+    # TODO: Delete this!
+    #############################################
+    @legacy_handlers = Hash.new
+
+    # 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 callback/filter hashes
+    @before_filters = Hash.new
+    @after_filters = Hash.new
+    @callback = Hash.new
+
     # Special handling to avoid mucking with Logger constants if we're using a different logger
     if options[:log]
       @log = options[:log]
@@ -331,36 +374,13 @@ class YAIL
     eventmap = "#{File.dirname(__FILE__)}/yail/eventmap.yml"
     @event_number_lookup = File.open(eventmap) { |file| YAML::load(file) }.invert
 
-    # We're not dead... yet...
-    @dead_socket = false
-
-    # Build our socket - if something goes wrong, it's immediately a dead socket.
     if @io
       @socket = @io
     else
-      begin
-        @socket = TCPSocket.new(@address, @port)
-        setup_ssl if @ssl
-      rescue StandardError => boom
-        @log.fatal "+++ERROR: Unable to open socket connection in Net::YAIL.initialize: #{boom.inspect}"
-        @dead_socket = true
-        raise
-      end
+      prepare_tcp_socket
     end
 
-    # 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
+    set_defaults
   end
 
   # Starts listening for input and builds the perma-threads that check for
@@ -375,23 +395,19 @@ class YAIL
     # Exit a bit more gracefully than just crashing out - allow any :outgoing_quit filters to run,
     # and even give the server a second to clean up before we fry the connection
     #
-    # TODO: perhaps this should be in a callback so user can override TERM/INT handling
+    # TODO: This REALLY doesn't belong here!  This is saying everybody who uses the lib wants
+    #       CTRL+C to end the app at the YAIL level.  Not necessarily true outside bot-land.
     quithandler = lambda { quit('Terminated by user'); sleep 1; stop_listening; exit }
     trap("INT", quithandler)
     trap("TERM", quithandler)
 
-    # 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)
+    # Let's begin the cycle by telling the server who we are.  This should start a TERRIBLE CHAIN OF EVENTS!!!
+    dispatch OutgoingEvent.new(:type => :begin_connection, :username => @username, :address => @address, :realname => @realname)
   end
 
   # This starts the connection, threading, etc. as start_listening, but *forces* the user into
@@ -428,6 +444,71 @@ class YAIL
 
   private
 
+  # Sets up all default filters and callbacks
+  def set_defaults
+    # Set up callbacks for slightly more important things than reporting - note that these should
+    # eventually be changed as they don't belong in the core of YAIL.  Note that since these are
+    # callbacks, the user can very easily overwrite them, at least.
+    on_nicknameinuse self.method(:_nicknameinuse)
+    on_namreply self.method(:_namreply)
+
+    # Set up truly core handlers/filters - these shouldn't be overridden unless users like to get
+    # their hands dirty
+    set_callback(:outgoing_begin_connection, self.method(:out_begin_connection))
+    on_ping self.method(:magic_ping)
+
+    # Nick change magically setting @me is necessary as a filter - user can handle the event and do
+    # anything he wants, but this should still run.
+    hearing_nick self.method(:magic_nick)
+
+    # Welcome magic also sets @me magically, so it's a filter
+    hearing_welcome self.method(:magic_welcome)
+
+    # Outgoing handlers are what make this app actually work - users who override these have to
+    # do so very explicitly (no "on_xxx" magic) and will probably break stuff.  Use filters instead!
+
+    # These three need magic to buffer their output, so can't use our simpler create_command system
+    set_callback :outgoing_msg, self.method(:magic_out_msg)
+    set_callback :outgoing_ctcp, self.method(:magic_out_ctcp)
+    set_callback :outgoing_act, self.method(:magic_out_act)
+
+    # All PRIVMSG events eventually hit this - it's a legacy thing, and kinda dumb, but there you
+    # have it.  Just sends a raw PRIVMSG out to the socket.
+    create_command :privmsg, "PRIVMSG :target ::message", :target, :message
+
+    # The rest of these should be fairly obvious
+    create_command :notice, "NOTICE :target ::message", :target, :message
+    create_command :ctcpreply, "NOTICE :target :\001:message\001", :target, :message
+    create_command :mode,   "MODE", :target, " :target", :modes, " :modes", :objects, " :objects"
+    create_command :join,   "JOIN :channel", :channel, :password, " :password"
+    create_command :part,   "PART :channel", :channel, :message, " ::message"
+    create_command :quit,   "QUIT", :message, " ::message"
+    create_command :nick,   "NICK ::nick", :nick
+    create_command :user,   "USER :username :hostname :servername ::realname", :username, :hostname, :servername, :realname
+    create_command :pass,   "PASS :password", :password
+    create_command :oper,   "OPER :user :password", :user, :password
+    create_command :topic,  "TOPIC :channel", :channel, :topic, " ::topic"
+    create_command :names,  "NAMES", :channel, " :channel"
+    create_command :list,   "LIST", :channel, " :channel", :server, " :server"
+    create_command :invite, "INVITE :nick :channel", :nick, :channel
+    create_command :kick,   "KICK :channel :nick", :nick, :channel, :message, " ::message"
+  end
+
+  # Prepares @socket for use and defaults @dead_socket to false
+  def prepare_tcp_socket
+    @dead_socket = false
+
+    # Build our socket - if something goes wrong, it's immediately a dead socket.
+    begin
+      @socket = TCPSocket.new(@address, @port)
+      setup_ssl if @ssl
+    rescue StandardError => boom
+      @log.fatal "+++ERROR: Unable to open socket connection in Net::YAIL.initialize: #{boom.inspect}"
+      @dead_socket = true
+      raise
+    end
+  end
+
   # If user asked for SSL, this is where we set it all up
   def setup_ssl
     require 'openssl'
@@ -480,7 +561,7 @@ class YAIL
   end
 
   # This should be called from a thread only!  Does nothing but listens
-  # forever for incoming data, and calling handlers due to this listening
+  # forever for incoming data, and calling filters/callback due to this listening
   def io_loop
     loop do
       # Possible fix for SSL one-message-behind issue from BP - thanks!
@@ -515,11 +596,12 @@ class YAIL
         @input_buffer.clear
       end
 
-      if (lines)
+      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)
+        until lines.empty?
+          event = Net::YAIL::IncomingEvent.parse(lines.shift)
+          dispatch(event)
         end
 
         lines = nil
@@ -530,9 +612,9 @@ class YAIL
   end
 
   # Grabs one message for each target in the private message buffer, removing
-  # messages from @privmsg_buffer.  Returns a hash array of target -> text
+  # messages from @privmsg_buffer.  Returns an array of events to process
   def pop_privmsgs
-    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....
@@ -545,23 +627,18 @@ class YAIL
           next
         end
 
-        privmsgs[target] = @privmsg_buffer[target].shift
+        privmsgs.push @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
+  # Checks for new private messages, and dispatches 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
+    privmsgs.each {|event| dispatch event}
   end
 
   # Our final thread loop - grabs the first privmsg for each target and
@@ -574,158 +651,135 @@ class YAIL
     end
   end
 
-  # Gets some input, sends stuff off to a handler.  Yay.
-  def process_input(line)
-    # Allow global handler to break the chain, filter the line, whatever.  For
-    # this release, it's a hack.  2.0 will be better.
-    if (Array === @handlers[:incoming_any])
-      for handler in @handlers[:incoming_any]
-        result = handler.call(line)
-        return if result == true
-      end
-    end
-
-    # Use the exciting new-new parser
-    event = Net::YAIL::IncomingEvent.parse(line)
-
-    # Partial conversion to using events - we still have a horrible case statement, but
-    # we're at least using the event object.  Slightly less hacky than before.
-
-    # Except for this - we still have to handle numerics the crappy way until we build the proper
-    # dispatching of events
-    event = event.parent if event.parent && :incoming_numeric == event.parent.type
-
-    case event.type
-      # Ping is important to handle quickly, so it comes first.
-      when :incoming_ping
-        handle(event.type, event.text)
-
-      when :incoming_numeric
-        # Lovely - I passed in a "nick" - which, according to spec, is NEVER part of a numeric reply
-        handle_numeric(event.numeric, event.servername, nil, event.target, event.text)
-
-      when :incoming_invite
-        handle(event.type, event.fullname, event.nick, event.channel)
+  ##################################################
+  # EVENT HANDLING ULTRA SUPERSYSTEM DELUXE!!!
+  ##################################################
 
-      # Fortunately, the legacy handler for all five "message" types is the same!
-      when :incoming_msg, :incoming_ctcp, :incoming_act, :incoming_notice, :incoming_ctcpreply
-        # Legacy handling requires merger of target and channel....
-        target = event.target if event.pm?
-        target = event.channel if !target
+  public
+  # Prepends the given block or method to the before_filters array for the given type.  Before-filters are called
+  # before the event callback has run, and can stop the event (and other filters) from running by calling the event's
+  # end_chain() method.  Filters shouldn't do this very often!  Before-filtering can modify output text before the
+  # event callback runs, ignore incoming events for a given user, etc.
+  def before_filter(event_type, method = nil, &block)
+    filter = block_given? ? block : method
+    if filter
+      event_type = numeric_event_type_convert(event_type)
+      @before_filters[event_type] ||= Array.new
+      @before_filters[event_type].unshift(filter)
+    end
+  end
 
-        # Notices come from server sometimes, so... another merger for legacy fun!
-        nick = event.server? ? '' : event.nick
-        handle(event.type, event.from, nick, target, event.text)
+  # Sets up the callback for the given incoming event type.  Note that unlike Net::YAIL 1.4.x and prior, there is no
+  # longer a concept of multiple callbacks!  Use filters for that kind of functionality.  Think this way: the callback
+  # is the action that takes place when an event hits.  Filters are for functionality related to the event, but not
+  # the definitive callback - logging, filtering messages, stats gathering, ignoring messages from a set user, etc.
+  def set_callback(event_type, method = nil, &block)
+    callback = block_given? ? block : method
+    event_type = numeric_event_type_convert(event_type)
+    @callback[event_type] = callback
+    @callback.delete(event_type) unless callback
+  end
 
-      # This is a bit painful for right now - just use some hacks to make it work semi-nicely,
-      # but let's not put hacks into the core Event object.  Modes need reworking soon anyway.
-      #
-      # NOTE: text is currently the mode settings ('+b', for instance) - very bad.  TODO: FIX FIX FIX!
-      when :incoming_mode
-        # Modes can come from the server, so legacy system again regularly sent nil data....
-        nick = event.server? ? '' : event.nick
-        handle(event.type, event.from, nick, event.channel, event.text, event.targets.join(' '))
+  # Prepends the given block or method to the after_filters array for the given type.  After-filters are called after
+  # the event callback has run, and cannot stop other after-filters from running.  Best used for logging or statistics
+  # gathering.
+  def after_filter(event_type, method = nil, &block)
+    filter = block_given? ? block : method
+    if filter
+      event_type = numeric_event_type_convert(event_type)
+      @after_filters[event_type] ||= Array.new
+      @after_filters[event_type].unshift(filter)
+    end
+  end
 
-      when :incoming_topic_change
-        handle(event.type, event.fullname, event.nick, event.channel, event.text)
+  # 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
 
-      when :incoming_join
-        handle(event.type, event.fullname, event.nick, event.channel)
+  # Converts events that are numerics into the internal "incoming_numeric_xxx" format
+  def numeric_event_type_convert(type)
+    if (type.to_s =~ /^incoming_(.*)$/)
+      number = @event_number_lookup[$1].to_i
+      type = :"incoming_numeric_#{number}" if number > 0
+    end
 
-      when :incoming_part
-        handle(event.type, event.fullname, event.nick, event.channel, event.text)
+    return type
+  end
 
-      when :incoming_kick
-        handle(event.type, event.fullname, event.nick, event.channel, event.target, event.text)
+  # Given an event, calls pre-callback filters, callback, and post-callback filters.  Uses hacky
+  # :incoming_any event if event object is of IncomingEvent type.
+  def dispatch(event)
+    # Add all before-callback stuff to our chain
+    chain = []
+    chain.push @before_filters[:incoming_any] if Net::YAIL::IncomingEvent === event
+    chain.push @before_filters[:outgoing_any] if Net::YAIL::OutgoingEvent === event
+    chain.push @before_filters[event.type]
+    chain.flatten!
+    chain.compact!
+
+    # Run each filter in the chain, exiting early if event was handled
+    for filter in chain
+      filter.call(event)
+      return if event.handled?
+    end
 
-      when :incoming_quit
-        handle(event.type, event.fullname, event.nick, event.text)
+    # Legacy handler - return if true, since that's how the old system works - EXCEPTION for outgoing events, since
+    # the old system didn't allow the outgoing "core" code to be skipped!
+    if true == legacy_process_event(event)
+      return unless Net::YAIL::OutgoingEvent === event
+    end
 
-      when :incoming_nick
-        handle(event.type, event.fullname, event.nick, event.text)
+    # Add new callback and all after-callback stuff to a new chain
+    chain = []
+    chain.push @callback[event.type]
+    chain.push @after_filters[event.type]
+    chain.push @after_filters[:incoming_any] if Net::YAIL::IncomingEvent === event
+    chain.push @after_filters[:outgoing_any] if Net::YAIL::OutgoingEvent === event
+    chain.flatten!
+    chain.compact!
+
+    # Run all after-filters blindly - none can affect callback, so after-filters can't set handled to true
+    chain.each {|filter| filter.call(event)}
+  end
 
-      when :incoming_error
-        handle(event.type, event.text)
+  # Handles magic listener setup methods: on_xxx, hearing_xxx, heard_xxx, saying_xxx, and said_xxx
+  def method_missing(name, *args, &block)
+    method = nil
+    event_type = nil
 
-      # Unknown line!
-      else
-        # This should really never happen, but isn't technically an error per se
-        @log.warn 'Unknown line: %s!' % line.inspect
-        handle(:incoming_miscellany, line)
-    end
-  end
+    case name.to_s
+      when /^on_(.*)$/
+        method = :set_callback
+        event_type = :"incoming_#{$1}"
 
-  ##################################################
-  # EVENT HANDLING ULTRA SUPERSYSTEM DELUXE!!!
-  ##################################################
+      when /^hearing_(.*)$/
+        method = :before_filter
+        event_type = :"incoming_#{$1}"
 
-  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, &block)
-    raise "Cannot change handlers while threads are listening!" if @ioloop_thread
-
-    # Allow blocks as well as procs
-    if block_given?
-      procs.push(block)
-    end
+      when /^heard_(.*)$/
+        method = :after_filter
+        event_type = :"incoming_#{$1}"
 
-    # 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
+      when /^saying_(.*)$/
+        method = :before_filter
+        event_type = :"outgoing_#{$1}"
 
-    @handlers[event] ||= Array.new
-    until procs.empty?
-      @handlers[event].unshift(procs.pop)
+      when /^said_(.*)$/
+        method = :after_filter
+        event_type = :"outgoing_#{$1}"
     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]
-
-    @log.debug "+++EVENT HANDLER: Handling event #{event} via #{@handlers[event].inspect}:"
-
-    # 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(*arguments)
-      break if result == true
-    end
-  end
+    # Magic methods MUST have an arg or a block!
+    filter_or_callback_method = block_given? ? block : args.shift
 
-  # 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
-      @log.info "Unknown raw #{number.to_s} from #{fullactor}: #{text}"
-    end
-  end
+    # If we didn't match a magic method signature, or we don't have the expected parameters, call
+    # parent's method_missing.  Just to be safe, we also return, in case YAIL one day subclasses
+    # from something that handles some method_missing stuff.
+    return super if method.nil? || event_type.nil? || args.length > 0
 
-  # 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}"}
+    self.send(method, event_type, filter_or_callback_method)
   end
 end